[zh] Update and add content/zh/docs/zero-code/java/*.md

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: 1932c5d9a52ee2484f7a1c170acc8391d98192da
 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.55.0
 ---
 
 Java 中零代码插桩的常见选项包括 Java 代理 JAR、Spring Boot 启动器和 Quarkus OpenTelemetry 扩展。

content/zh/docs/zero-code/java/agent/declarative-configuration.md

@@ -0,0 +1,166 @@
+---
+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

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
 ---

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}
 
 代理高度可配置。

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 %}}