otel-java

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenTelemetry in Java

Java 中的 OpenTelemetry

Entry point for OpenTelemetry mechanics in Java services. Load a reference below based on the task; each reference is self-contained.

Java 服务中 OpenTelemetry 机制的入口。根据任务选择下方的参考文档；每个参考文档都是独立完整的。

References

参考文档

File	Use when
`references/declarative-setup.md`	Configuring the SDK via declarative YAML: Javaagent activation, Spring Boot Starter, autoconfigure SDK, BOM, agent-only properties, manual instrumentation entry points.
`references/sensitive-data-capture.md`	What HTTP instrumentation captures by default (query strings ON, headers/params OFF), query-parameter redaction ( `sensitive-query-parameters` ), header/servlet-parameter capture knobs, SQL sanitization.

文件	使用场景
`references/declarative-setup.md`	通过声明式 YAML 配置 SDK：Javaagent 激活、Spring Boot Starter、自动配置 SDK、BOM、仅代理属性、手动插桩入口点。
`references/sensitive-data-capture.md`	HTTP 插桩默认捕获的内容（查询字符串开启，请求头/参数关闭）、查询参数脱敏（ `sensitive-query-parameters` ）、请求头/Servlet 参数捕获开关、SQL 清理。

Sources of Truth

权威来源

For YAML schema details, fetch the upstream sources listed in the

otel-declarative-config

skill. For Java-specific facts:

Fact	Fetch
Latest BOM ( `opentelemetry-bom` )	`gh api repos/open-telemetry/opentelemetry-java/releases/latest -q '.tag_name'`
Latest Javaagent	`gh api repos/open-telemetry/opentelemetry-java-instrumentation/releases/latest -q '.tag_name'`
SDK declarative-config accepted and preferred `file_format` for a selected BOM tag	`WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java/<selected-sdk-tag>/sdk-extensions/declarative-config/src/main/java/io/opentelemetry/sdk/autoconfigure/declarativeconfig/OpenTelemetryConfigurationFactory.java`
Javaagent declarative-config docs (current activation flag, supported `file_format` )	`WebFetch https://opentelemetry.io/docs/zero-code/java/agent/declarative-configuration/`
Javaagent declarative-config smoke fixture (parser truth for selected agent tag)	`WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java-instrumentation/<selected-agent-tag>/smoke-tests/src/test/resources/declarative-config.yaml`
Javaagent CHANGELOG (when each schema rc landed)	`WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java-instrumentation/<selected-agent-tag>/CHANGELOG.md`
Spring Boot Starter declarative-config fixture (selected starter tag)	`WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java-instrumentation/<selected-agent-tag>/smoke-tests-otel-starter/spring-boot-2/src/testDeclarativeConfig/resources/application.yaml`
Spring Boot starter docs	`WebFetch https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/`
Per-instrumentation telemetry & config (resolved spans/attributes, metrics, config options, target versions)	`WebFetch https://explorer.opentelemetry.io/data/javaagent/instrumentations/<id>/<id>-<hash>.json` — get `<id>` and the latest `<hash>` from the index (see below)

如需了解 YAML schema 详情，请查阅

otel-declarative-config

技能中列出的上游来源。针对 Java 相关的信息：

信息	获取方式
最新 BOM（ `opentelemetry-bom` ）	`gh api repos/open-telemetry/opentelemetry-java/releases/latest -q '.tag_name'`
最新 Javaagent	`gh api repos/open-telemetry/opentelemetry-java-instrumentation/releases/latest -q '.tag_name'`
选定 BOM 版本对应的 SDK 声明式配置支持且推荐的 `file_format`	`WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java/<selected-sdk-tag>/sdk-extensions/declarative-config/src/main/java/io/opentelemetry/sdk/autoconfigure/declarativeconfig/OpenTelemetryConfigurationFactory.java`
Javaagent 声明式配置文档（当前激活标志、支持的 `file_format` ）	`WebFetch https://opentelemetry.io/docs/zero-code/java/agent/declarative-configuration/`
Javaagent 声明式配置测试用例（对应选定代理版本的解析基准）	`WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java-instrumentation/<selected-agent-tag>/smoke-tests/src/test/resources/declarative-config.yaml`
Javaagent 更新日志（各 schema 候选版本的发布时间）	`WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java-instrumentation/<selected-agent-tag>/CHANGELOG.md`
Spring Boot Starter 声明式配置测试用例（对应选定 Starter 版本）	`WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java-instrumentation/<selected-agent-tag>/smoke-tests-otel-starter/spring-boot-2/src/testDeclarativeConfig/resources/application.yaml`
Spring Boot Starter 文档	`WebFetch https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/`
各插桩组件的遥测数据与配置（已解析的 Span/属性、指标、配置选项、目标版本）	`WebFetch https://explorer.opentelemetry.io/data/javaagent/instrumentations/<id>/<id>-<hash>.json` —— 从索引中获取 `<id>` 和最新的 `<hash>` （见下方「插桩组件会生成哪些遥测数据？」）

