otel-semantic-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

Use this skill when you need released semantic convention guidance for naming, attributes, or compliance checks.

当你需要已发布的语义规范来指导命名、属性设置或合规性检查时，可以使用本技能。

do not load the full semantic convention spec into context
use the bundled lookup script to query only the needed released group or attribute
for local verification against a checked-out upstream repo, set
```
OTEL_SEMCONV_REPO=/path/to/semantic-conventions
```

identify the boundary type such as
```
http
```
,
```
db
```
,
```
messaging
```
,
```
rpc
```
, or
```
network
```
pick one primary group first, then add related groups only when they add needed context
for
```
gen_ai.*
```
, OpenAI, or MCP conventions, use the dedicated OpenTelemetry GenAI semantic conventions repository; the core repository keeps only deprecated GenAI-era stubs after v1.42.0
see
```
references/semconv-selection.md
```

list groups:

./scripts/query-otel-semantic-conventions.sh --groups

inspect one group:

./scripts/query-otel-semantic-conventions.sh http

inspect one kind:

./scripts/query-otel-semantic-conventions.sh http spans

inspect one exact attribute or entry:

./scripts/query-otel-semantic-conventions.sh http http.request.method

after changing the parser, run

OTEL_SEMCONV_REPO=/path/to/semantic-conventions bash ./scripts/test-query-otel-semantic-conventions.sh

use required and recommended attributes before optional ones
derive semconv-governed span names directly from the released naming rule
do not prepend or append protocol labels, hostnames, product names, business hints, or other custom prose to semconv-governed span names
if the released naming rule does not provide a low-cardinality target, use the simpler fallback allowed by that convention
if no released key exists, use a stable custom namespace and keep values bounded

include the group name, released version, and source URL from the script output
call out any concrete compatibility limitation if the implementation cannot fully match the released guidance

确定边界类型，例如
```
http
```
、
```
db
```
、
```
messaging
```
、
```
rpc
```
或
```
network
```
先选择一个主组，仅当相关组能提供必要上下文时再添加
对于
```
gen_ai.*
```
、OpenAI 或 MCP 规范，请使用专用的 OpenTelemetry GenAI 语义规范仓库；核心仓库在 v1.42.0 之后仅保留已弃用的 GenAI 时代存根
请查看
```
references/semconv-selection.md
```

列出所有组：

./scripts/query-otel-semantic-conventions.sh --groups

查看单个组：

./scripts/query-otel-semantic-conventions.sh http

查看单个类型：

./scripts/query-otel-semantic-conventions.sh http spans

查看单个具体属性或条目：

./scripts/query-otel-semantic-conventions.sh http http.request.method

修改解析器后，运行

OTEL_SEMCONV_REPO=/path/to/semantic-conventions bash ./scripts/test-query-otel-semantic-conventions.sh