airbyte/java-datadog-tracer-base

DataDog Java Agent Docker镜像文档

1. 镜像概述和主要用途

DataDog Java Agent Docker镜像是用于为Java服务提供DataDog监控能力的专用镜像。该镜像封装了DataDog Java Agent（Java代理程序），通过Java Agent机制注入到Java应用进程中，实现对Java服务的性能监控、分布式追踪、错误检测及JVM指标收集，无需修改应用代码即可完成与DataDog平台的集成。

2. 核心功能和特性

2.1 核心功能

• 性能指标收集：实时采集Java应用及JVM关键指标（如响应时间、吞吐量、GC次数、内存使用等）。
• 分布式追踪：支持OpenTelemetry和Datadog APM协议，追踪跨服务调用链路。
• 错误与异常监控：捕获应用运行时异常、未处理异常及HTTP错误状态码。
• JVM深度监控：收集堆内存、非堆内存、线程数、类加载等JVM运行时指标。
• 框架自动集成：原生支持Spring Boot、Tomcat、Jetty、Struts等主流Java框架。

2.2 核心特性

• 低侵入性：通过Java Agent机制注入，无需修改应用代码或依赖。
• 轻量化设计：Agent本身资源占用低（CPU < 1%，内存 < 50MB），对应用性能影响极小。
• 动态配置：支持通过环境变量或配置文件实时调整监控参数。
• 全平台兼容：与DataDog SaaS平台无缝对接，支持指标可视化、告警及日志关联分析。

3. 使用场景和适用范围

3.1 适用场景

• 微服务架构中的Java服务监控（如Spring Cloud、Dubbo应用）。
• 需要追踪跨服务调用链路的分布式系统。
• 需优化JVM性能的高并发Java应用（如电商订单系统、支付系统）。
• 需满足SLA监控要求的核心业务应用（如***交易、政务服务系统）。

3.2 适用范围

• Java版本：Java 8、11、17及以上LTS版本。
• 应用类型：基于JVM的Java应用（包括Jar包、War包部署的应用）。
• 部署环境：Docker容器环境（单机Docker、Kubernetes集群）。
• 框架支持：Spring Boot 1.x/2.x/3.x、Tomcat 7+/8+/9+/10+、Jetty 9+/10+、Netty 4.x、Play Framework等。

4. 详细使用方法和配置说明

4.1 镜像拉取

从DataDog官方镜像仓库拉取最新版本：

bash
docker pull gcr.io/datadoghq/dd-java-agent:latest

国内用户可使用镜像加速（如datadog/dd-java-agent:latest，需确认镜像源可用性）。

4.2 基础使用方式（Docker Run）

通过docker run启动Java应用时，需将Agent JAR挂载到容器并通过-javaagent参数注入。

步骤1：挂载Agent JAR

将Agent镜像中的dd-java-agent.jar挂载到应用容器（以openjdk:11-jre-slim为例）：

bash
docker run -d \
  --name java-app-with-agent \
  # 挂载Agent JAR到应用容器的/opt/datadog目录
  -v $(docker run --rm gcr.io/datadoghq/dd-java-agent:latest cat /opt/datadog/dd-java-agent.jar > dd-java-agent.jar && pwd)/dd-java-agent.jar:/opt/datadog/dd-java-agent.jar \
  # 配置DataDog Agent环境变量
  -e DD_API_KEY=<YOUR_DATADOG_API_KEY> \  # 必选，DataDog平台API密钥
  -e DD_SITE=datadoghq.com \              # 可选，默认datadoghq.com（国内用户用datadoghq.cn）
  -e DD_SERVICE=my-java-service \         # 必选，服务名称（如order-service）
  -e DD_ENV=production \                  # 可选，环境名称（如prod/test）
  -e DD_VERSION=1.0.0 \                   # 可选，应用版本（如v1.2.3）
  # 启动应用并注入Agent
  openjdk:11-jre-slim \
  java -javaagent:/opt/datadog/dd-java-agent.jar -jar /app/my-app.jar

4.3 Docker Compose配置示例

创建docker-compose.yml，集成Agent到Java服务：

yaml
version: '3.8'
services:
  java-app:
    image: openjdk:11-jre-slim
    container_name: java-app
    volumes:
      # 挂载Agent JAR（需提前从Agent镜像复制到本地./agent目录）
      - ./agent/dd-java-agent.jar:/opt/datadog/dd-java-agent.jar
      # 挂载应用JAR包（本地应用路径）
      - ./app:/app
    environment:
      # DataDog基础配置
      - DD_API_KEY=<YOUR_DATADOG_API_KEY>
      - DD_SITE=datadoghq.com
      - DD_SERVICE=order-service
      - DD_ENV=production
      - DD_VERSION=2.1.0
      # 追踪配置
      - DD_TRACE_ENABLED=true
      - DD_TRACE_SAMPLE_RATE=1.0  # 采样率（1.0=100%）
      # JVM监控配置
      - DD_JVM_METRICS_ENABLED=true
    command: ["java", "-javaagent:/opt/datadog/dd-java-agent.jar", "-jar", "/app/order-service.jar"]

提前复制Agent JAR到本地：

bash
# 创建Agent目录
mkdir -p ./agent
# 从Agent镜像复制JAR到本地
docker run --rm -v $(pwd)/agent:/output gcr.io/datadoghq/dd-java-agent:latest cp /opt/datadog/dd-java-agent.jar /output/

4.4 高级配置方法

4.4.1 环境变量配置

Agent支持通过环境变量动态调整参数，常用配置如下表：

4.4.2 配置文件挂载

如需更复杂的配置（如自定义指标、采样规则），可通过挂载dd-java-agent.yaml配置文件实现：

1. 本地创建配置文件./agent-config/dd-java-agent.yaml：

yaml
# 自定义JVM指标收集间隔（秒）
jvm:
  metrics_collection_interval: 10

# 分布式追踪采样规则
trace:
  sampler:
    rules:
      - service: "payment-service"
        sample_rate: 0.5  # 支付服务采样率50%
      - service: "order-service"
        sample_rate: 1.0  # 订单服务采样率100%

# 自定义标签（全局附加到所有指标）
tags:
  - "team:backend"
  - "owner:dev@example.com"

2. 在docker-compose.yml中挂载配置文件：

yaml
services:
  java-app:
    # ... 其他配置 ...
    volumes:
      - ./agent/dd-java-agent.jar:/opt/datadog/dd-java-agent.jar
      - ./agent-config/dd-java-agent.yaml:/opt/datadog/dd-java-agent.yaml  # 挂载配置文件
    environment:
      # 指定配置文件路径
      - DD_CONFIG=/opt/datadog/dd-java-agent.yaml

5. 注意事项

1. API密钥安全：DD_API_KEY为敏感信息，建议通过Docker Secrets或Kubernetes Secrets管理，避免硬编码到配置文件。
2. Java版本兼容性：Agent版本需与Java版本匹配（如Java 17需Agent 0.100+版本），详见DataDog官方兼容性文档。
3. 资源限制：为Agent预留至少50MB内存（JVM参数-Xmx50m），避免因资源不足导致Agent崩溃。
4. 网络连通性：容器需能访问DataDog站点（agent-intake.<DD_SITE>端口443），若使用私有网络，需配置代理或允许出站流量。

6. 参考链接

• DataDog Java Agent官方文档
• DataDog API密钥获取
• Java Agent配置参数全表