What telemetry does an instrumentation emit?

插桩组件会生成哪些遥测数据？

For "what does the agent produce for library X" — which spans, attributes, metrics, or config knobs — use the OpenTelemetry Ecosystem Explorer, which fully maps the Java agent and exposes an agent-friendly surface (Markdown indexes and resolved JSON, no scraping). Do not answer from model memory.

Navigation:

```
WebFetch https://explorer.opentelemetry.io/agent/javaagent/index.md
```
— table mapping display name →
```
id
```
→ the instrumentation's JSON data URL (the URL embeds the content
```
<hash>
```
).
```
WebFetch
```
that JSON URL — one self-contained record (a few KB): resolved
```
configurations
```
,
```
telemetry
```
(spans with
```
span_kind
```
+ typed attributes, and
```
metrics
```
),
```
javaagent_target_versions
```
,
```
semantic_conventions
```
, and
```
scope
```
.

Version-specific or "what changed between releases":

https://explorer.opentelemetry.io/agent/javaagent/versions.md

lists versions and marks the latest;

https://explorer.opentelemetry.io/data/javaagent/versions/<version>-index.json

gives the

id

→

hash

map for a version — a differing hash for the same

id

across two versions means that instrumentation changed. Schema:

https://explorer.opentelemetry.io/schemas/javaagent-instrumentation.schema.json

; use

/llms.txt

for the agent-oriented index and

/llms-full.txt

for the full documentation.

Prefer this Explorer data over the raw

ecosystem-registry

YAML on GitHub: the Explorer applies upstream metadata corrections that the raw registry does not.

针对「代理为库 X 生成了什么内容」这类问题——包括哪些 Span、属性、指标或配置选项——请使用 OpenTelemetry 生态浏览器，它完整映射了 Java 代理并提供了面向代理的界面（Markdown 索引和已解析的 JSON，无需爬取）。请勿依赖模型记忆回答。

导航步骤：

```
WebFetch https://explorer.opentelemetry.io/agent/javaagent/index.md
```
—— 显示名称 →
```
id
```
→ 插桩组件 JSON 数据 URL 的映射表（URL 中包含内容
```
<hash>
```
）。
```
WebFetch
```
该 JSON URL —— 一个独立完整的记录（几 KB）：已解析的
```
configurations
```
、
```
telemetry
```
（包含
```
span_kind
```
和类型化属性的 Span，以及
```
metrics
```
）、
```
javaagent_target_versions
```
、
```
semantic_conventions
```
和
```
scope
```
。

特定版本或「版本间有哪些变化」相关内容：

https://explorer.opentelemetry.io/agent/javaagent/versions.md

列出了所有版本并标记最新版本；

https://explorer.opentelemetry.io/data/javaagent/versions/<version>-index.json

提供了对应版本的

id

→

hash

映射——同一

id

在两个版本中的

hash

不同意味着该插桩组件发生了变化。Schema 地址：

https://explorer.opentelemetry.io/schemas/javaagent-instrumentation.schema.json

；使用

/llms.txt

获取面向代理的索引，使用

/llms-full.txt

获取完整文档。

优先使用该浏览器数据，而非 GitHub 上的原始

ecosystem-registry

YAML：浏览器应用了上游元数据修正，而原始注册表没有这些修正。

Cross-References

交叉引用

Schema-level facts:
```
otel-declarative-config
```
skill (language-agnostic YAML schema sources).
SDK version selection across languages:
```
otel-sdk-versions
```
skill.
Semantic conventions lookup:
```
otel-semantic-conventions
```
skill.

Schema 层面的信息：
```
otel-declarative-config
```
技能（与语言无关的 YAML schema 来源）。
跨语言 SDK 版本选择：
```
otel-sdk-versions
```
技能。
语义规范查询：
```
otel-semantic-conventions
```
技能。