kubesense-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

KubeSense MCP

KubeSense MCP provides observability tools for querying logs, traces, and metrics from Kubernetes clusters.

KubeSense MCP 提供可观测性工具，用于查询Kubernetes集群中的日志、追踪数据和指标。

Tools

工具

Tool	Purpose
`get-trace-or-log-fields`	Discover available fields for logs or traces
`get-available-metrics`	Discover available metric names
`get-metric-labels`	Get label names for a specific metric
`search-logs`	Browse raw log records (max 10 rows)
`search-traces`	Browse raw trace/span records (max 10 rows)
`analyze-logs`	Run aggregated analysis on logs
`analyze-traces`	Run aggregated analysis on traces
`analyze-metrics`	Execute PromQL queries on metrics
`analyze-telemetry`	Multi-datasource queries with formula support

工具	用途
`get-trace-or-log-fields`	发现日志或追踪数据的可用字段
`get-available-metrics`	发现可用的指标名称
`get-metric-labels`	获取特定指标的标签名称
`search-logs`	浏览原始日志记录（最多10行）
`search-traces`	浏览原始追踪/跨度记录（最多10行）
`analyze-logs`	对日志执行聚合分析
`analyze-traces`	对追踪数据执行聚合分析
`analyze-metrics`	对指标执行PromQL查询
`analyze-telemetry`	支持公式的多数据源查询

Discovery-First Rule

发现优先原则

Always discover before querying. Never guess field names or metric names.

logs/traces:  get-trace-or-log-fields  →  search-logs / search-traces / analyze-logs / analyze-traces
metrics:      get-available-metrics    →  get-metric-labels  →  analyze-metrics

**查询前务必先进行发现操作。**切勿猜测字段名称或指标名称。

logs/traces:  get-trace-or-log-fields  →  search-logs / search-traces / analyze-logs / analyze-traces
metrics:      get-available-metrics    →  get-metric-labels  →  analyze-metrics

Choosing the Right Tool

选择合适的工具

Show me recent logs →
```
search-logs
```
How many errors in the last hour? →
```
analyze-logs
```
with
```
row_count
```
+ error filter
P99 latency for a service →
```
analyze-traces
```
with
```
p99
```
aggregation on
```
duration
```
CPU / memory usage →
```
get-available-metrics
```
→
```
analyze-metrics
```
Error rate as a percentage →
```
analyze-telemetry
```
with a formula query

显示最近的日志 →
```
search-logs
```
过去一小时内有多少错误？ → 使用
```
row_count
```
+错误过滤器的
```
analyze-logs
```
服务的P99延迟 → 对
```
duration
```
执行
```
p99
```
聚合的
```
analyze-traces
```
CPU/内存使用率 →
```
get-available-metrics
```
→
```
analyze-metrics
```
错误率百分比 → 使用公式查询的
```
analyze-telemetry
```

Query Types

查询类型

All

analyze-*

tools accept a

queryType

```
"range"
```
— time-series values over the given window (for trends)
```
"instant"
```
— single point-in-time snapshot (for totals/counts)

所有

analyze-*

工具都接受

queryType

参数：

```
"range"
```
— 指定时间窗口内的时间序列值（用于趋势分析）
```
"instant"
```
— 特定时间点的快照（用于总计/计数）

Time Ranges

时间范围

All tools require

from_time

and

to_time

as ISO 8601 strings, e.g.:

"from_time": "2026-04-23T10:00:00Z"
"to_time":   "2026-04-23T10:30:00Z"

Start narrow (15–30 min) and widen if needed.

所有工具都要求

from_time

和

to_time

为ISO 8601格式字符串，例如：

"from_time": "2026-04-23T10:00:00Z"
"to_time":   "2026-04-23T10:30:00Z"

建议先从较窄范围（15–30分钟）开始，必要时再扩大范围。

Filters

过滤器

The

filters

parameter in

search-logs

search-traces

analyze-logs

, and

analyze-traces

accepts a SQL-like WHERE clause.

search-logs

、

search-traces

、

analyze-logs

和

analyze-traces

中的

filters

参数接受类SQL的WHERE子句。

Operators

运算符

Operator	Example	Notes
`=`	`level = 'ERROR'`	Exact match
`!=`	`status != 'ok'`	Not equal
`>` `<` `>=` `<=`	`duration_ms > 500`	Comparisons; use unquoted numbers for float fields. Filter trace latency via `duration_ms` (ms), not the ns `duration` field
`IN`	`level IN ('ERROR', 'WARN')`	Matches any value in list
`NOT IN`	`namespace NOT IN ('kube-system')`	Excludes values in list
`LIKE`	`workload LIKE '%api%'`	`%` is wildcard
`NOT LIKE`	`pod_name NOT LIKE '%debug%'`	Negative pattern match

运算符	示例	说明
`=`	`level = 'ERROR'`	精确匹配
`!=`	`status != 'ok'`	不等于
`>` `<` `>=` `<=`	`duration_ms > 500`	比较运算；浮点数字段使用不带引号的数字。通过 `duration_ms` （毫秒）过滤追踪延迟，而非纳秒级的 `duration` 字段
`IN`	`level IN ('ERROR', 'WARN')`	匹配列表中的任意值
`NOT IN`	`namespace NOT IN ('kube-system')`	排除列表中的值
`LIKE`	`workload LIKE '%api%'`	`%` 为通配符
`NOT LIKE`	`pod_name NOT LIKE '%debug%'`	反向模式匹配

Combining Conditions

组合条件

level = 'ERROR' AND namespace = 'production'

status = 'error' AND (workload = 'api-server' OR workload = 'auth-service')

level = 'ERROR' AND namespace = 'production'

status = 'error' AND (workload = 'api-server' OR workload = 'auth-service')

Value Types

值类型

Strings — always single-quoted:
```
workload = 'my-service'
```
Numbers — unquoted:
```
duration_ms > 500
```
(filter trace latency in ms via
```
duration_ms
```
)

字符串 — 始终使用单引号包裹：
```
workload = 'my-service'
```
数字 — 无需引号：
```
duration_ms > 500
```
（通过
```
duration_ms
```
以毫秒为单位过滤追踪延迟）

Examples

示例

level IN ('ERROR', 'FATAL') AND workload LIKE '%payment%'

status = 'error' AND protocol_type = 'HTTP' AND return_code = '500'

duration_ms > 500 AND workload = 'checkout-service'

level IN ('ERROR', 'FATAL') AND workload LIKE '%payment%'

status = 'error' AND protocol_type = 'HTTP' AND return_code = '500'

duration_ms > 500 AND workload = 'checkout-service'

Datasource Skills

数据源技能

For detailed field references, examples, and query patterns, read the datasource-specific skill:

kubesense-logs — Discover fields, search raw logs, aggregate with counts/percentiles, filter syntax
kubesense-apm — Discover fields, search raw spans, analyze latency and errors, filter syntax
kubesense-metrics — Discover metrics, get labels, write PromQL queries

如需详细的字段参考、示例和查询模式，请阅读特定数据源的技能文档：

kubesense-logs — 发现字段、搜索原始日志、通过计数/百分位数进行聚合、过滤器语法
kubesense-apm — 发现字段、搜索原始跨度、分析延迟和错误、过滤器语法
kubesense-metrics — 发现指标、获取标签、编写PromQL查询

Multi-Query Reference

多查询参考

multi-query.md — Multi-datasource queries and formula expressions with
```
analyze-telemetry
```

multi-query.md — 使用
```
analyze-telemetry
```
进行多数据源查询和公式表达式