# 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 重命名映射、移除/手工拆分警告、逐属性差异统计与未映射属性报告。

> 标准页面: https://elysiatools.com/zh/tools/otel-semantic-convention-migration-tool

- **分类:** Development

- **关键词:** opentelemetry 迁移, 语义约定, semconv, otel 属性, http.method 重命名, http.request.method, db.system.name, messaging.destination.name, span 属性, log 属性, otel collector transform, rename_attribute_actions, grafana 仪表盘 otel, 升级 otel sdk, 遥测重构, 埋点更新

## 概述

粘贴代码（任意语言）、OTel Collector 配置或 Grafana 仪表盘 JSON；选择源与目标约定版本。引擎按层应用官方非规范性迁移表—v1.23.1 稳定 HTTP 约定，v1.24 重命名数据库属性，v1.27 重写消息属性。全词匹配防止部分匹配。被移除的属性（http.target、net.sock.family、net.sock.peer.name）只标记不重写—http.target 必须手工拆分为 url.path 与 url.query。输出：重写后的源码与差异摘要、collector 重命名映射、仪表盘 JSON 同步以及需人工复查的未映射旧属性。

## 输入项

- **源码 / 配置 / 仪表盘 JSON** (textarea): span.setAttribute("http.method", req.method); ... or collector YAML, or Grafana dashboard JSON
- **起始版本** (select)
- **目标版本** (select)
- **生成 collector 重命名映射** (checkbox)
- **同步重写 JSON 内的值（仪表盘）** (checkbox)

## 适用场景

- 升级应用中的 OpenTelemetry SDK 并需要同步更新存量埋点属性名时。
- 迁移 OpenTelemetry Collector 配置文件并需要生成 transform 处理器重命名映射时。
- 更新 Grafana 仪表盘或告警查询中引用的旧版 OTel 遥测属性键时。

## 工作原理

- 解析输入的各语言源码、Collector YAML 配置或 Grafana 仪表盘 JSON 文本。
- 根据选择的起始与目标版本（如 v1.20.0 至 v1.27.0），按官方语义分层规范进行全词精确匹配与属性重命名。
- 标记已废弃或需人工拆分的旧属性（如 http.target），并生成差异对比、未映射报告以及 Collector 转换规则。

## 使用案例

- 多语言微服务应用在升级 OTel SDK 后的埋点代码批量更新。
- 可观测性管道中 OpenTelemetry Collector 属性转换规则的生成与维护。
- 监控平台中基于旧版 OTel 属性编写的 Grafana 仪表盘与告警规则批量校正。

## 常见问题

### 为什么 http.target 属性没有被自动重命名？

根据 OpenTelemetry 新规范，http.target 已被废弃，需由开发人员人工拆分为 url.path 与 url.query 两个独立属性。

### 工具支持哪些编程语言的源码重构？

工具基于语义属性全词匹配，支持 JavaScript、TypeScript、Python、Go、Java、C#/.NET 等任意语言的代码片段及配置文件。

### Collector 重命名配置输出的是什么格式？

工具会生成适用于 OpenTelemetry Collector transform processor 或 attributes processor 的 rename 键值映射规则。

### 分版本迁移是如何划分的？

v1.23.1 稳定 HTTP 约定，v1.24.0 重命名数据库（db.*）属性，v1.27.0 重写消息队列（messaging.*）属性。

### 重命名会影响属性值本身吗？

默认仅重写属性键名；若勾选同步重写仪表盘，则会一并更新 JSON 查询语句中作为值的属性键引用。

## 相关工具

