Java 自动埋点

Java 自动埋点使用 OpenTelemetry Java 智能体为 Java 应用程序提供全面的遥测数据采集。此插桩可自动从 Java 应用程序和常用框架中捕获 trace、metrics 和 logs，而无需修改代码。

Java 自动埋点的工作原理

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

HTTP servers 和 clients（Servlet、Spring MVC、JAX-RS 等）
Database clients（JDBC、Hibernate 等）
Messaging systems（JMS、Kafka、RabbitMQ 等）
RPC frameworks（gRPC 等）
Caching libraries（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 - 为智能体启用调试日志（默认值：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 智能体支持：

Java 8 及更高版本

故障排查

验证智能体注入

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

kubectl describe pod <pod-name>

在容器命令中查找 -javaagent 参数。

启用调试日志

启用调试日志以排查问题：

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

配置参考

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

Java Auto-instrumentation Documentation

#Java 自动埋点

#目录