Java 自动插桩

Java 自动插桩使用 OpenTelemetry Java agent 为 Java 原生应用提供全面的遥测数据采集。此插桩无需修改代码，即可自动从 Java 原生应用和常用框架中捕获 traces、metrics 和 logs。

Java 自动插桩的工作原理

operator 会将 OpenTelemetry Java agent 作为 Java 智能体 JAR 文件注入到 Java 原生应用容器中。该智能体使用字节码插桩在运行时自动为 Java 类提供插桩，并从以下来源捕获遥测数据：

HTTP 服务器和客户端（Servlet、Spring MVC、JAX-RS 等）
数据库客户端（JDBC、Hibernate 等）
消息系统（JMS、Kafka、RabbitMQ 等）
RPC 框架（gRPC 等）
缓存库（Redis、Memcached 等）
以及许多其他流行的 Java 库和框架

启用 Java 插桩

要为 Java 原生应用启用自动插桩，请为你的 pod 或 namespace 添加注解：

apiVersion: v1
kind: Pod
metadata:
  name: java-app
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
spec:
  containers:
  - name: app
    image: myjavaapp:latest

operator 会自动注入 Java 智能体，并通过设置带有 -javaagent 标志的 JAVA_TOOL_OPTIONS 环境变量，配置 JVM 在启动时加载它。

Java 智能体环境变量

以下环境变量用于控制 Java 智能体的行为：

插桩控制

OTEL_JAVAAGENT_ENABLED - 启用或禁用 Java 智能体（默认值：true）
OTEL_JAVAAGENT_DEBUG - 为智能体启用 debug 日志（默认值：false）
OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED - 默认启用所有插桩（默认值：true）

特定插桩控制

你可以启用或禁用特定插桩：

OTEL_INSTRUMENTATION_JDBC_ENABLED - JDBC 插桩
OTEL_INSTRUMENTATION_SPRING_WEB_ENABLED - Spring Web 插桩
OTEL_INSTRUMENTATION_KAFKA_ENABLED - Kafka 插桩
OTEL_INSTRUMENTATION_REDIS_ENABLED - Redis 插桩

示例配置：

spec:
  java:
    env:
      - name: OTEL_INSTRUMENTATION_JDBC_ENABLED
        value: "true"
      - name: OTEL_INSTRUMENTATION_KAFKA_ENABLED
        value: "true"
      - name: OTEL_INSTRUMENTATION_REDIS_ENABLED
        value: "false"

扩展配置

配置额外的智能体扩展：

OTEL_JAVAAGENT_EXTENSIONS - 额外智能体扩展的路径
OTEL_JAVAAGENT_CONFIGURATION_FILE - 智能体配置文件的路径

高级配置

自定义智能体镜像

你可以指定自定义的 Java 智能体镜像：

spec:
  java:
    image: my-registry.com/custom-java-agent:my-tag

卷挂载

该智能体会挂载到应用容器中的 /otel-auto-instrumentation-java-<container-name>/ 路径。

按容器注入

对于多容器 pod，请指定要为哪些容器启用插桩：

metadata:
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
    instrumentation.opentelemetry.io/container-names: "app,worker"

支持的 Java 版本

OpenTelemetry Java agent 支持：

Java 8 及更高版本

故障排查

验证智能体注入

检查智能体是否已成功注入：

kubectl describe pod <pod-name>

查看容器命令中是否包含 -javaagent 参数。

启用 debug 日志

启用 debug 日志以排查问题：

spec:
  java:
    env:
      - name: OTEL_JAVAAGENT_DEBUG
        value: "true"
      - name: OTEL_LOG_LEVEL
        value: "debug"

常见问题

智能体未加载：验证 init container 是否已成功完成，以及共享卷中是否存在智能体 JAR。

缺少 traces：检查 exporter 端点是否正确，并且应用 pod 是否可以访问该端点。

内存使用过高：减少已启用的插桩数量，或调整 JVM 堆设置。

示例配置

Java 原生应用插桩的完整示例如下：

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: java-instrumentation
  namespace: java-development
spec:
  java:
    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.26.1
    env:
      - name: OTEL_JAVAAGENT_DEBUG
        value: "false"
  exporter:
    endpoint: http://otel-collector.observability.svc:4318
  env:
    - name: OTEL_RESOURCE_ATTRIBUTES
      value: deployment.environment.name=development
  sampler:
    type: parentbased_traceidratio
    argument: "1"
  propagators:
    - tracecontext
    - baggage
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: java-app
  namespace: java-development
spec:
  replicas: 1
  selector:
    matchLabels:
      app: java-app
  template:
    metadata:
      labels:
        app: java-app
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"
    spec:
      containers:
      - name: app
        image: myjavaapp:latest
        ports:
        - containerPort: 8080

operator 用于注入智能体的 Java 自动插桩镜像。v2 Operator 不会随附 Java 智能体镜像，因此你必须自行构建或提供一个镜像。请参阅插桩选项中的警告。
OTLP exporter 端点。请将此 URL 替换为你实际的 OpenTelemetry Collector 地址。
为此 pod 启用 Java 自动插桩注入。有关可接受值，请参阅注入注解支持的值。

配置参考

有关详细的配置选项、受支持的库以及高级使用场景，请参阅官方 OpenTelemetry Operator 文档：

Java 自动插桩文档

#Java 自动插桩

#目录