diff --git a/content/zh/docs/zero-code/java/_index.md b/content/zh/docs/zero-code/java/_index.md index a2266493830c..49f4c1ed409d 100644 --- a/content/zh/docs/zero-code/java/_index.md +++ b/content/zh/docs/zero-code/java/_index.md @@ -1,15 +1,14 @@ --- title: Java 零代码插桩 linkTitle: Java -default_lang_commit: 7715987e5ce1d4ac441afce2db7d337e11192666 -drifted_from_default: true +default_lang_commit: 3a7cfddeb3358c6afc115c93589a91102f90be96 aliases: - /docs/java/automatic_instrumentation - /docs/languages/java/automatic_instrumentation cascade: vers: - instrumentation: 2.19.0 - otel: 1.53.0 + instrumentation: 2.20.1 + otel: 1.54.1 --- Java 中零代码插桩的常见选项包括 Java 代理 JAR、Spring Boot 启动器和 Quarkus OpenTelemetry 扩展。 diff --git a/content/zh/docs/zero-code/java/agent/declarative-configuration.md b/content/zh/docs/zero-code/java/agent/declarative-configuration.md new file mode 100644 index 000000000000..adc13732531c --- /dev/null +++ b/content/zh/docs/zero-code/java/agent/declarative-configuration.md @@ -0,0 +1,281 @@ +--- +title: Java 代理声明式配置 +linkTitle: 声明式配置 +default_lang_commit: 9958669fbbc5664acded963fedb51c7cbf63c6a3 +weight: 11 +cSpell:ignore: genai +--- + + + +声明式配置使用 YAML 文件，而非环境变量或系统属性。 + +这种方法在以下情况下非常有用： + +- 你需要设置许多配置选项。 +- 你想使用环境变量或系统属性中不可用的配置选项。 + +与环境变量一样，配置语法与语言无关，适用于所有支持声明式配置的 OpenTelemetry Java SDK，包括 OpenTelemetry Java 代理。 + +{{% alert title="警告" %}} 声明式配置是实验性功能。 +{{% /alert %}} + +## 支持版本 {#supported-versions} + + + +声明式配置在 **OpenTelemetry Java 代理版本 2.20.0 及更高版本**中受支持。 + +## 快速开始 {#getting-started} + + + +1. 将下面的配置文件保存为 `otel-config.yaml`。 +2. 将以下内容添加到你的 JVM 启动参数中： + + ```shell + -Dotel.experimental.config.file=/path/to/otel-config.yaml + ``` + +参考 [SDK 声明式配置][SDK Declarative configuration]文档，获取更通用的声明式配置入门指南。 + +本页重点介绍 [OpenTelemetry Java 代理](https://github.com/open-telemetry/opentelemetry-java-instrumentation) 的声明式配置。 + +## 配置选项的映射 {#mapping-of-configuration-options} + + + +当你希望将现有的有的环境变量或系统属性配置映射为声明式配置时，请遵循以下规则： + +1. 如果配置选项以 `otel.javaagent.` 开头（例如 `otel.javaagent.logging`），那么它很可能是只能通过环境变量或系统属性设置的属性（有关详细信息，请参阅下面的[仅限环境变量和系统属性的选项](#environment-variables-and-system-properties-only-options)部分）。 + 否则，移除 `otel.javaagent.` 前缀，并将其放置在下方的 `agent` 配置段中。 +2. 如果配置选项以 `otel.instrumentation.` 开头（例如 `otel.instrumentation.spring-batch.experimental.chunk.new-trace`），那么去掉 `otel.instrumentation.` 前缀，并将其放在下面的 `instrumentation` 部分下。 +3. 否则，该选项很可能属于 SDK 配置。在[迁移配置](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/examples/sdk-migration-config.yaml)中查找对应的环境变量或系统属性。 + 如果有一个系统属性像 `otel.bsp.schedule.delay`，那么在迁移配置中查找对应的环境变量 `OTEL_BSP_SCHEDULE_DELAY`。 +4. 使用 `.` 创建缩进级别。 +5. 将 `-` 转换为 `_`。 +6. 根据需要使用 YAML 布尔值和整数类型（例如 `true` 而不是 `"true"`，`5000` 而不是 `"5000"`）。 +7. 下面列出了一些特殊映射的选项。 + +```yaml +instrumentation/development: + general: + peer: + service_mapping: # 原配置项为 "otel.instrumentation.common.peer-service-mapping" + - peer: 1.2.3.4 + service: FooService + - peer: 2.3.4.5 + service: BarService + http: + client: + request_captured_headers: # 原配置项为 otel.instrumentation.http.client.capture-request-headers + - Content-Type + - Accept + response_captured_headers: # 原配置项为 otel.instrumentation.http.client.capture-response-headers + - Content-Type + - Content-Encoding + server: + request_captured_headers: # 原配置项为 otel.instrumentation.http.server.capture-request-headers + - Content-Type + - Accept + response_captured_headers: # 原配置项为 otel.instrumentation.http.server.capture-response-headers + - Content-Type + - Content-Encoding + java: + agent: + # 原配置项为 otel.instrumentation.common.default-enabled + # instrumentation_mode: none # 原为 false + instrumentation_mode: default # 原为 true + spring_batch: + experimental: + chunk: + new_trace: true +``` + +## 仅适用于环境变量和系统属性的选项 {#environment-variables-and-system-properties-only-options} + + + +以下配置选项虽受声明式配置支持，但仅能通过环境变量或系统属性进行设置： + +- `otel.javaagent.configuration-file`（但使用声明式配置时不需要设置该选项） +- `otel.javaagent.debug` +- `otel.javaagent.enabled` +- `otel.javaagent.experimental.field-injection.enabled` +- `otel.javaagent.experimental.security-manager-support.enabled` +- `otel.javaagent.extensions` +- `otel.javaagent.logging.application.logs-buffer-max-records` +- `otel.javaagent.logging` + +这些选项在代理启动时需要在读取声明式配置文件之前设置。 + +## 时长格式 {#duration-format} + + + +- 声明式配置**仅支持以毫秒为单位的时长**（例如，5 秒表示为 `5000`）。 +- 如果你使用 `OTEL_BSP_SCHEDULE_DELAY=5s`，将会出现错误（该格式对环境变量有效，但对声明式配置无效）。 + +示例： + +```yaml +tracer_provider: + processors: + - batch: + schedule_delay: ${OTEL_BSP_SCHEDULE_DELAY:-5000} +``` + +## 行为差异 {#behavior-differences} + + + +- 资源属性 `telemetry.distro.name`（默认由 Java 代理添加）的值为 `opentelemetry-javaagent`， + 而不是 `opentelemetry-java-instrumentation`（将在 3.0 版本中与 Java 代理保持一致）。 + +## 未支持的功能 {#not-yet-supported-features} + + + +一些通过环境变量和系统属性支持的功能尚未被声明式配置支持： + +以下设置仍需通过环境变量或系统属性进行设置： + +- `otel.experimental.javascript-snippet` +- `otel.instrumentation.aws-sdk.experimental-record-individual-http-error` +- `otel.instrumentation.aws-sdk.experimental-span-attributes` +- `otel.instrumentation.aws-sdk.experimental-use-propagator-for-messaging` +- `otel.instrumentation.common.db-statement-sanitizer.enabled` +- `otel.instrumentation.common.logging.span-id` +- `otel.instrumentation.common.logging.trace-flags` +- `otel.instrumentation.common.logging.trace-id` +- `otel.instrumentation.experimental.span-suppression-strategy` +- `otel.instrumentation.genai.capture-message-content` +- `otel.instrumentation.jdbc.experimental.capture-query-parameters` +- `otel.instrumentation.jdbc.experimental.transaction.enabled` +- `otel.instrumentation.log4j-context-data.add-baggage` +- `otel.instrumentation.messaging.experimental.capture-headers` +- `otel.instrumentation.messaging.experimental.receive-telemetry.enabled` +- `otel.javaagent.experimental.thread-propagation-debugger.enabled` +- `otel.semconv-stability.opt-in` + + + +Java 代理中尚未被声明式配置支持的功能： + +- `otel.instrumentation.common.mdc.resource-attributes` +- `otel.javaagent.add-thread-details` +- 当 `otel.javaagent.debug=true` 时，为 Span 添加控制台日志记录器 + - 可以通过在配置文件中添加用于输出 Span 信息的控制台日志记录器。 +- 使用 `GlobalConfigProvider` 在自定义代码中访问声明式配置值 + +Java SDK 中尚未被声明式配置支持的功能： + +- 在 `AutoConfiguredOpenTelemetrySdk` 中调用 `AutoConfigureListener` + +Contrib 中尚未被声明式配置支持的功能： + +- [AWS X-Ray](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/aws-xray) +- [GCP 认证](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/gcp-auth-extension) + +最后，[Spring Boot 启动器](/docs/zero-code/java/spring-boot-starter)尚不支持声明式配置： + +- 但是，你已经可以使用 `application.yaml` 来配置 OpenTelemetry Spring Boot 启动器 + +[SDK Declarative configuration]: /docs/languages/sdk-configuration/declarative-configuration diff --git a/content/zh/docs/zero-code/java/agent/disable.md b/content/zh/docs/zero-code/java/agent/disable.md index 4a81ab59f7b8..bf16b8ff551e 100644 --- a/content/zh/docs/zero-code/java/agent/disable.md +++ b/content/zh/docs/zero-code/java/agent/disable.md @@ -1,9 +1,8 @@ --- title: 禁用特定插桩 linkTitle: 禁用插桩 -weight: 11 -default_lang_commit: a4dcd0236fb8d57f53a6167905c9114afd55df4b -drifted_from_default: true +weight: 12 +default_lang_commit: 2cb66a7e093114cfe06eb70dbca46abbbee45ef2 # prettier-ignore cSpell:ignore: activej akka armeria avaje clickhouse couchbase datasource dbcp Dotel dropwizard dubbo finatra hikari hikaricp httpasyncclient httpclient hystrix javalin jaxrs jaxws jedis jodd kotlinx ktor logback logmanager mojarra mybatis myfaces okhttp openai oshi payara pekko rabbitmq ratpack rediscala redisson restlet rocketmq shenyu spymemcached twilio vaadin vertx vibur webflux webmvc --- diff --git a/content/zh/docs/zero-code/java/agent/getting-started.md b/content/zh/docs/zero-code/java/agent/getting-started.md index 9cec9bb3aaa6..d0987115c8ac 100644 --- a/content/zh/docs/zero-code/java/agent/getting-started.md +++ b/content/zh/docs/zero-code/java/agent/getting-started.md @@ -1,8 +1,7 @@ --- title: 快速开始 weight: 1 -default_lang_commit: 0930994d5be6f01b05d0caca0550c468d2f3e829 -drifted_from_default: true +default_lang_commit: 2cb66a7e093114cfe06eb70dbca46abbbee45ef2 cSpell:ignore: Dotel myapp --- @@ -27,6 +26,13 @@ cSpell:ignore: Dotel myapp java -jar myapp.jar ``` +## 声明式配置 {#declarative-configuration} + +声明式配置使用 YAML 文件，而非环境变量或系统属性。 +当你需要设置许多配置选项，或者想要使用那些无法通过环境变量或系统属性来配置的选项时，这种方式会非常有用。 + +有关更多详细信息，请参阅[声明式配置](../declarative-configuration)页面。 + ## 配置代理 {#configuring-the-agent} 代理高度可配置。 diff --git a/content/zh/docs/zero-code/java/agent/instrumentation/_index.md b/content/zh/docs/zero-code/java/agent/instrumentation/_index.md new file mode 100644 index 000000000000..5d8829572118 --- /dev/null +++ b/content/zh/docs/zero-code/java/agent/instrumentation/_index.md @@ -0,0 +1,115 @@ +--- +title: 插桩配置 +linkTitle: 插桩配置 +default_lang_commit: 5b82e8f9c057d4d4961d41091a4bc75fc9b5b37c +weight: 100 +cSpell:ignore: enduser hset serverlessapis +--- + +本页介绍适用于多个插桩的通用设置。 + +## 对等服务名称 {#peer-service-name} + +[对等服务名称](/docs/specs/semconv/general/attributes/#general-remote-service-attributes)是与之建立连接的远程服务的名称。它对应于本地服务的[资源](/docs/specs/semconv/resource/#service)中的`service.name`。 + +{{% config_option name="otel.instrumentation.common.peer-service-mapping" %}} + +用于将主机名或 IP 地址映射为对等服务， +格式为以逗号分隔的**<主机名或 IP>=<用户指定名称>**键值对列表。 +当某个 Span 的主机名或 IP 地址与映射关系匹配时，对等服务会作为一个属性添加到该 Span 中。 + +例如，如果设置为以下内容： + +```text +1.2.3.4=cats-service,dogs-abcdef123.serverlessapis.com=dogs-api +``` + +然后，发往 `1.2.3.4` 的请求会带有 `peer.service` 属性，其值为 `cats-service`； +而发往 `dogs-abcdef123.serverlessapis.com` 的请求会带有 `peer.service` 属性，其值为 `dogs-api`。 + +自 Java 代理版本 `1.31.0` 起，可以提供端口和路径来定义 `peer.service`。 + +例如，如果设置为以下内容： + +```text +1.2.3.4:443=cats-service,dogs-abcdef123.serverlessapis.com:80/api=dogs-api +``` + +那么，发往 `1.2.3.4:443` 的请求会带有 `peer.service` 属性，其值为 `cats-service`； +而发往 `dogs-abcdef123.serverlessapis.com:80/api/v1` 的请求会带有 `peer.service` 属性，其值为 `dogs-api`。 + +{{% /config_option %}} + +## 数据库语句清洗 {#db-statement-sanitization} + +代理会在设置 `db.statement` 语义属性之前，对所有数据库查询以及其他语句进行清洗。 +查询语句中的所有值（字符串、数字）都会被替换为问号（`?`）。 + +注意：JDBC 绑定参数不会被捕获到 `db.statement` 中。 +如果你希望捕获绑定参数，请参阅[相关问题](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/7413)。 + +例如： + +- SQL 查询 `SELECT a from b where password="secret"` 将在导出的 Span 中显示为 `SELECT a from b where password=?`； +- Redis 命令 `HSET map password "secret"` 将在导出的 Span 中显示为 `HSET map password ?`。 + +此行为在所有数据库插桩中默认启用。使用以下属性可将其禁用： + +{{% config_option +name="otel.instrumentation.common.db-statement-sanitizer.enabled" +default=true +%}} 启用数据库语句清洗功能 {{% /config_option %}} + +## 在消息传递插桩中采集消费者消息接收遥测数据 {#capturing-consumer-message-receive-telemetry-in-messaging-instrumentations} + +你可以配置代理，在消息传递插桩中采集消费者消息接收遥测数据。使用以下属性来启用该功能： + +{{% config_option +name="otel.instrumentation.messaging.experimental.receive-telemetry.enabled" +default=false +%}} 启用消费者消息接收遥测功能 {{% /config_option %}} + +需要注意的是，这会导致消费者端启动一个新的链路，仅通过一个 Span 链接将其与生产者的追踪关联起来。 + +> **注意**：表中列出的属性、环境变量名称仍处于实验阶段，可能会发生变化。 + +## 采集终端用户属性 {#capturing-enduser-attributes} + +你可以配置代理， +从 [JavaEE/JakartaEE Servlet](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/servlet) 和 [Spring Security](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-security-config-6.0) 等插桩库中采集[通用身份属性](/docs/specs/semconv/registry/attributes/enduser/)（`enduser.id`、`enduser.role`、`enduser.scope`）。 + +> **注意**：鉴于所涉及数据的敏感性，此功能默认关闭，但允许对特定属性进行选择性激活。 +> 在开启数据采集前，你必须仔细评估每个属性的隐私影响。 + +{{% config_option +name="otel.instrumentation.common.enduser.id.enabled" +default=false +%}} 决定是否采集 `enduser.id` 语义属性。 +{{% /config_option %}} + +{{% config_option +name="otel.instrumentation.common.enduser.role.enabled" +default=false +%}} 决定是否采集 `enduser.role` 语义属性。 +{{% /config_option %}} + +{{% config_option +name="otel.instrumentation.common.enduser.scope.enabled" +default=false +%}} 决定是否采集 `enduser.scope` 语义属性。 +{{% /config_option %}} + +### Spring Security {#spring-security} + +对于使用自定义[授权前缀](https://docs.spring.io/spring-security/reference/servlet/authorization/architecture.html#authz-authorities)的 Spring Security 用户， +你可以使用以下属性来从 `enduser.*` 属性值中剥离这些前缀，以更好地表示实际的角色和范围名称： + +{{% config_option +name="otel.instrumentation.spring-security.enduser.role.granted-authority-prefix" +default=ROLE_ +%}} 用于识别要采集到 `enduser.role` 语义属性中的权限的前缀。 {{% /config_option %}} + +{{% config_option +name="otel.instrumentation.spring-security.enduser.scope.granted-authority-prefix" +default=SCOPE_ +%}} 用于识别要采集到 `enduser.scope` 语义属性中的权限的前缀。 {{% /config_option %}} diff --git a/content/zh/docs/zero-code/java/agent/instrumentation/http.md b/content/zh/docs/zero-code/java/agent/instrumentation/http.md new file mode 100644 index 000000000000..eccf93ef4b9f --- /dev/null +++ b/content/zh/docs/zero-code/java/agent/instrumentation/http.md @@ -0,0 +1,85 @@ +--- +title: HTTP 插桩配置 +linkTitle: HTTP +default_lang_commit: 4dda37feaa73c216918aab12f16de959d1977766 +weight: 110 +--- + +## 捕获 HTTP 请求头和响应头 {#capturing-http-request-and-response-headers} + +你可以配置代理，将预定义的 HTTP 头作为 Span 属性进行采集， +符合[语义规范](/docs/specs/semconv/http/http-spans/)。 +使用以下属性来定义要采集的 HTTP 头： + +{{% config_option name="otel.instrumentation.http.client.capture-request-headers" %}} +以逗号分隔的 HTTP 头名称列表。 +HTTP 客户端插桩将采集所有配置的头名称的 HTTP 请求头值。 +{{% /config_option %}} + +{{% config_option name="otel.instrumentation.http.client.capture-response-headers" %}} +以逗号分隔的 HTTP 头名称列表。 +HTTP 客户端插桩将采集所有配置的头名称的 HTTP 响应头值。 +{{% /config_option %}} + +{{% config_option name="otel.instrumentation.http.server.capture-request-headers" %}} +以逗号分隔的 HTTP 头名称列表。 +HTTP 服务器插桩将采集所有配置的头名称的 HTTP 请求头值。 +{{% /config_option %}} + +{{% config_option name="otel.instrumentation.http.server.capture-response-headers" %}} +以逗号分隔的 HTTP 头名称列表。 +HTTP 服务器插桩将采集所有配置的头名称的 HTTP 响应头值。 +{{% /config_option %}} + +这些配置选项受所有 HTTP 客户端和服务器插桩支持。 + +> **注意**：表中列出的属性、环境变量名称仍处于实验阶段，可能会发生变化。 + +## 采集 Servlet 请求参数 {#capturing-servlet-request-parameters} + +你可以配置代理，使其为 Servlet API 处理的请求采集预定义的 HTTP 请求参数，并将这些参数作为 Span 属性。 +使用以下属性来定义要采集的 Servlet 请求参数： + +{{% config_option name="otel.instrumentation.servlet.experimental.capture-request-parameters" %}} +以逗号分隔的请求参数名称列表。 +{{% /config_option %}} + +> **注意**：表中列出的属性、环境变量名称仍处于实验阶段，可能会发生变化。 + +## 配置已知 HTTP 方法 {#configuring-known-http-methods} + +配置插桩以识别一组替代的 HTTP 请求方法。 +所有其他方法将被视为 `_OTHER`。 + +{{% config_option name="otel.instrumentation.http.known-methods" +default="CONNECT,DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT,TRACE" +%}} 以逗号分隔的已知 HTTP 方法列表。 {{% /config_option %}} --> + +## 启用实验性 HTTP 遥测功能 {#enabling-experimental-http-telemetry} + +你可以配置代理，采集额外的实验性 HTTP 遥测数据。 + +{{% config_option +name="otel.instrumentation.http.client.emit-experimental-telemetry" +default=false +%}} 启用实验性 HTTP 客户端遥测功能。 {{% /config_option %}} + +{{% config_option name="otel.instrumentation.http.server.emit-experimental-telemetry" +default=false +%}} +启用实验性 HTTP 服务器遥测功能。 {{% /config_option %}} + +对于客户端和服务器 Span，添加以下属性： + +- `http.request.body.size` 和 `http.response.body.size`：分别表示请求和响应体的大小。 + +对于客户端指标，创建以下指标： + +- [http.client.request.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpclientrequestbodysize) +- [http.client.response.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpclientresponsebodysize) + +对于服务器指标，创建以下指标： + +- [http.server.active_requests](/docs/specs/semconv/http/http-metrics/#metric-httpserveractive_requests) +- [http.server.request.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpserverrequestbodysize) +- [http.server.response.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpserverresponsebodysize) diff --git a/content/zh/docs/zero-code/java/agent/server-config.md b/content/zh/docs/zero-code/java/agent/server-config.md index 6d113232b8a6..583acb19565b 100644 --- a/content/zh/docs/zero-code/java/agent/server-config.md +++ b/content/zh/docs/zero-code/java/agent/server-config.md @@ -2,8 +2,7 @@ title: 应用服务器配置 linkTitle: 应用服务器配置 description: 如何为 Java 应用服务器定义代理路径 -default_lang_commit: 748555c22f43476291ae0c7974ca4a2577da0472 -drifted_from_default: true +default_lang_commit: 908a1cd58d5a1c0a1c59993e099fc4ed99185590 weight: 215 cSpell:ignore: asadmin Glassfish Payara setenv --- @@ -86,9 +85,17 @@ JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:/path/to/opentelemetry-javaagent.jar" 确保你的域目录下的 domain.xml 文件中包含针对代理的 `` 条目。 -## Tomcat / TomEE {#tomcat-tomee} +## Tomcat、TomEE {#tomcat-tomee} -将 Java 代理的路径添加到启动脚本中： +将 Java 代理的路径添加到启动脚本中。配置方法取决于你的安装方式： + +**对于包管理安装**（apt-get/yum），添加到 `/etc/tomcat*/tomcat*.conf`： + +```sh +JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/opentelemetry-javaagent.jar" +``` + +**对于下载安装**，创建或修改 `/bin/setenv.sh`（Linux）或 `/bin/setenv.bat`（Windows）： {{< tabpane text=true persist=lang >}} @@ -108,6 +115,8 @@ set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:":\path\to\opentelemetry-jav {{% /tab %}} {{< /tabpane >}} +**对于 Windows 服务安装**，使用 `/bin/tomcat*w.exe` 将 `-javaagent::\path\to\opentelemetry-javaagent.jar` 添加到 Java 选项的 Java 选项卡下。 + ## WebLogic {#weblogic} 将 Java 代理的路径添加到域启动脚本中： diff --git a/content/zh/docs/zero-code/java/agent/supported-libraries.md b/content/zh/docs/zero-code/java/agent/supported-libraries.md new file mode 100644 index 000000000000..89469f08e328 --- /dev/null +++ b/content/zh/docs/zero-code/java/agent/supported-libraries.md @@ -0,0 +1,246 @@ +--- +title: 支持的库 +linkTitle: 支持的库 +default_lang_commit: 1fe3f355b66260860b47b6cd79c768fd27402334 +weight: 11 +# prettier-ignore +cSpell:ignore: activej akka armeria avaje clickhouse couchbase dbcp dropwizard dubbo finatra hikari hikaricp httpasyncclient httpclient hystrix javalin jedis jodd ktor logback logmanager mojarra mybatis myfaces okhttp openai oshi payara pekko rabbitmq ratpack rediscala redisson resteasy restlet rocketmq shenyu spymemcached twilio vaadin vertx vibur webflux webmvc +--- + + + +Java 代理开箱即用地对许多库、框架和应用服务器进行自动插桩。 +如果您没有看到您正在寻找的框架或技术， +请考虑[提交一个问题](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues)。 + +## 库与框架 {#supported-libraries} + + + +以下是受支持的库和框架。除非另有说明，列出的版本均为支持的最低版本。 + +| 库与框架 | 能被自动插桩版本 | 独立库插桩[1] | 功能与语义约定 | +| ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| [ActiveJ](https://activej.io/) | 6.0+ | N/A | [HTTP Server Spans]、[HTTP Server Metrics] | +| [Akka Actors](https://doc.akka.io/docs/akka/current/typed/index.html) | 2.3+ | N/A | 上下文传播 | +| [Akka HTTP](https://doc.akka.io/docs/akka-http/current/index.html) | 10.0+ | N/A | [HTTP Client Spans]、[HTTP Client Metrics]、[HTTP Server Spans]、[HTTP Server Metrics]、提供 `http.route` [2] | +| [Alibaba Druid](https://github.com/alibaba/druid) | 1.0+ | [opentelemetry-alibaba-druid-1.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-alibaba-druid-1.0) | [Database Pool Metrics] | +| [Apache Axis2](https://axis.apache.org/axis2/java/core/) | 1.6+ | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [Apache Camel](https://camel.apache.org/) | 2.20+ (not including 3.0+ yet) | N/A | 依赖于所使用的组件 | +| [Apache CXF JAX-RS](https://cxf.apache.org/) | 3.2+ (not including 4.0+ yet) | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [Apache CXF JAX-WS](https://cxf.apache.org/) | 3.0+ (not including 4.0+ yet) | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [Apache DBCP](https://commons.apache.org/proper/commons-dbcp/) | 2.0+ | [opentelemetry-apache-dbcp-2.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-apache-dbcp-2.0) | [Database Pool Metrics] | +| [Apache Dubbo](https://github.com/apache/dubbo/) | 2.7+ | [opentelemetry-apache-dubbo-2.7](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-apache-dubbo-2.7) | [RPC Client Spans]、[RPC Server Spans] | +| [Apache HttpAsyncClient](https://hc.apache.org/index.html) | 4.1+ | N/A | [HTTP Client Spans]、[HTTP Client Metrics] | +| [Apache HttpClient](https://hc.apache.org/index.html) | 2.0+ | [opentelemetry-apache-httpclient-4.3](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-apache-httpclient-4.3)、
[opentelemetry-apache-httpclient-5.2](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-apache-httpclient-5.2) | [HTTP Client Spans]、[HTTP Client Metrics] | +| [Apache ShenYu](https://shenyu.apache.org/) | 2.4+ | N/A | 提供 `http.route` [2] | +| [Apache Kafka Producer/Consumer API](https://kafka.apache.org/documentation/#producerapi) | 0.11+ | [opentelemetry-kafka-clients-2.6](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-kafka-clients-2.6) | [Messaging Spans] | +| [Apache Kafka Streams API](https://kafka.apache.org/documentation/streams/) | 0.11+ | N/A | [Messaging Spans] | +| [Apache MyFaces](https://myfaces.apache.org/) | 1.2+ (not including 4.0+ yet) | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [Apache Pekko Actors](https://pekko.apache.org/) | 1.0+ | N/A | 上下文传播 | +| [Apache Pekko HTTP](https://pekko.apache.org/) | 1.0+ | N/A | [HTTP Client Spans]、[HTTP Client Metrics]、[HTTP Server Spans]、[HTTP Server Metrics]、提供 `http.route` [2] | +| [Apache Pulsar](https://pulsar.apache.org/) | 2.8+ | N/A | [Messaging Spans] | +| [Apache RocketMQ gRPC/Protobuf-based Client](https://rocketmq.apache.org/) | 5.0+ | N/A | [Messaging Spans] | +| [Apache RocketMQ Remoting-based Client](https://rocketmq.apache.org/) | 4.8+ | [opentelemetry-rocketmq-client-4.8](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-rocketmq-client-4.8) | [Messaging Spans] | +| [Apache Struts](https://github.com/apache/struts) | 2.3+ | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [Apache Tapestry](https://tapestry.apache.org/) | 5.4+ | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [Apache Wicket](https://wicket.apache.org/) | 8.0+ | N/A | 提供 `http.route` [2] | +| [Armeria](https://armeria.dev) | 1.3+ | [opentelemetry-armeria-1.3](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-armeria-1.3) | [HTTP Client Spans]、[HTTP Client Metrics]、[HTTP Server Spans]、[HTTP Server Metrics] | +| [Armeria gRPC](https://armeria.dev) | 1.14+ | | [RPC Client Spans]、[RPC Client Metrics]、[RPC Server Spans]、[RPC Server Metrics] | +| [AsyncHttpClient](https://github.com/AsyncHttpClient/async-http-client) | 1.9+ | N/A | [HTTP Client Spans]、[HTTP Client Metrics] | +| [Avaje Jex](https://avaje.io/jex/) | 3.0+ | N/A | 提供 `http.route` [2] | +| [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/java-handler.html) | 1.0+ | [opentelemetry-aws-lambda-core-1.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-aws-lambda-core-1.0),
[opentelemetry-aws-lambda-events-3.11](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-aws-lambda-events-3.11) | [FaaS Server Spans] | +| [AWS SDK](https://aws.amazon.com/sdk-for-java/) | 1.11 - 1.12.583,
2.2+ | [opentelemetry-aws-sdk-1.11](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-aws-sdk-1.11),
[opentelemetry-aws-sdk-1.11-autoconfigure](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-aws-sdk-1.11-autoconfigure),
[opentelemetry-aws-sdk-2.2](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-aws-sdk-2.2),
[opentelemetry-aws-sdk-2.2-autoconfigure](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-aws-sdk-2.2-autoconfigure) | [Messaging Spans]、[Database Client Spans]、[Database Client Metrics] [6]、[HTTP Client Spans]、[GenAI Client Spans]、[GenAI Client Metrics] | +| [Azure Core](https://docs.microsoft.com/en-us/java/api/overview/azure/core-readme) | 1.14+ | N/A | 上下文传播 | +| [Cassandra Driver](https://github.com/datastax/java-driver) | 3.0+ | [opentelemetry-cassandra-4.4](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-cassandra-4.4) | [Database Client Spans]、[Database Client Metrics] [6] | +| [Clickhouse Client](https://github.com/ClickHouse/clickhouse-java) | 0.5+ | N/A | [Database Client Spans]、[Database Client Metrics] [6] | +| [Couchbase Client](https://github.com/couchbase/couchbase-java-client) | 2.0 - 2.7.x | N/A | [Database Client Spans]、[Database Client Metrics] [6] | +| [Couchbase Client](https://github.com/couchbase/couchbase-java-client) | 3.1+ | N/A | [Database Client Spans] | +| [c3p0](https://github.com/swaldman/c3p0) | 0.9.2+ | [opentelemetry-c3p0-0.9](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-c3p0-0.9) | [Database Pool Metrics] | +| [Dropwizard Metrics](https://metrics.dropwizard.io/) | 4.0+ (disabled by default) | N/A | none | +| [Dropwizard Views](https://www.dropwizard.io/en/latest/manual/views.html) | 0.7+ | N/A | 控制器 Span [3] | +| [Eclipse Grizzly](https://javaee.github.io/grizzly/httpserverframework.html) | 2.3+ | N/A | [HTTP Server Spans]、[HTTP Server Metrics] | +| [Eclipse Jersey](https://eclipse-ee4j.github.io/jersey/) | 2.0+ | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [Eclipse Jetty HTTP Client](https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/client/HttpClient.html) | 9.2 - 9.4.x,
12.0+ | [opentelemetry-jetty-httpclient-9.2](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-jetty-httpclient-9.2)
[opentelemetry-jetty-httpclient-12.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-jetty-httpclient-12.0) | [HTTP Client Spans]、[HTTP Client Metrics] | +| [Eclipse Metro](https://projects.eclipse.org/projects/ee4j.metro) | 2.2+ | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [Eclipse Mojarra](https://projects.eclipse.org/projects/ee4j.mojarra) | 1.2+ (not including 4.0+ yet) | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [Elasticsearch API Client](https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/index.html) | 7.16 - 7.17.19,
8.0 - 8.9.+ [4] | N/A | [Elasticsearch Client Spans] | +| [Elasticsearch REST Client](https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/index.html) | 5.0+ | N/A | [Database Client Spans]、[Database Client Metrics] [6] | +| [Elasticsearch Transport Client](https://www.elastic.co/guide/en/elasticsearch/client/java-api/current/index.html) | 5.0+ | N/A | [Database Client Spans]、[Database Client Metrics] [6] | +| [Finagle](https://github.com/twitter/finagle) | 23.11+ | N/A | none | +| [Finatra](https://github.com/twitter/finatra) | 2.9+ | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [Geode Client](https://geode.apache.org/) | 1.4+ | N/A | [Database Client Spans]、[Database Client Metrics] [6] | +| [Google HTTP Client](https://github.com/googleapis/google-http-java-client) | 1.19+ | N/A | [HTTP Client Spans]、[HTTP Client Metrics] | +| [Grails](https://grails.org/) | 3.0+ | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [GraphQL Java](https://www.graphql-java.com/) | 12.0+ | [opentelemetry-graphql-java-12.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-graphql-java-12.0),
[opentelemetry-graphql-java-20.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-graphql-java-20.0) | [GraphQL Server Spans] | +| [gRPC](https://github.com/grpc/grpc-java) | 1.6+ | [opentelemetry-grpc-1.6](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-grpc-1.6) | [RPC Client Spans]、[RPC Client Metrics]、[RPC Server Spans]、[RPC Server Metrics] | +| [Guava ListenableFuture](https://guava.dev/releases/snapshot/api/docs/com/google/common/util/concurrent/ListenableFuture.html) | 10.0+ | [opentelemetry-guava-10.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-guava-10.0) | 上下文传播 | +| [GWT](https://www.gwtproject.org/) | 2.0+ | N/A | [RPC Server Spans] | +| [Hibernate](https://github.com/hibernate/hibernate-orm) | 3.3+ | N/A | none | +| [Hibernate Reactive](https://hibernate.org/reactive) | 1.0+ | N/A | none | +| [HikariCP](https://github.com/brettwooldridge/HikariCP) | 3.0+ | [opentelemetry-hikaricp-3.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-hikaricp-3.0) | [Database Pool Metrics] | +| [HttpURLConnection](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/net/HttpURLConnection.html) | Java 8+ | N/A | [HTTP Client Spans]、[HTTP Client Metrics] | +| [Hystrix](https://github.com/Netflix/Hystrix) | 1.4+ | N/A | none | +| [InfluxDB Client](https://github.com/influxdata/influxdb-java) | 2.4+ | N/A | [Database Client Spans]、[Database Client Metrics] [6] | +| [Java Executors](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Executor.html) | Java 8+ | N/A | 上下文传播 | +| [Java HTTP Client](https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/package-summary.html) | Java 11+ | [opentelemetry-java-http-client](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-java-http-client) | [HTTP Client Spans]、[HTTP Client Metrics] | +| [Java HTTP Server](https://docs.oracle.com/en/java/javase/21/docs/api/jdk.httpserver/module-summary.html) | Java 8+ | [opentelemetry-java-http-server](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-java-http-server) | [HTTP Server Spans]、[HTTP Server Metrics] | +| [java.util.logging](https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html) | Java 8+ | N/A | none | +| [Java Platform](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ManagementFactory.html) | Java 8+ | [opentelemetry-runtime-telemetry-java8](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-runtime-telemetry-java8),
[opentelemetry-runtime-telemetry-java17](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-runtime-telemetry-java17),
[opentelemetry-resources](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-resources) | [JVM Runtime Metrics] | +| [Javalin](https://javalin.io/) | 5.0+ | N/A | 提供 `http.route` [2] | +| [JAX-RS](https://javaee.github.io/javaee-spec/javadocs/javax/ws/rs/package-summary.html) | 0.5+ | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [JAX-RS Client](https://javaee.github.io/javaee-spec/javadocs/javax/ws/rs/client/package-summary.html) | 1.1+ | N/A | [HTTP Client Spans]、[HTTP Client Metrics] | +| [JAX-WS](https://jakarta.ee/specifications/xml-web-services/2.3/apidocs/javax/xml/ws/package-summary.html) | 2.0+ (not including 3.0+ yet) | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [JBoss Log Manager](https://github.com/jboss-logging/jboss-logmanager) | 1.1+ | N/A | none | +| [JDBC](https://docs.oracle.com/javase/8/docs/api/java/sql/package-summary.html) | Java 8+ | [opentelemetry-jdbc](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-jdbc) | [Database Client Spans]、[Database Client Metrics] [6] | +| [Jedis](https://github.com/xetorthio/jedis) | 1.4+ | N/A | [Database Client Spans]、[Database Client Metrics] [6] | +| [JMS](https://javaee.github.io/javaee-spec/javadocs/javax/jms/package-summary.html) | 1.1+ | N/A | [Messaging Spans] | +| [Jodd HTTP](https://http.jodd.org/) | 4.2+ | N/A | [HTTP Client Spans]、[HTTP Client Metrics] | +| [JSP](https://javaee.github.io/javaee-spec/javadocs/javax/servlet/jsp/package-summary.html) | 2.3.x only | N/A | 控制器 Span [3] | +| [Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) | 1.0+ | N/A | 上下文传播 | +| [Ktor](https://github.com/ktorio/ktor) | 1.0+ | [opentelemetry-ktor-1.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-ktor-1.0),
[opentelemetry-ktor-2.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-ktor-2.0),
[opentelemetry-ktor-3.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-ktor-3.0) | [HTTP Client Spans]、[HTTP Client Metrics]、[HTTP Server Spans]、[HTTP Server Metrics] | +| [Kubernetes Client](https://github.com/kubernetes-client/java) | 7.0+ | N/A | [HTTP Client Spans] | +| [Lettuce](https://github.com/lettuce-io/lettuce-core) | 4.0+ | [opentelemetry-lettuce-5.1](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-lettuce-5.1) | [Database Client Spans]、[Database Client Metrics] [6] | +| [Log4j 1](https://logging.apache.org/log4j/1.2/) | 1.2+ | N/A | none | +| [Log4j 2](https://logging.apache.org/log4j/2.x/) | 2.11+ | [opentelemetry-log4j-appender-2.17](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-log4j-appender-2.17),
[opentelemetry-log4j-context-data-2.17-autoconfigure](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-log4j-context-data-2.17) | none | +| [Logback](http://logback.qos.ch/?disable_http_check) | 1.0+ | [opentelemetry-logback-appender-1.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-logback-appender-1.0),
[opentelemetry-logback-mdc-1.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-logback-mdc-1.0) | none | +| [Micrometer](https://micrometer.io/) | 1.5+ (disabled by default) | [opentelemetry-micrometer-1.5](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-micrometer-1.5) | none | +| [MongoDB Driver](https://mongodb.github.io/mongo-java-driver/) | 3.1+ | [opentelemetry-mongo-3.1](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-mongo-3.1) | [Database Client Spans]、[Database Client Metrics] [6] | +| [MyBatis](https://mybatis.org/mybatis-3/) | 3.2+ | N/A | none | +| [Netty HTTP codec [5]](https://github.com/netty/netty) | 3.8+ | [opentelemetry-netty-4.1](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-netty-4.1) | [HTTP Client Spans]、[HTTP Client Metrics]、[HTTP Server Spans]、[HTTP Server Metrics] | +| [OpenAI Java SDK](https://github.com/openai/openai-java) | 1.1+ | [openai-java-1.1](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/openai-java-1.1) | [GenAI Client Spans]、[GenAI Client Metrics] | +| [OpenSearch Rest Client](https://github.com/opensearch-project/opensearch-java) | 1.0+ | | [Database Client Spans]、[Database Client Metrics] [6] | +| [OkHttp](https://github.com/square/okhttp/) | 2.2+ | [opentelemetry-okhttp-3.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-okhttp-3.0) | [HTTP Client Spans]、[HTTP Client Metrics] | +| [Oracle UCP](https://docs.oracle.com/database/121/JJUCP/) | 11.2+ | [opentelemetry-oracle-ucp-11.2](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-oracle-ucp-11.2) | [Database Pool Metrics] | +| [OSHI](https://github.com/oshi/oshi/) | 5.3.1+ | [opentelemetry-oshi](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-oshi) | [System Metrics] (partial support) | +| [Play MVC](https://github.com/playframework/playframework) | 2.4+ | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [Play WS](https://github.com/playframework/play-ws) | 1.0+ | N/A | [HTTP Client Spans]、[HTTP Client Metrics] | +| [PowerJob](http://www.powerjob.tech/?disable_http_check) | 4.0.0+ | N/A | none | +| [Quarkus Resteasy Reactive](https://quarkus.io/extensions/io.quarkus/quarkus-resteasy-reactive/) | 2.16.7+ | N/A | 提供 `http.route` [2] | +| [Quartz](https://www.quartz-scheduler.org/) | 2.0+ | [opentelemetry-quartz-2.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-quartz-2.0) | none | +| [R2DBC](https://r2dbc.io/) | 1.0+ | [opentelemetry-r2dbc-1.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-r2dbc-1.0) | [Database Client Spans]、[Database Client Metrics] [6] | +| [RabbitMQ Client](https://github.com/rabbitmq/rabbitmq-java-client) | 2.7+ | N/A | [Messaging Spans] | +| [Ratpack](https://github.com/ratpack/ratpack) | 1.4+ | [opentelemetry-ratpack-1.7](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-ratpack-1.7) | [HTTP Client Spans]、[HTTP Client Metrics]、[HTTP Server Spans]、[HTTP Server Metrics] | +| [Reactor](https://github.com/reactor/reactor-core) | 3.1+ | [opentelemetry-reactor-3.1](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-reactor-3.1) | 上下文传播 | +| [Reactor Netty](https://github.com/reactor/reactor-netty) | 0.9+ | N/A | [HTTP Client Spans]、[HTTP Client Metrics] | +| [Rediscala](https://github.com/etaty/rediscala) | 1.8+ | N/A | [Database Client Spans]、[Database Client Metrics] [6] | +| [Redisson](https://github.com/redisson/redisson) | 3.0+ | N/A | [Database Client Spans]、[Database Client Metrics] [6] | +| [RESTEasy](https://resteasy.dev/) | 3.0+ (not including 6.0+ yet) | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [Restlet](https://restlet.github.io/) | 1.0+ | [opentelemetry-restlet-1.1](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-restlet-1.1),
[opentelemetry-restlet-2.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-restlet-2.0) | [HTTP Server Spans]、[HTTP Server Metrics] | +| [RMI](https://docs.oracle.com/en/java/javase/11/docs/api/java.rmi/java/rmi/package-summary.html) | Java 8+ | | [RPC Client Spans]、[RPC Server Spans] | +| [RxJava](https://github.com/ReactiveX/RxJava) | 1.0+ | [opentelemetry-rxJava-1.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-rxjava-1.0),
[opentelemetry-rxJava-2.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-rxjava-2.0),
[opentelemetry-rxJava-3.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-rxjava-3.0),
[opentelemetry-rxJava-3.1.1](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-rxjava-3.1.1) | 上下文传播 | +| [Scala ForkJoinPool](https://www.scala-lang.org/api/2.12.0/scala/concurrent/forkjoin/package$$ForkJoinPool$.html) | 2.8+ | N/A | 上下文传播 | +| [Servlet](https://javaee.github.io/javaee-spec/javadocs/javax/servlet/package-summary.html) | 2.2+ | N/A | [HTTP Server Spans]、[HTTP Server Metrics] | +| [Spark Web Framework](https://github.com/perwendel/spark) | 2.3+ | N/A | 提供 `http.route` [2] | +| [Spring Batch](https://spring.io/projects/spring-batch) | 3.0+ (not including 5.0+ yet) | N/A | none | +| [Spring Boot](https://spring.io/projects/spring-boot) | | [opentelemetry-spring-boot-resources](/docs/zero-code/java/spring-boot-starter/) | none | +| [Spring Cloud AWS](https://spring.io/projects/spring-cloud-aws) | 3.0+ | N/A | [Messaging Spans] | +| [Spring Cloud Gateway](https://github.com/spring-cloud/spring-cloud-gateway) | 2.0+ | N/A | 提供 `http.route` [2] | +| [Spring Core](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/package-summary.html) | 2.0+ | N/A | 上下文传播 | +| [Spring Data](https://spring.io/projects/spring-data) | 1.8+ | N/A | none | +| [Spring Integration](https://spring.io/projects/spring-integration) | 4.1+ (not including 6.0+ yet) | [opentelemetry-spring-integration-4.1](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-spring-integration-4.1) | [Messaging Spans] | +| [Spring JMS](https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#jms) | 2.0+ | N/A | [Messaging Spans] | +| [Spring Kafka](https://spring.io/projects/spring-kafka) | 2.7+ | [opentelemetry-spring-kafka-2.7](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-spring-kafka-2.7) | [Messaging Spans] | +| [Spring Pulsar](https://spring.io/projects/spring-pulsar) | 1.0+ | | [Messaging Spans] | +| [Spring RabbitMQ](https://spring.io/projects/spring-amqp) | 1.0+ | N/A | [Messaging Spans] | +| [Spring RestTemplate](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/client/package-summary.html) | 3.1+ | [opentelemetry-spring-web-3.1](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-spring-web-3.1) | [HTTP Client Spans]、[HTTP Client Metrics] | +| [Spring RMI](https://docs.spring.io/spring-framework/docs/4.0.x/javadoc-api/org/springframework/remoting/rmi/package-summary.html) | 4.0+ | N/A | [RPC Client Spans]、[RPC Server Spans] | +| [Spring Scheduling](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/scheduling/package-summary.html) | 3.1+ | N/A | none | +| [Spring Web MVC](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/servlet/mvc/package-summary.html) | 3.1+ | [opentelemetry-spring-webmvc-5.3](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-spring-webmvc-5.3),
[opentelemetry-spring-webmvc-6.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-spring-webmvc-6.0) | [HTTP Server Spans]、[HTTP Server Metrics]、提供 `http.route` [2]、控制器 Span [3] | +| [Spring Web Services](https://spring.io/projects/spring-ws) | 2.0+ (not including 4.0+ yet) | N/A | none | +| [Spring WebFlux](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/reactive/package-summary.html) | 5.3+ | [opentelemetry-spring-webflux-5.3](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-spring-webflux-5.3) | [HTTP Client Spans]、[HTTP Client Metrics]、[HTTP Server Spans]、[HTTP Server Metrics]、提供 `http.route` [2]、控制器 Span [3] | +| [Spymemcached](https://github.com/couchbase/spymemcached) | 2.12+ | N/A | [Database Client Spans]、[Database Client Metrics] [6] | +| [Tomcat JDBC Pool](https://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html) | 8.5+ | N/A | [Database Pool Metrics] | +| [Twilio](https://github.com/twilio/twilio-java) | 6.6+ (not including 8.0+ yet) | N/A | none | +| [Undertow](https://undertow.io/) | 1.4+ | N/A | [HTTP Server Spans]、[HTTP Server Metrics] | +| [Vaadin](https://vaadin.com/) | 14.2+ | N/A | 提供 `http.route` [2]、控制器 Span [3] | +| [Vert.x HttpClient](https://vertx.io/docs/apidocs/io/vertx/core/http/HttpClient.html) | 3.0+ | N/A | [HTTP Client Spans]、[HTTP Client Metrics] | +| [Vert.x Kafka Client](https://vertx.io/docs/vertx-kafka-client/java/) | 3.6+ | N/A | [Messaging Spans] | +| [Vert.x Redis Client](https://vertx.io/docs/vertx-redis-client/java/) | 4.0+ | N/A | [Database Client Spans]、[Database Client Metrics] [6] | +| [Vert.x RxJava2](https://vertx.io/docs/vertx-rx/java2/) | 3.5+ | N/A | 仅上下文传播 | +| [Vert.x SQL Client](https://github.com/eclipse-vertx/vertx-sql-client/) | 4.0+ | N/A | [Database Client Spans]、[Database Client Metrics] [6] | +| [Vert.x Web](https://vertx.io/docs/vertx-web/java/) | 3.0+ | N/A | 提供 `http.route` [2] | +| [Vibur DBCP](https://www.vibur.org/) | 11.0+ | [opentelemetry-vibur-dbcp-11.0](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-vibur-dbcp-11.0) | [Database Pool Metrics] | +| [XXL-JOB](https://www.xuxueli.com/xxl-job/en/) | 1.9.2+ | N/A | none | +| [ZIO](https://zio.dev/) | 2.0+ | N/A | 上下文传播 | + + + +**[1]** 独立库插桩指的是无需依赖 Java 代理即可使用的插桩方式。 + +**[2]** 提供 `http.route`：为现有的 `SERVER` Span 提供基于路由的 Span 名称。如果适用，为现有的 `SERVER` Span 和指标提供 `http.route` Span 和指标属性。 + +**[3]** 控制器 Span 是捕获控制器、视图执行的 `INTERNAL` Span。请参阅[禁用控制器、视图 Span](/docs/zero-code/java/agent/disable/#suppressing-controller-andor-view-spans)。 + +**[4]** 该库的较新版本已内置遥测功能。 + +**[5]** 目前不支持捕获 HTTP/2 流量。 + +**[6]** 数据库客户端指标适用于选择加入[语义约定稳定性](/docs/specs/semconv/non-normative/db-migration/)的用户。 + +[Elasticsearch Client Spans]: /docs/specs/semconv/database/elasticsearch/ +[HTTP Server Spans]: /docs/specs/semconv/http/http-spans/#http-server +[HTTP Client Spans]: /docs/specs/semconv/http/http-spans/#http-client-span +[HTTP Server Metrics]: /docs/specs/semconv/http/http-metrics/#http-server +[HTTP Client Metrics]: /docs/specs/semconv/http/http-metrics/#http-client +[RPC Server Spans]: /docs/specs/semconv/rpc/rpc-spans/#rpc-server-span +[RPC Client Spans]: /docs/specs/semconv/rpc/rpc-spans/#rpc-client-span +[RPC Server Metrics]: /docs/specs/semconv/rpc/rpc-metrics/#rpc-server +[RPC Client Metrics]: /docs/specs/semconv/rpc/rpc-metrics/#rpc-client +[Messaging Spans]: /docs/specs/semconv/messaging/messaging-spans/ +[Database Client Spans]: /docs/specs/semconv/database/database-spans/ +[Database Client Metrics]: /docs/specs/semconv/database/database-metrics/ +[Database Pool Metrics]: /docs/specs/semconv/database/database-metrics/ +[JVM Runtime Metrics]: /docs/specs/semconv/runtime/jvm-metrics/ +[System Metrics]: /docs/specs/semconv/system/system-metrics/ +[GraphQL Server Spans]: /docs/specs/semconv/graphql/graphql-spans/ +[FaaS Server Spans]: /docs/specs/semconv/faas/faas-spans/ +[GenAI Client Spans]: /docs/specs/semconv/gen-ai/gen-ai-spans/ +[GenAI Client Metrics]: /docs/specs/semconv/gen-ai/gen-ai-metrics/#generative-ai-client-metrics + +## 应用服务器 {#application-servers} + + + +以下是经过该代理定期测试的应用服务器： + +| 应用服务器 | 版本 | JVM | +| ------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------ | +| [Jetty](https://www.eclipse.org/jetty/) | 9.4.53 | OpenJDK 8, 11, 17, 21, 23
OpenJ9 8, 11, 17, 21, 23 | +| [Jetty](https://www.eclipse.org/jetty/) | 10.0.19, 11.0.19 | OpenJDK 11, 17, 21, 23
OpenJ9 11, 17, 21, 23 | +| [Jetty](https://www.eclipse.org/jetty/) | 12.0.6 | OpenJDK 17, 21, 23
OpenJ9 17, 21, 23 | +| [Open Liberty](https://openliberty.io/) | 20.0.0.12 | OpenJDK 8, 11
OpenJ9 8, 11 | +| [Open Liberty](https://openliberty.io/) | 21.0.0.12, 22.0.0.12 | OpenJDK 8, 11, 17
OpenJ9 8, 11, 17 | +| [Open Liberty](https://openliberty.io/) | 23.0.0.12 | OpenJDK 8, 11, 17, 20
OpenJ9 8, 11, 17, 20 | +| [Payara](https://www.payara.fish/) | 5.2020.6, 5.2021.8 | OpenJDK 8, 11
OpenJ9 8, 11 | +| [Payara](https://www.payara.fish/) | 6.2023.12 | OpenJDK 11, 17
OpenJ9 11, 17, 21, 23 | +| [Tomcat](https://tomcat.apache.org/) | 7.0.109 | OpenJDK 8
OpenJ9 8 | +| [Tomcat](https://tomcat.apache.org/) | 8.5.98, 9.0.85 | OpenJDK 8, 11, 17, 21, 23
OpenJ9 8, 11, 17, 21, 23 | +| [Tomcat](https://tomcat.apache.org/) | 10.1.18 | OpenJDK 11, 17, 21, 23
OpenJ9 11, 17, 21, 23 | +| [TomEE](https://tomee.apache.org/) | 7.0.9, 7.1.4 | OpenJDK 8
OpenJ9 8 | +| [TomEE](https://tomee.apache.org/) | 8.0.16 | OpenJDK 8, 11, 17, 21, 23
OpenJ9 8, 11, 17, 21, 23 | +| [TomEE](https://tomee.apache.org/) | 9.1.2 | OpenJDK 11, 17, 21, 23
OpenJ9 11, 17, 21, 23 | +| [Websphere Traditional](https://www.ibm.com/uk-en/cloud/websphere-application-server) | 8.5.5.22, 9.0.5.14 | IBM JDK 8 | +| [WildFly](https://www.wildfly.org/) | 13.0.0.Final | OpenJDK 8
OpenJ9 8 | +| [WildFly](https://www.wildfly.org/) | 17.0.1.Final, 21.0.0.Final | OpenJDK 8, 11, 17, 21
OpenJ9 8, 11, 17, 21 | +| [WildFly](https://www.wildfly.org/) | 28.0.1.Final, 29.0.1.Final, 30.0.1.Final | OpenJDK 11, 17, 21, 23
OpenJ9 11, 17, 21, 23 | diff --git a/content/zh/docs/zero-code/java/spring-boot-starter/_index.md b/content/zh/docs/zero-code/java/spring-boot-starter/_index.md new file mode 100644 index 000000000000..3d3e38d395cc --- /dev/null +++ b/content/zh/docs/zero-code/java/spring-boot-starter/_index.md @@ -0,0 +1,19 @@ +--- +title: Spring Boot 启动器 +default_lang_commit: 8c61967612481a3b8d48926cfaa3c92ce7c46906 +aliases: + - /docs/languages/java/automatic/spring-boot + - /docs/zero-code/java/agent/spring-boot + - /docs/zero-code/java/spring-boot +--- + +你可以通过两种方式为 [Spring Boot](https://spring.io/projects/spring-boot) 应用程序配置 OpenTelemetry 插桩。 + +1. 为 Spring Boot 应用程序配置插桩的默认选择是使用带有字节码插桩的 [**OpenTelemetry Java 代理**](../agent)： + - 提供比 OpenTelemetry 启动器更多的开箱即用的插桩 +2. **OpenTelemetry Spring Boot 启动器**可以帮助你： + - 适用于 **Spring Boot Native image** 应用程序，这类应用中 OpenTelemetry Java 代理无法正常工作 + - 当 OpenTelemetry Java 代理的**启动开销**超出您的需求时 + - 已在使用其他 Java 监控代理的场景，因为 OpenTelemetry Java 代理可能与其他代理存在兼容性问题 + - 可通过 **Spring Boot 配置文件**（`application.properties`、`application.yml`）进行配置， + 这种配置方式与 OpenTelemetry Java 代理不兼容 diff --git a/content/zh/docs/zero-code/java/spring-boot-starter/additional-instrumentations.md b/content/zh/docs/zero-code/java/spring-boot-starter/additional-instrumentations.md new file mode 100644 index 000000000000..1695cbc0ad24 --- /dev/null +++ b/content/zh/docs/zero-code/java/spring-boot-starter/additional-instrumentations.md @@ -0,0 +1,35 @@ +--- +title: 额外的插桩 +default_lang_commit: 2faf0ea68ab12d5fc5423fc98031a3d287b3f88e +weight: 60 +--- + +OpenTelemetry Spring Boot 启动器提供了[开箱即用的插桩](../out-of-the-box-instrumentation)，你可以使用额外的插桩来增强它。 + +## Log4j2 插桩 {#log4j2-instrumentation} + +你必须将 OpenTelemetry appender 添加到你的 `log4j2.xml` 文件中： + +```xml + + + + + + + + + + + +``` + +你可以在 [Log4j](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/log4j/log4j-appender-2.17/library/README.md) 插桩库中找到 OpenTelemetry appender的更多配置选项。 + +| 系统属性 | 类型 | 默认值 | 描述 | +| --------------------------------------------- | ------- | ------ | -------------------------------------------------------------- | +| `otel.instrumentation.log4j-appender.enabled` | Boolean | true | 启用使用 `OpenTelemetry` 实例配置 Log4j OpenTelemetry 附加器。 | + +## 插桩库 {#instrumentation-libraries} + +你可以使用 [OpenTelemetry 插桩库](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks) 配置其他插桩。 diff --git a/content/zh/docs/zero-code/java/spring-boot-starter/annotations.md b/content/zh/docs/zero-code/java/spring-boot-starter/annotations.md new file mode 100644 index 000000000000..1d16c7b548a0 --- /dev/null +++ b/content/zh/docs/zero-code/java/spring-boot-starter/annotations.md @@ -0,0 +1,118 @@ +--- +title: 注解 +default_lang_commit: c392c714849921cd56aca8ca99ab11e0e4cb16f4 +weight: 50 +--- + + + + +对于大多数用户来说，开箱即用的插桩功能已经完全足够，无需进行任何其他操作。 +然而，在某些情况下，用户可能希望为自己的自定义代码创建 [Span](/docs/concepts/signals/traces/#spans)，而无需进行许多代码更改。 + +如果你在方法上添加 `WithSpan` 注解，则该方法会被包装在一个 Span 中。 +`SpanAttribute` 注解还允许你将方法参数作为属性捕获。 + + + +```java +package otel; + +import io.opentelemetry.api.trace.Span; +import io.opentelemetry.api.trace.SpanKind; +import io.opentelemetry.instrumentation.annotations.SpanAttribute; +import io.opentelemetry.instrumentation.annotations.WithSpan; +import org.springframework.stereotype.Component; + +/** 测试 WithSpan */ +@Component +public class TracedClass { + + @WithSpan + public void tracedMethod() {} + + @WithSpan(value = "span name") + public void tracedMethodWithName() { + Span currentSpan = Span.current(); + currentSpan.addEvent("ADD EVENT TO tracedMethodWithName SPAN"); + currentSpan.setAttribute("isTestAttribute", true); + } + + @WithSpan(kind = SpanKind.CLIENT) + public void tracedClientSpan() {} + + public void tracedMethodWithAttribute(@SpanAttribute("attributeName") String parameter) {} +} +``` + + +{{% alert title="注意" %}} +OpenTelemetry 注解基于代理模式使用 Spring AOP。 + +这些注解仅适用于代理的方法。 +你可以在 [Spring 文档](https://docs.spring.io/spring-framework/reference/core/aop/proxying.html)中了解更多信息。 + +在下面的示例中，当调用 GET 端点时，`WithSpan` 注解不会起作用： + +```java +@RestController +public class MyControllerManagedBySpring { + + @GetMapping("/ping") + public void aMethod() { + anotherMethod(); + } + + @WithSpan + public void anotherMethod() { + } +} +``` + +{{% /alert %}} + +{{% alert title="注意" %}} + +要使用 OpenTelemetry 注解，你需要向项目中添加 Spring Boot 启动器 AOP 依赖： + +{{< tabpane text=true >}} {{% tab header="Maven (`pom.xml`)" lang=Maven %}} + +```xml + + + org.springframework.boot + spring-boot-starter-aop + + +``` + +{{% /tab %}} {{% tab header="Gradle (`build.gradle`)" lang=Gradle %}} + +```kotlin +dependencies { + implementation("org.springframework.boot:spring-boot-starter-aop") +} +``` + +{{% /tab %}} {{< /tabpane >}} + +{{% /alert %}} + +你可以通过将 `otel.instrumentation.annotations.enabled` 属性设置为 `false` 来禁用 OpenTelemetry 注解。 + +你可以使用 `WithSpan` 注解的元素来自定义 Span： + +| 名称 | 类型 | 描述 | 默认值 | +| ------- | ---------- | --------- | ------------------- | +| `value` | `String` | Span 名称 | 类名.方法名 | +| `kind` | `SpanKind` | Span 类型 | `SpanKind.INTERNAL` | + +你可以使用 `SpanAttribute` 注解的 `value` 元素来自定义属性名称： + +| 名称 | 类型 | 描述 | 默认值 | +| ------- | -------- | -------- | ---------- | +| `value` | `String` | 属性名称 | 方法参数名 | + +## 下一步操作 {#next-steps} + +除使用注解外，OpenTelemetry API 还允许你获取一个可用于[自定义插桩](../api)的追踪器。 diff --git a/content/zh/docs/zero-code/java/spring-boot-starter/api.md b/content/zh/docs/zero-code/java/spring-boot-starter/api.md new file mode 100644 index 000000000000..e4db8165e1f4 --- /dev/null +++ b/content/zh/docs/zero-code/java/spring-boot-starter/api.md @@ -0,0 +1,72 @@ +--- +title: 使用 API 扩展插桩功能 +linkTitle: 使用 API 扩展插桩功能 +default_lang_commit: c392c714849921cd56aca8ca99ab11e0e4cb16f4 +description: 结合 OpenTelemetry API 与 Spring Boot 启动器，通过自定义 Span 和指标扩展自动生成的遥测数据。 +weight: 21 +--- + +## Introduction {#introduction} + +除开箱即用的插桩功能外，你还可借助 OpenTelemetry API，通过自定义手动插桩的方式对 Spring 启动器进行扩展。 +这使你能够为自己的代码创建 [Span](/docs/concepts/signals/traces/#spans) 和[指标](/docs/concepts/signals/metrics)， +无需进行过多代码修改。 + +所需的依赖项已包含在 Spring Boot 启动器中。 + +## OpenTelemetry {#opentelemetry} + +Spring Boot 启动器是一个特殊的案例，其中 `OpenTelemetry` 可作为 Spring Bean 使用。 +只需将 `OpenTelemetry` 注入到你的 Spring 组件中即可。 + +## Span {#span} + +{{% alert title="Note" %}} + + + +对于最常见的使用场景，使用 `@WithSpan` 注解而不是手动插桩。 +请参阅[注解](../annotations)以获取更多信息。 + +{{% /alert %}} + +```java +import io.opentelemetry.api.OpenTelemetry; +import io.opentelemetry.api.trace.Tracer; + +@Controller +public class MyController { + private final Tracer tracer; + + public MyController(OpenTelemetry openTelemetry) { + this.tracer = openTelemetry.getTracer("application"); + } +} +``` + +使用 `Tracer` 创建一个 Span，如 [Span](/docs/languages/java/api/#span) 部分所述。 + +完整示例可在[示例代码库][example repository]中找到。 + +## Meter {#meter} + +```java +import io.opentelemetry.api.OpenTelemetry; +import io.opentelemetry.api.metrics.Meter; + +@Controller +public class MyController { + private final Meter meter; + + public MyController(OpenTelemetry openTelemetry) { + this.meter = openTelemetry.getMeter("application"); + } +} +``` + +使用 `Meter` 创建一个指标，如 [Meter](/docs/languages/java/api/#meter) 部分所述。 + +完整示例可在[示例代码库][example repository]中找到。 + +[example repository]: https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/spring-native diff --git a/content/zh/docs/zero-code/java/spring-boot-starter/getting-started.md b/content/zh/docs/zero-code/java/spring-boot-starter/getting-started.md new file mode 100644 index 000000000000..b823e1271ad5 --- /dev/null +++ b/content/zh/docs/zero-code/java/spring-boot-starter/getting-started.md @@ -0,0 +1,113 @@ +--- +title: 快速开始 +default_lang_commit: c392c714849921cd56aca8ca99ab11e0e4cb16f4 +weight: 20 +cSpell:ignore: springboot +--- + +{{% alert title="Note" %}} + +你也可以使用 [Java 代理](../../agent)为你的 Spring Boot 应用程序配置插桩。 +有关优缺点，请参见 [Java 零代码插桩](..). + +{{% /alert %}} + +### 兼容性 {#compatibility} + +OpenTelemetry Spring Boot 启动器适用于 Spring Boot 2.6+ 和 3.1+ 版本，以及 Spring Boot Native image 应用程序。 +[opentelemetry-java-examples/spring-native](https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/spring-native)仓库包含了一个使用 OpenTelemetry Spring Boot 启动器配置插桩的 Spring Boot Native image 应用程序的示例。 + +### 依赖管理 {#dependency-management} + +物料清单（[BOM](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#bill-of-materials-bom-poms)） 确保依赖（含传递性依赖）版本一致性 + +{{% alert title="注意" %}} + +使用 Maven 时，请在项目中的任何其他 BOM 之前导入 OpenTelemetry BOM。 +例如，如果您导入 `spring-boot-dependencies` BOM，则必须在 OpenTelemetry BOM 之后声明它。 + +使用 Gradle 时，当存在多个 BOM（物料清单）时，对于同一依赖，Gradle 会选择[最新版本](https://docs.gradle.org/current/userguide/dependency_resolution.html#2_perform_conflict_resolution)，因此 BOM 的声明顺序并不重要。 + +{{% /alert %}} + + + +下面的示例展示了如何使用 Maven 导入 OpenTelemetry BOM: + +```xml + + + + io.opentelemetry.instrumentation + opentelemetry-instrumentation-bom + {{% param vers.instrumentation %}} + pom + import + + + +``` + +使用 Gradle 和 Spring Boot 时，有两种方式可以导入 BOM。 + +你可以通过在 `dependencies` 中添加 BOM 来使用 Gradle 的原生 BOM 支持： + +```kotlin +import org.springframework.boot.gradle.plugin.SpringBootPlugin + +plugins { + id("java") + id("org.springframework.boot") version "3.2.O" +} + +dependencies { + implementation(platform(SpringBootPlugin.BOM_COORDINATES)) + implementation(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:{{% param vers.instrumentation %}}")) +} +``` + +使用 Gradle 时，另一种方式是使用 `io.spring.dependency-management` 插件并在 `dependencyManagement` 中导入 BOM： + +```kotlin +plugins { + id("java") + id("org.springframework.boot") version "3.2.O" + id("io.spring.dependency-management") version "1.1.0" +} + +dependencyManagement { + imports { + mavenBom("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:{{% param vers.instrumentation %}}") + } +} +``` + +{{% alert title="注意" %}} + +在使用 Gradle 进行配置时，请注意不要混淆不同的配置方式。 +例如，不要在 `dependencies` 中使用 `implementation(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:{{% param vers.instrumentation %}}"))` 与 `io.spring.dependency-management` 插件。 + +{{% /alert %}} + +#### OpenTelemetry 启动器依赖 {#opentelemetry-starter-dependency} + +添加以下依赖以启用 OpenTelemetry 启动器。 + +OpenTelemetry 启动器使用 OpenTelemetry Spring Boot 的[自动配置](https://docs.spring.io/spring-boot/reference/using/auto-configuration.html)。 + +{{< tabpane text=true >}} {{% tab header="Maven (`pom.xml`)" lang=Maven %}} + +```xml + + io.opentelemetry.instrumentation + opentelemetry-spring-boot-starter + +``` + +{{% /tab %}} {{% tab header="Gradle (`build.gradle`)" lang=Gradle %}} + +```kotlin +implementation("io.opentelemetry.instrumentation:opentelemetry-spring-boot-starter") +``` + +{{% /tab %}} {{< /tabpane>}} diff --git a/content/zh/docs/zero-code/java/spring-boot-starter/other-spring-autoconfig.md b/content/zh/docs/zero-code/java/spring-boot-starter/other-spring-autoconfig.md new file mode 100644 index 000000000000..36c385ca2c2f --- /dev/null +++ b/content/zh/docs/zero-code/java/spring-boot-starter/other-spring-autoconfig.md @@ -0,0 +1,47 @@ +--- +title: 其他 Spring 自动配置 +default_lang_commit: f92dd4fbd069d7f6884b54b5a7961562bb40d656 +weight: 70 +cSpell:ignore: autoconfigurations +--- + + + + +你可以使用 OpenTelemetry Zipkin 启动器，而不是使用 OpenTelemetry Spring 启动器。 + +## Zipkin 启动器 {#zipkin-starter} + +OpenTelemetry Zipkin Exporter Starter 是一个启动器包，其中包含设置分布式追踪所需的 `opentelemetry-api`、`opentelemetry-sdk`、`opentelemetry-extension-annotations`、`opentelemetry-logging-exporter`、`opentelemetry-spring-boot-autoconfigurations` 和 Spring 框架启动器。 +它还提供了 [opentelemetry-exporters-zipkin](https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/zipkin) 构件和相应的导出器自动配置。 + +如果运行时类路径中存在导出器，且 Spring 应用程序上下文中缺少该导出器的 Spring Bean，则会初始化一个导出器 Bean，并将其添加到活动追踪器提供程序中的简单跨度处理器中。 +有关更多详细信息，请参阅 [实现 (OpenTelemetryAutoConfiguration.java)](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/OpenTelemetryAutoConfiguration.java)。 + +{{< tabpane text=true >}} {{% tab header="Maven (`pom.xml`)" lang=Maven %}} + +```xml + + + io.opentelemetry + opentelemetry-exporter-zipkin + {{% param vers.otel %}} + + +``` + +{{% /tab %}} {{% tab header="Gradle (`build.gradle`)" lang=Gradle %}} + +```kotlin +dependencies { + implementation("io.opentelemetry:opentelemetry-exporter-zipkin:{{% param vers.otel %}}") +} +``` + +{{% /tab %}} {{< /tabpane>}} + +### 配置 {#configurations} + +| 属性 | 默认值 | ConditionalOnClass | +| ------------------------------ | ------ | -------------------- | +| `otel.exporter.zipkin.enabled` | true | `ZipkinSpanExporter` | diff --git a/content/zh/docs/zero-code/java/spring-boot-starter/out-of-the-box-instrumentation.md b/content/zh/docs/zero-code/java/spring-boot-starter/out-of-the-box-instrumentation.md new file mode 100644 index 000000000000..043f3dbdc58f --- /dev/null +++ b/content/zh/docs/zero-code/java/spring-boot-starter/out-of-the-box-instrumentation.md @@ -0,0 +1,271 @@ +--- +title: 开箱即用的插桩 +default_lang_commit: 0b22ed7b760c66407308d5a59053b620ac06a1fa +weight: 40 +cSpell:ignore: logback webflux webmvc +--- + + + + +多种框架都提供开箱即用的插桩功能： + +| 框架 | 特性 | 默认值 | +| --------------------- | ----------------------------------------------- | ------ | +| JDBC | `otel.instrumentation.jdbc.enabled` | true | +| Logback | `otel.instrumentation.logback-appender.enabled` | true | +| Logback MDC | `otel.instrumentation.logback-mdc.enabled` | true | +| Spring Web | `otel.instrumentation.spring-web.enabled` | true | +| Spring Web MVC | `otel.instrumentation.spring-webmvc.enabled` | true | +| Spring WebFlux | `otel.instrumentation.spring-webflux.enabled` | true | +| Kafka | `otel.instrumentation.kafka.enabled` | true | +| MongoDB | `otel.instrumentation.mongo.enabled` | true | +| Micrometer | `otel.instrumentation.micrometer.enabled` | false | +| R2DBC (reactive JDBC) | `otel.instrumentation.r2dbc.enabled` | true | + +## 选择性的打开插桩 {#turn-on-instrumentations-selectively} + +要仅使用特定的插桩，首先通过将 `otel.instrumentation.common.default-enabled` 属性设置为 `false` 来关闭所有插桩。 +然后，逐个启用插桩。 + +例如，如果你只想启用 JDBC 插桩，请将 `otel.instrumentation.jdbc.enabled` 设置为 `true`。 + +## 通用插桩配置 {#common-instrumentation-configuration} + +所有数据库插桩的通用属性： + +| 系统特性 | 类型 | 默认值 | 描述 | +| ------------------------------------------------------------ | ------- | ------ | ---------------------- | +| `otel.instrumentation.common.db-statement-sanitizer.enabled` | Boolean | true | 启用数据库语句的清理。 | + +## JDBC 插桩 {#jdbc-instrumentation} + +| 系统特性 | 类型 | 默认值 | 描述 | +| ------------------------------------------------------- | ------- | ------ | ---------------------- | +| `otel.instrumentation.jdbc.statement-sanitizer.enabled` | Boolean | true | 启用数据库语句的清理。 | + +## Logback {#logback} + +你可以使用系统特性启用实验性功能以捕获属性： + +| 系统特性 | 类型 | 默认值 | 描述 | +| -------------------------------------------------------------------------------------- | ------- | ------ | -------------------------------------------------------------------------------------------------------- | +| `otel.instrumentation.logback-appender.experimental-log-attributes` | Boolean | false | 启用实验性日志属性 `thread.name` 和 `thread.id` 的捕获。 | +| `otel.instrumentation.logback-appender.experimental.capture-code-attributes` | Boolean | false | 启用[源代码属性][source code attributes]的捕获。请注意，在日志记录位置捕获源代码属性可能会增加性能开销。 | +| `otel.instrumentation.logback-appender.experimental.capture-marker-attribute` | Boolean | false | 启用将 Logback 标记作为属性捕获。 | +| `otel.instrumentation.logback-appender.experimental.capture-key-value-pair-attributes` | Boolean | false | 启用将 Logback 键值对作为属性捕获。 | +| `otel.instrumentation.logback-appender.experimental.capture-logger-context-attributes` | Boolean | false | 启用将 Logback 日志上下文属性作为属性捕获。 | +| `otel.instrumentation.logback-appender.experimental.capture-mdc-attributes` | String | | 以逗号分隔的要捕获的 MDC 属性列表。使用通配符 `*` 可捕获所有属性。 | + +[source code attributes]: /docs/specs/semconv/general/attributes/#source-code-attributes + +或者，你可以通过在 `logback.xml` 或 `logback-spring.xml` 文件中添加 OpenTelemetry Logback appender 来启用这些功能： + +```xml + + + + + + %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n + + + + + false + true + true + true + true + * + + + + + + +``` + +## Spring Web 自动配置 {#spring-web-autoconfiguration} + +为 [opentelemetry-spring-web-3.1](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-web/spring-web-3.1/library) 中定义的 `RestTemplate` 跟踪拦截器提供自动配置。 +此自动配置通过应用 `RestTemplate` Bean 后置处理器，对所有使用 Spring `RestTemplate` Bean 发送的请求进行插桩。 +此功能支持 spring web 版本 3.1+。 +要了解有关 OpenTelemetry `RestTemplate` 拦截器的更多信息，请参见 +[opentelemetry-spring-web-3.1](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-web/spring-web-3.1/library)。 + +支持以下几种创建 `RestTemplate` 的方式： + + + +```java +package otel; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.web.client.RestTemplate; + +@Configuration +public class RestTemplateConfig { + + @Bean + public RestTemplate restTemplate() { + return new RestTemplate(); + } +} +``` + + +```java +package otel; + +import org.springframework.boot.web.client.RestTemplateBuilder; +import org.springframework.web.bind.annotation.RestController; +import org.springframework.web.client.RestTemplate; + +@RestController +public class RestTemplateController { + + private final RestTemplate restTemplate; + + public RestTemplateController(RestTemplateBuilder restTemplateBuilder) { + restTemplate = restTemplateBuilder.rootUri("http://localhost:8080").build(); + } +} +``` + + +支持以下几种创建 `RestClient` 的方式： + + + +```java +package otel; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.web.client.RestClient; + +@Configuration +public class RestClientConfig { + + @Bean + public RestClient restClient() { + return RestClient.create(); + } +} +``` + + +```java +package otel; + +import org.springframework.web.bind.annotation.RestController; +import org.springframework.web.client.RestClient; + +@RestController +public class RestClientController { + + private final RestClient restClient; + + public RestClientController(RestClient.Builder restClientBuilder) { + restClient = restClientBuilder.baseUrl("http://localhost:8080").build(); + } +} +``` + + +正如使用 Java 代理一样，你可以配置捕获以下实体： + +- [HTTP 请求和响应头](/docs/zero-code/java/agent/instrumentation/http/#capturing-http-request-and-response-headers) +- [已知的 HTTP 方法](/docs/zero-code/java/agent/instrumentation/http/#configuring-known-http-methods) +- [实验性的 HTTP 遥测](/docs/zero-code/java/agent/instrumentation/http/#enabling-experimental-http-telemetry) + +## Spring Web MVC 自动配置 {#spring-web-mvc-autoconfiguration} + +此功能通过向应用程序上下文添加一个 [生成遥测数据的 Servlet `Filter`](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/spring/spring-webmvc/spring-webmvc-5.3/library/src/main/java/io/opentelemetry/instrumentation/spring/webmvc/v5_3/WebMvcTelemetryProducingFilter.java) Bean，为 Spring WebMVC 控制器自动配置插桩。 +该过滤器使用服务器 Span 装饰请求执行，如果在 HTTP 请求中接收到传入的跟踪上下文，则会传播该上下文。 +要了解更多关于 OpenTelemetry Spring WebMVC 插桩的信息，请参阅 +[opentelemetry-spring-webmvc-5.3 插桩库](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-webmvc/spring-webmvc-5.3/library)。 + +正如使用 Java 代理一样，你可以配置捕获以下实体： + +- [HTTP 请求和响应头](/docs/zero-code/java/agent/instrumentation/http/#capturing-http-request-and-response-headers) +- [已知的 HTTP 方法](/docs/zero-code/java/agent/instrumentation/http/#configuring-known-http-methods) +- [实验性的 HTTP 遥测](/docs/zero-code/java/agent/instrumentation/http/#enabling-experimental-http-telemetry) + +## Spring WebFlux 自动配置 {#spring-webflux-autoconfiguration} + +为 [opentelemetry-spring-webflux-5.3](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-webflux/spring-webflux-5.3/library) 提供自动配置。 +此自动配置通过应用 Bean 后置处理器，对所有使用 Spring 的 WebClient 和 WebClient Builder Bean 发送的出站 HTTP 请求进行插桩。 +此功能支持 Spring WebFlux 版本 5.0+。 +有关详细信息，请参阅 [opentelemetry-spring-webflux-5.3](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-webflux/spring-webflux-5.3/library)。 + +以下是创建 `WebClient` 的支持方式： + + + +```java +package otel; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.web.reactive.function.client.WebClient; + +@Configuration +public class WebClientConfig { + + @Bean + public WebClient webClient() { + return WebClient.create(); + } +} +``` + + +```java +package otel; + +import org.springframework.web.bind.annotation.RestController; +import org.springframework.web.reactive.function.client.WebClient; + +@RestController +public class WebClientController { + + private final WebClient webClient; + + public WebClientController(WebClient.Builder webClientBuilder) { + webClient = webClientBuilder.baseUrl("http://localhost:8080").build(); + } +} +``` + + +## Kafka 插桩 {#kafka-instrumentation} + +为 Kafka 客户端插桩提供自动配置。 + +| 系统特性 | 类型 | 默认值 | 描述 | +| --------------------------------------------------------- | ------- | ------ | -------------------------- | +| `otel.instrumentation.kafka.experimental-span-attributes` | Boolean | false | 启用实验性跨度属性的捕获。 | + +## Micrometer 插桩 {#micrometer-instrumentation} + +为 Micrometer 到 OpenTelemetry 的桥接提供自动配置。 + +## MongoDB 插桩 {#mongodb-instrumentation} + +为 MongoDB 客户端插桩提供自动配置。 + +| 系统特性 | 类型 | 默认值 | 描述 | +| -------------------------------------------------------- | ------- | ------ | -------------------------- | +| `otel.instrumentation.mongo.statement-sanitizer.enabled` | Boolean | true | 启用数据库语句的清洗处理。 | + +## R2DBC 插桩 {#r2dbc-instrumentation} + +为 OpenTelemetry R2DBC 插桩提供自动配置。 + +| 系统特性 | 类型 | 默认值 | 描述 | +| -------------------------------------------------------- | ------- | ------ | -------------------------- | +| `otel.instrumentation.r2dbc.statement-sanitizer.enabled` | Boolean | true | 启用数据库语句的清洗处理。 | diff --git a/content/zh/docs/zero-code/java/spring-boot-starter/sdk-configuration.md b/content/zh/docs/zero-code/java/spring-boot-starter/sdk-configuration.md new file mode 100644 index 000000000000..49482c1ee4db --- /dev/null +++ b/content/zh/docs/zero-code/java/spring-boot-starter/sdk-configuration.md @@ -0,0 +1,257 @@ +--- +title: SDK 配置 +default_lang_commit: 1e69c8f94a605ce5624c6b6657080d98f633ac7b +weight: 30 +cSpell:ignore: customizer distro +--- + + + + +此 Spring 启动器支持[配置元数据](https://docs.spring.io/spring-boot/docs/current/reference/html/configuration-metadata.html)， +这意味着您可以在 IDE 中查看和自动完成所有可用属性。 + +## 通用配置 {#general-configuration} + +OpenTelemetry 启动器支持所有的 [SDK 自动配置](/docs/zero-code/java/agent/configuration/#sdk-configuration)（自 2.2.0 版本起）。 + +你可以在 `application.properties` 或 `application.yaml` 文件中通过属性来更新配置，也可以通过环境变量进行配置。 + +`application.properties` 示例： + +```properties +otel.propagators=tracecontext,b3 +otel.resource.attributes.deployment.environment=dev +otel.resource.attributes.service.name=cart +otel.resource.attributes.service.namespace=shop +``` + +`application.yaml` 示例： + +```yaml +otel: + propagators: + - tracecontext + - b3 + resource: + attributes: + deployment.environment: dev + service: + name: cart + namespace: shop +``` + +环境变量示例： + +```shell +export OTEL_PROPAGATORS="tracecontext,b3" +export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=dev,service.name=cart,service.namespace=shop" +``` + +## 覆盖资源属性 {#overriding-resource-attributes} + +如同在 Spring Boot 中一样，您可以使用环境变量覆盖 `application.properties` 和 `application.yaml` 文件中的属性。 + +例如，您可以通过设置标准的 `OTEL_RESOURCE_ATTRIBUTES` 环境变量来配置或覆盖 `deployment.environment` 资源属性。 + +```shell +export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=prod" +``` + +或者，你可以使用 `OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_ENVIRONMENT` 这个环境变量， +来设置或覆盖单个资源属性： + +```shell +export OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_ENVIRONMENT="prod" +``` + +第二个选项支持 [SpEL](https://docs.spring.io/spring-framework/docs/3.2.x/spring-framework-reference/html/expressions.html) 表达式。 + +请注意，`DEPLOYMENT_ENVIRONMENT` 会被 Spring Boot 的[宽松绑定](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.external-config.typesafe-configuration-properties.relaxed-binding.environment-variables)转换为 `deployment.environment`。 + +## 禁用 OpenTelemetry 启动器 {#disable-the-opentelemetry-starter} + +{{% config_option name="otel.sdk.disabled" %}} + +将值设置为 `true` 以禁用启动器，例如用于测试目的。 + +{{% /config_option %}} + +## 编程式配置 {#programmatic-configuration} + +你可以使用 `AutoConfigurationCustomizerProvider` 进行编程式配置。 +对于无法通过配置属性实现的高级用例，建议使用编程方式进行配置。 + +### 从追踪中排除 Actuator 端点 {#exclude-actuator-endpoints-from-tracing} + +例如，你可以自定义采样器，将健康检查端点从追踪中排除： + +{{< tabpane text=true >}} {{% tab header="Maven (`pom.xml`)" lang=Maven %}} + +```xml + + + io.opentelemetry.contrib + opentelemetry-samplers + 1.33.0-alpha + + +``` + +{{% /tab %}} {{% tab header="Gradle (`build.gradle`)" lang=Gradle %}} + +```kotlin +dependencies { + implementation("io.opentelemetry.contrib:opentelemetry-samplers:1.33.0-alpha") +} +``` + +{{% /tab %}} {{< /tabpane>}} + + + +```java +package otel; + +import io.opentelemetry.api.trace.SpanKind; +import io.opentelemetry.contrib.sampler.RuleBasedRoutingSampler; +import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider; +import io.opentelemetry.semconv.UrlAttributes; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + +@Configuration +public class FilterPaths { + + @Bean + public AutoConfigurationCustomizerProvider otelCustomizer() { + return p -> + p.addSamplerCustomizer( + (fallback, config) -> + RuleBasedRoutingSampler.builder(SpanKind.SERVER, fallback) + .drop(UrlAttributes.URL_PATH, "^/actuator") + .build()); + } +} +``` + + +### 编程式配置导出器 {#configure-the-exporter-programmatically} + +你还可以通过编程方式配置 OTLP 导出器。 +此配置替换了默认的 OTLP 导出器，并向请求添加了自定义标头。 + + + +```java +package otel; + +import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter; +import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider; +import java.util.Collections; +import java.util.Map; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + +@Configuration +public class CustomAuth { + @Bean + public AutoConfigurationCustomizerProvider otelCustomizer() { + return p -> + p.addSpanExporterCustomizer( + (exporter, config) -> { + if (exporter instanceof OtlpHttpSpanExporter) { + return ((OtlpHttpSpanExporter) exporter) + .toBuilder().setHeaders(this::headers).build(); + } + return exporter; + }); + } + + private Map headers() { + return Collections.singletonMap("Authorization", "Bearer " + refreshToken()); + } + + private String refreshToken() { + // 例如，从 kubernetes 密钥中读取令牌 + return "token"; + } +} +``` + + +## 资源提供器 {#resource-providers} + +OpenTelemetry 启动器包含与 Java 代理相同的资源提供器： + +- [通用资源提供器](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/resources/library) +- [默认禁用的资源提供器](/docs/zero-code/java/agent/configuration/#enable-resource-providers-that-are-disabled-by-default) + +此外，OpenTelemetry 启动器还包括以下特定于 Spring Boot 的资源提供器： + +### 分发资源启动器 {#distribution-resource-provider} + +FQN（完全限定名） : +`io.opentelemetry.instrumentation.spring.autoconfigure.resources.DistroVersionResourceProvider` + +| 属性 | 值 | +| -------------------------- | ----------------------------------- | +| `telemetry.distro.name` | `opentelemetry-spring-boot-starter` | +| `telemetry.distro.version` | 启动器版本 | + +### Spring 资源启动器 {#spring-resource-provider} + +FQN（完全限定名）: +`io.opentelemetry.instrumentation.spring.autoconfigure.resources.SpringResourceProvider` + +| 属性 | 值 | +| ----------------- | -------------------------------------------------------------------------------------------------------- | +| `service.name` | `spring.application.name` 或 `build.name` 来自 `build-info.properties` (请参阅[服务名称](#service-name)) | +| `service.version` | `build.version` 来自 `build-info.properties` | + +## 服务名称 {#service-name} + +使用这些资源提供器，服务名称由以下优先级规则确定， +符合 OpenTelemetry 的[规范](/docs/languages/sdk-configuration/general/#otel_service_name)： + +1. `otel.service.name` Spring 属性或 `OTEL_SERVICE_NAME` 环境变量（优先级最高） +2. `service.name` 可配置于 `otel.resource.attributes` 系统属性、Spring 属性或 `OTEL_RESOURCE_ATTRIBUTES` 环境变量 +3. `spring.application.name` Spring 属性 +4. `build-info.properties` +5. 来自 META-INF、MANIFEST.MF 的 `Implementation-Title` +6. 默认值为 `unknown_service:java`（优先级最低） + +在你的 pom.xml 文件中使用以下代码段来生成 `build-info.properties` 文件： + +{{< tabpane text=true >}} {{% tab header="Maven (`pom.xml`)" lang=Maven %}} + +```xml + + ${project.artifactId} + + + org.springframework.boot + spring-boot-maven-plugin + + + + build-info + repackage + + + + + + +``` + +{{% /tab %}} {{% tab header="Gradle (`build.gradle`)" lang=Gradle %}} + +```kotlin +springBoot { + buildInfo { + } +} +``` + +{{% /tab %}} {{< /tabpane>}}