trace_id、span_id、service.name、name、start_time_unix_nano、end_time_unix_nano 和 status_code 全部字段的数据流。名为 default 的数据流优先于其他符合条件的数据流,仍然相同时按数据流名称决定。组织没有这样的数据流时,结果为空。只有通过尾部采样保留下来的链路才能读取。
所有调用都需要 streams.query,系统范围可使用 sys.telemetry.read。
列出链路摘要
过滤条件是包含
field、op 和 value 的对象,一个请求最多带 32 个过滤条件。所有过滤条件必须同时匹配。运算符 in 用 values(值的列表)代替 value。
过滤条件按数据流中的字段名指定字段,例如
service.name、name,不接受其他名称。运算符 eq、ne 和 like 分别是 =、!= 和 contains 的别名。JSON 字段不能用作过滤条件。
trace_id、duration_ns、span_count 和 error_count 在 trace 上比较。其他字段都属于 span:trace 中有一个 span 满足过滤条件,该 trace 即匹配;!= 在 trace 的所有 span 都不含该值时匹配。缺少该字段的 span 视为不含该值。
in 匹配 values 中的任意一个值:1 到 64 个值,每个最长 512 字节,且符合字段类型。重复列出的值只算一次。作用于 span 字段时,trace 中有一个 span 含有其中某个值,该 trace 即匹配。
where 表达过滤条件列表无法表达的内容:多个可选分支。它是以下四种形式之一的 JSON 对象:
filters、q 和 where 需同时满足。条件树中的过滤条件含义不变:作用于 span 字段时,trace 中有一个 span 满足即匹配;!= 在 trace 的所有 span 都不含该值时匹配。trace 匹配 A 或匹配 B,即匹配 {"or": [A, B]}。filters 与 where 中的过滤条件合计最多 32 个。一棵条件树最多查找 8 段文本,分组最多嵌套 8 层,每个分组至少有一个条件。
checkout 的 span 或 span 数超过 50 的链路。
cursor 会把页面绑定到签发它的查询。带着 cursor 重复请求,同时更换 limit、sort、q、filters 或 where,会返回 400。
service 与 operation、以纳秒表示的开始时间、以毫秒表示的时长、Span 数量和错误 Span 数量。设置了 next_cursor 时,has_more 为 true。
按时间统计链路数量
q、filters 和 where,匹配的链路也相同。时间桶由调用方指定。
查询参数
从
origin_micros 到 to,一个请求最多覆盖 512 个时间桶。
buckets 只列出包含链路的时间桶,按时间从早到晚排列。total 是在该时间桶内开始的链路数量。errors 是其中至少有一个错误 Span 的链路数量。p50_ns、p95_ns 和 p99_ns 是这些链路耗时的中位数、第 95 和第 99 百分位,以纳秒表示。它们是估算值,没有统计到耗时时不返回。
统计读取链路摘要;过滤条件作用于 Span 字段时,还会读取 Span。列表对每条链路只返回一条摘要。写入重试导致同一条摘要存了两份时,统计会计两次。
无法统计时,调用仍返回 200。此时 buckets 为空,unavailable 给出原因。
列出 Span
q、filters 和 where,并按单个 Span 解读:作用于 Span 字段的过滤条件针对 Span 本身,!= 保留缺少该字段的 Span。duration_ns 是 Span 自身的耗时,span_count 与 error_count 是 Span 所属链路的数量。Span 匹配 A 或匹配 B,即匹配 {"or": [A, B]}。
查询参数
status 为 OK、ERROR 或 UNSET。kind 按 OTLP 的编号表示 Span 类型:1 internal、2 server、3 client、4 producer、5 consumer。Span 没有 parent_span_id、kind 或 http_status_code 时不返回对应字段。调用作为受跟踪的查询运行,与其他查询一样经过准入控制。
读取单条链路
trace_id 由 1 到 128 个字符组成,字符取自 A-Z、a-z、0-9、- 和 _。
查询参数
响应最多包含 100,000 个 Span,大小不超过 32 MiB。上限截断了 Span 列表时,
truncated 为 true。
trace_flags、trace_state、resource、scope、各个 dropped_*_count 计数器、schema_version 和 semantic_conventions_version。
查找链接到某条链路的 Span
from 和 to,并在该窗口内查找。
spans 最多列出 200 个链接过来的 Span,按时间从新到旧排列;还有更多 Span 链接到该链路时,more 为 true。linked_span_id 是链接指向的本链路 Span,attributes 是该链接自身的属性。
查找会把窗口内每个 Span 的链接作为文本读取,并受链路统计的时间预算限制。无法完成时,调用仍返回 200,spans 为空,unavailable 给出原因:time_budget、busy 或 scan_limit,含义与链路统计相同。
错误