- [JSON Schema 转 Zod Schema 转换器](https://elysiatools.com/zh/tools/json-schema-to-zod-schema-converter): 将标准 JSON Schema 的 JSON/YAML 定义转换为可直接在 TypeScript 项目中使用的 Zod 运行时校验代码，支持嵌套结构、数组、枚举和常见校验规则
- [OpenAPI 转 Postman Collection](https://elysiatools.com/zh/tools/openapi-to-postman-collection): 把 OpenAPI 3.x 或 Swagger 2.0 规范（JSON/YAML）转成可直接导入的 Postman Collection v2.1.0，含文件夹、变量、认证与示例响应。
- [OpenAPI 转 TypeScript 类型生成器](https://elysiatools.com/zh/tools/openapi-to-typescript-generator): 将 OpenAPI 或 Swagger 的 JSON/YAML 规范转换为 TypeScript 接口类型、请求参数类型和响应类型，并支持输出格式与命名风格配置
- [批量邮箱提取器](https://elysiatools.com/zh/tools/bulk-email-extractor): 从输入文本、文章、网页源码或混合内容中提取所有邮箱地址。支持去重和导出为JSON格式。
- [CSV转换器](https://elysiatools.com/zh/tools/csv-transformer): 转换和处理CSV数据，支持列操作、计算和数据类型转换。 操作示例： • 重命名列: \[{"type": "rename", "column": "旧列名", "new_name": "新列名"}\] • 添加计算列: \[{"type": "add_column", "new_column": "总计", "formula": "价格 * 数量"}\] • 删除列: \[{"type": "remove_column", "remove_column": "要删除的列名"}\] • 转换数据类型: \[{"type": "convert_type", "convert_column": "年龄", "target_type": "number"}\] • 计算值: \[{"type": "calculate", "target_column": "总计", "expression": "价格 * 税率 + 运费"}\] • 过滤行: \[{"type": "filter_values", "filter_column": "状态", "operator": "equals", "value": "激活"}\]
- [JSON 差异可视化](https://elysiatools.com/zh/tools/json-diff-visualizer): 比较两个 JSON 并生成带颜色、路径和统计信息的可视化差异报告
- [JSONata 查询转换工作室](https://elysiatools.com/zh/tools/jsonata-query-transform-studio): 预览 JSONata 风格查询与转换，支持多数据对比，并导出 JSON、CSV、YAML 或 Markdown。
- [TOML / INI / HCL / .env / Nix / dotenv / Kubernetes ConfigMap / Secret 配置格式桥](https://elysiatools.com/zh/tools/toml-ini-hcl-envfile-nix-dotenv-kubernetes-configmap-secret-config-format-bridge): 在 dotenv .env、TOML、INI、Java .properties、YAML、JSON、HCL（Terraform/Vagrant 原生语法）与 Nix 属性集之间转换配置，并可输出 Kubernetes ConfigMap / Secret 清单；保留 ${VAR} / {{var}} 模板占位符与 envsubst 风格插值、记录类型推断来源（string/int/float/bool/list）、HCL 块标签自动折叠为嵌套键，往返 diff 突出非等价设置（丢失键、类型变化、值改写），输出对 Kustomize 补丁友好的 YAML。

## 示例

- [分布式追踪示例](https://elysiatools.com/zh/samples/distributed-tracing-samples): 使用 Jaeger、OpenTelemetry 和其他现代可观测性工具的综合分布式追踪示例，适用于微服务架构
- [Parcel 打包工具](https://elysiatools.com/zh/samples/parcel): Parcel零配置打包工具示例，包括项目设置、插件和高级配置
- [OpenAPI/Swagger 示例](https://elysiatools.com/zh/samples/openapi-swagger): 使用 OpenAPI 3.0 和 Swagger 规范的 RESTful 服务综合 API 文档示例
- [pnpm 包管理器示例](https://elysiatools.com/zh/samples/pnpm): 快速、节省磁盘空间的包管理器示例，包括monorepo管理、工作区配置和高级工作流

## 相关内容

- [OpenTelemetry 埋点升级验收工作流](https://elysiatools.com/zh/hubs/opentelemetry-instrumentation-upgrade-verification): 盘点旧属性、迁移 OTel 语义约定、核对链路上下文传播，并用真实 trace 验收跨服务埋点。