样本是 logfmt 还是结构化 JSON?
引号与重复键掩盖字段时先把 logfmt 转成 JSON;已有类型明确的 JSON 直接分析,不做无意义转换。
Elysia Tools
导航
工作流指南
盘点旧属性、迁移 OTel 语义约定、核对链路上下文传播,并用真实 trace 验收跨服务埋点。
第一次接触这个流程?按步骤顺序来,从下面第一个工具开始。已经知道自己需要什么?直接跳到对应的步骤——本流程用到的全部工具都在下面的对比表里。
第一个工具: 结构化日志解析器
专题
| 工具 | 用来做什么 | 分类 |
|---|---|---|
| 结构化日志解析器 | 自动识别常见日志格式,提取核心字段并推断字段类型,支持导出为 JSON、CSV 或 SQL。 | 数据处理 |
| Logfmt 与 JSON 结构化日志桥接 | 在 logfmt(key=value)与 JSON 之间双向转换,处理引号转义、数字/布尔类型转换和重复键。 | 格式转换 |
| OpenTelemetry 语义约定 v1.20 → v1.27 属性迁移工具 | 跨 OpenTelemetry 语义约定版本重写 span/log 属性名:http.method → http.request.method、http.status_code → http.response.status_code、http.url → url.full、db.system → db.system.name、messaging.destination → messaging.destination.name 等 25+ 条—支持粘贴 JS/TS/Python/Go/Java/.NET 源码、collector YAML 或 Grafana 仪表盘 JSON,附 OTel Collector 重命名映射、移除/手工拆分警告、逐属性差异统计与未映射属性报告。 | 开发 |
| OpenTelemetry W3C traceparent / tracestate / baggage 与 OTLP 头传播验证器 | 按 W3C Trace Context ABNF 校验 traceparent(版本/16 字节 trace-id/8 字节 parent-id/1 字节 trace-flags,全零与 ff 版本拒绝、大写告警)、tracestate(≤32 个成员、simple 与 tenant@system 键、重复键告警)、baggage(百分号编码值 + 不透明属性);校验 OTLP 导出 Content-Type 与 gRPC grpc-trace-context-bin 的 25 字节二进制上下文往返一致性;并对两个独立 traceparent 做关联 round-trip(trace-id 稳定性 + 随机子 span-id 冲突检查),输出可直接重发的规范化头。 |
专题
| 开发 |
| 分布式追踪解码与瀑布图可视化 | 解析 Jaeger、Zipkin 或 OpenTelemetry 的 trace JSON,并以瀑布图展示 span 时序与异常节点 | 开发 |
| API 延迟预算规划器 | 规划并可视化 API 延迟预算。输入 P99 目标(如 ≤ 300ms)和各阶段分配(DNS、TCP、TLS、TTFB、Processing、Network),查看实时瀑布图、预算占用和超标告警。可选粘贴 OpenTelemetry 或 Datadog trace,反推基于真实测量的分配建议。 | 开发 |
这个流程面向准备升级 OpenTelemetry 语义约定的服务负责人,不是把所有排障工具堆在一起的事故页面。先收集脱敏的旧日志、当前埋点或 Collector 配置、至少经过两个服务的代表性请求,以及源版本和目标版本。用 structured-log-analyzer 看清日志中实际存在的字段。若日志是 logfmt,再用 logfmt-to-json-structured-log-bridge 处理引号、类型转换和重复键;原本就是结构化 JSON 的样本无需多做一步。分享前先清除个人信息和密钥;完整的泄露风险检查属于 pii-log-redaction 工作流。
在代码、Collector 配置或仪表板 JSON 的副本上运行 otel-semantic-convention-migration-tool,记录源和目标版本、建议的重命名、被移除的属性及未映射的旧字段。工具给出的是迁移草稿,不会替你更新线上配置。比如 http.target 需要按语义考虑拆成路径和查询,不能只做字符串替换。由服务负责人审查这些分支,再走正常发布流水线。只看“改了多少字段”也不够,仪表板查询或 Collector 转换规则可能仍引用旧名。 迁移工具替换映射文本,不解析应用语义。逐项核对替换上下文;字符串变了不说明埋点或仪表板已正确迁移。
把代表性的 W3C traceparent、tracestate、baggage 与 OTLP 导出头部交给 opentelemetry-w3c-traceparent-tracestate-baggage-and-otlp-protobuf-headers-propagation-validator,核对下游是否保留同一个 trace-id,同时换成新的非零 span-id。头部有效并不代表应用真的上报了 span,所以还应使用 distributed-trace-decoder-waterfall-visualizer 打开升级后的链路 JSON。比对预期服务、父子关系、错误 span 和耗时;缺失的服务要记录,不能凭头部推测它存在。 标头检查针对输入值,也可能展示模拟的子跨度。模拟相关性不证明真实服务间传播。应另外比对两跳的脱敏标头,并核对已连通的跟踪导出。
若发布要求包含延迟目标,再用 api-latency-budget-planner 将观察到的阶段耗时与事先约定的预算并列。单条 trace 只能提示时间花在哪儿,不能统计出可信的 P99。验收记录应包含样本版本、属性差异、头部校验、真实链路证据、仍未映射的字段和预算例外。若主要任务变成线上事故排查或 API 载荷重放,应分别转到 observability-debugging 或 api-request-replay-and-debugging。
工作流指南
分析脱敏的升级前样本;仅在需要时把 logfmt 转为 JSON,先看清带引号的值和重复键。
按选定的 v1.20 升级路径改写可映射属性,审查差异及 Collector 改名草稿,并单列移除项和未映射字段。
标头检查针对输入值,也可能展示模拟的子跨度。模拟相关性不证明真实服务间传播。应另外比对两跳的脱敏标头,并核对已连通的跟踪导出。
解码升级后的 OTel、Jaeger 或 Zipkin JSON,对照预期请求路径核查服务顺序、父子 span、错误及耗时。
如果已有 SLO 目标,把观察到的 span 耗时与约定阶段预算并列,记录超出预算的环节。
引号与重复键掩盖字段时先把 logfmt 转成 JSON;已有类型明确的 JSON 直接分析,不做无意义转换。
映射明确的字段可生成改名草稿;http.target 等移除项和未映射属性必须由负责人决定,不能盲目部署转换规则。
用头部校验上下文连续性,用实际导出链路核对 span 关系;只有既定目标存在时才做延迟预算比较。