kubesense-traces

KubeSense Traces（APM）

适用于所有与请求相关的场景：延迟、p99/p95、错误率、HTTP 方法、状态码、端点、服务间调用、下游依赖。（日志行和 panic → kubesense-logs。）

需要 KubeSense MCP 服务；参见 kubesense-mcp。 工具会针对 traces 模块解析 RBAC。

工具

工具	适用场景
get-trace-or-log-fields（signal: "traces"）	始终首先使用
analyze-traces	延迟百分位数、错误率、计数、趋势
search-traces	读取单个 span
get-distributed-trace	已有 trace_id，需要完整调用链

get-distributed-trace 是这里杠杆效益最高的工具。 单个 span 能告诉你某处发生了故障；trace 则能告诉你故障发生在哪个环节，以及时间花在了哪里。

字段名称——仅限目录标签

所有输入位置都不接受存储列名。

概念	使用此标签	存储列（不接受）
服务身份	service	app_service
k8s 工作负载	workload	—
Pod	instance	pod_name
容器	container	container_name
节点	node_name	—
HTTP 方法	method	subtype
HTTP 状态码	status_code	return_code
资源／端点	resource	clustered_resource
span 角色	role	kind
协议	protocol	protocol_type
span 结果	status	—
延迟	duration	—
外部调用？	request_type	is_external
问题原因	reason	issue_reason
客户／租户	domain	customer_identifier
trace／span ID	trace_id、span_id	—
问题 ID	issue_id	—
namespace、cluster、region、app_version、env_type、source、server、client、server_namespace、client_namespace、operation_name、partner_cluster	同左	—

还会解析但不会在发现结果中显示的字段：timestamp（→ start_timestamp）、duration、primary_workload／primary_namespace（→ perspective_*）、associate_workload／associate_namespace（→ partner_*）。

service 与 workload

应用身份优先使用 service——它是跨平台标识符（Kubernetes、Docker、旧版系统均适用）。仅在确实需要 Kubernetes 拓扑时使用 workload。

说明

这与告警规则的指导原则相反：在告警规则中，workload 的分组更可靠。参见 kubesense-alerts——告警引擎会将 service 解析为一个汇总列，而该列仅对使用 SDK 进行检测的服务填充。

警告

node 在 traces 中无效——应使用 node_name。（Logs 则相反：使用 node，而非 node_name。）切勿在不同信号间沿用字段名称。

traces 中没有 body 字段。 对消息进行文本搜索仅适用于 logs。

traces 中的枚举值为小写

字段	值
status	error、ok
role	server、client
protocol	HTTP、gRPC、TCP、MongoDB、Redis、MySQL、PostgreSQL
method	GET、POST、PUT、DELETE、PATCH
source	eBPF、OTel
status_code	200、400、401、403、404、500、502、503、504

status = error——使用小写，与 logs 中大写的 type = ERROR 不同。

status_code 是字符串字段，因此即使值看起来像数字，也仍须使用带引号的字符串：status_code IN (500, 502) 会得到字符串 "500"、"502"。因此范围比较无效——请枚举状态码，或使用 status_code LIKE "5%" 匹配一类状态码。

读取 enum_values 列中的大小写信息，不要看 example——示例生成器在 method、protocol 和 status_code 对应的单元格中会返回空白。

时长：输入为 ms，输出为 ns

重要

筛选 duration 时使用毫秒。聚合 duration 时返回纳秒。 这两个单位出现在同一个字段中，弄错后不会报错。

where: "duration > 500"        →  spans slower than 500 milliseconds

解析器会将你的值乘以 1e6，以匹配纳秒存储列。因此：

目标	写法
慢于 250ms	duration > 250
慢于 1s	duration > 1000
慢于 1.5s	duration > 1.5e3 或 duration > 1500

警告

search-traces 工具描述中给出的示例 "duration > 250000" 是 错误的——它表示 250,000ms = 250 秒，因此不会匹配任何内容。请忽略此示例。

聚合的方向相反——对 fields: [{"field": "duration"}] 执行 p95/avg/max 后，返回值的单位是纳秒：

结果	含义
250000000	250ms
1000000000	1s

除以 1e6 即可换算为毫秒。MCP 层没有 duration_ms 字段—— 它会被拒绝为未知字段。

Trace 属性：仅支持分组

警告

在 traces 的 WHERE 子句中使用 @attr 不起作用。 它会被拒绝，并返回 unknown field "<key>" for signal=traces，因为解析器在 ARRAY_MAP 重映射期间清除了属性 判别符，随后该字段未通过列验证。工具描述中称 @db.system = postgresql 可以使用；实际上并不行。

只要以结构化方式传递字段，Trace 属性就可以使用——设置标志，而不是使用前缀：

"group_by_fields": [ { "field": "db.system", "is_attribute": true } ]

group_by_fields、fields、required_fields 和 sort_by 均支持。若要按属性值筛选，请按该属性分组并读取序列标签，或筛选等效的顶层列。

（Log 属性不受影响——在日志上使用 @user.id = abc 完全没问题。）

analyze-traces

{
  "from_time": "2026-07-30T10:00:00Z",
  "to_time": "2026-07-30T11:00:00Z",
  "query_type": "range",
  "group_by_fields": [ { "field": "service", "is_attribute": false } ],
  "fields": [ { "field": "duration", "is_attribute": false } ],
  "value_operation": "p95"
}

value_operation：row_count、unique_count、avg、sum、min、max、p50、p90、 p95、p99。count 无效——应使用 row_count，尽管架构的摘要行暗示可以使用 count。

问题	参数形式
按服务查看一段时间内的 p95 延迟	range，按 service 分组，fields: [duration]，p95
当前错误数最多的 5 个服务	instant，where: "status = error"，按 service 分组，row_count，sort_direction: DESC，limit: 5
按状态码统计错误	instant，where: "status = error"，按 status_code 分组，row_count
最慢的端点	instant，按 resource 分组，fields: [duration]，p99，sort_direction: DESC
仅统计服务器端	添加 where: "role = server"——否则客户端跨度会被重复计数

错误率百分比需要两个查询和一个公式 → analyze-telemetry。 请参阅 kubesense-mcp。

输出为列式 JSON：对于 range，包含一个共享的 timestamps 数组，以及每个序列中按位置对齐的 values 数组；对于 instant，每个序列包含一个标量 value。

search-traces

输入形式与 search-logs 相同。输出为 TSV，包含 # total_count=<N> is_free_search=<bool> 标头。

分页——及其硬性限制

分页时，将 to_time 缩小到返回结果中的最小 start_timestamp（不是 timestamp，后者是时间跨度的结束时间；start_timestamp 才是排序和筛选 键）。时间窗口采用左闭右开，因此不会重复返回游标所在行。

警告

无法对 traces 进行穷尽分页。 行的排序顺序为 toStartOfHour(start_timestamp) DESC, observation_point DESC, cluster DESC, start_timestamp DESC。observation_point 和 cluster 的优先级都高于时间戳， 因此仅固定 clusters 还不够——同一小时内其他观测点的 spans 会被跳过。而且 observation_point 不在 trace 字段目录中，所以 where 子句无法固定它（工具描述 建议使用 "observation_point = s-app"；但这会被拒绝为未知字段）。

实际建议：缩短时间窗口，确保 total_count 能放在一页内；或使用 analyze-traces。将任何分页 trace 扫描都视为抽样。

筛选 duration、trace_id、span_id 或任何属性都会设置 is_free_search，并将查询路由到原始表——速度更慢，且没有汇总数据。

get-distributed-trace

查看单个请求的 span 树。调查失败或缓慢的请求时，从这里开始。

{
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "from_time": "2026-07-30T10:20:00Z",
  "to_time": "2026-07-30T10:40:00Z",
  "max_spans": 200
}

trace_id、from_time、to_time 都是必填项。时间窗口必须包含该 trace 的 start_timestamp——trace 会按时间分区，因此未覆盖该时间戳的窗口不会返回任何结果。 前后各使用约 10 分钟的窗口。max_spans 默认为 200，最大为 500。

说明

使用 trace_id 定位，而不是 span 的 kuid。一个 trace 包含多个 span；它们都共享同一个 trace_id。

阅读输出

区块 1——每个 span 一行，按前序顺序排列（一个 span 后面紧跟其子节点），并包含用于绘制调用链的 tree 列。关键列：

列	用途
tree	查看调用关系
status / return_code	查看哪个 span 失败
duration_us	span 总耗时，单位为微秒，包括其调用的所有内容
self_time_us	此服务自身耗时，不包括子节点——瓶颈排序依据
start_time / end_time	RFC3339 毫秒格式——可直接粘贴到 search-logs
workload / namespace / cluster	后续日志／指标查询的范围
resource_name / protocol_type / subtype	查看调用的对象

区块 2——## services，每个（cluster、workload）一行，按错误数和自身耗时 从高到低排序。先阅读此区块，再查看 span 行，以确定可疑对象。即使区块 1 被截断，此区块 始终涵盖所有 span。

两条诊断规则

• 没有错误的 trace 仍可能有问题。 ## services 的首行就是耗时最长的调用环节。
• duration_us 大、self_time_us 小 = 服务在等待，而非处理。 调查它调用的对象（其子节点）， 而不是服务本身。反过来，如果某个 span 报错，但所有子节点都成功，则故障就在该服务内部。

如果 spans 归属的是采集器 Agent，而非工作负载的 pod，namespace 可能为空；请从有值的 span 行中获取， 或通过 get-workload-detail 查询。少数情况下，namespace 会列出多个以 | 连接的名称，这表示该集群在 多个 namespace 中运行了同名工作负载。

调查流程

1. get-distributed-trace(trace_id, ±10min)   → the call chain, errors marked
2. read "## services"                        → who owns the errors / the time
3. search-logs                               → scoped to that workload + the failing
                                               span's start_time/end_time (widen a few s)
4. get-recent-changes / get-infra-issues     → why: deploy, OOM, probe failure
5. analyze-metrics                           → confirm resource pressure

步骤 4–5 使用 kubesense-infra 和 kubesense-metrics。

规则

1. 先调用 get-trace-or-log-fields，设置 signal: "traces"，并使用与查询相同的时间窗口。
2. 仅使用目录中的标签：service、instance、method、status_code、resource、 role、protocol。不要使用 app_service、pod_name、subtype、return_code、 clustered_resource、kind、protocol_type。
3. Trace 使用 node_name，日志使用 node。不要跨信号沿用字段。
4. 应用身份优先使用 service，而非 workload——但告警引擎优先使用 workload。
5. **WHERE 中的 duration 单位是毫秒；聚合后的 duration 单位是纳秒。**将 结果除以 1e6，以毫秒报告。此处不存在 duration_ms。
6. @attr 过滤器在 Trace 上不起作用。请改用 group_by_fields/fields 中的 is_attribute: true。
7. 枚举值使用小写（status = error、role = server）；status_code 是字符串， 因此请枚举代码，或使用 LIKE "5%"，不要使用范围条件。
8. value_operation 是 row_count，不是 count。
9. 统计请求时添加 role = server，否则客户端 Span 会被重复计数。
10. get-distributed-trace 需要时间窗口包含 Trace 的开始时间；如果未找到，请先 扩大时间窗口。
11. 不要尝试穷举分页获取 Trace——无法固定 observation_point。请缩短时间窗口或 使用聚合。