ambrosiaaaaa/apm-java

apm-java 镜像文档

1. 镜像概述

apm-java是专为Java应用设计的性能监控(APM)工具Docker镜像，集成了APM代理、指标采集器及基础配置组件。通过在Java应用中注入轻量级代理，实现对应用性能数据的实时采集、分析与可视化，帮助开发和运维团队快速定位性能瓶颈、优化应用效率，无需复杂的手动配置。

2. 核心功能与特性

• 全面性能指标采集：覆盖应用层（响应时间、吞吐量、错误率）、JVM层（内存使用、GC状态、线程数）及系统层（CPU、网络I/O）关键指标；
• 分布式追踪：支持跨服务调用链追踪，记录请求路径及各节点耗时，定位分布式系统中的性能卡点；
• 轻量级设计：代理对应用性能影响极小（通常<1% overhead），支持动态配置更新；
• 多框架兼容：适配主流Java框架（Spring Boot、Tomcat、Jetty等）及JDK 8+环境；
• 数据集成能力：可将监控数据发送至APM服务器（如Elastic APM Server、Prometheus等），支持与日志系统联动分析。

3. 典型使用场景

• Java微服务监控：监控微服务架构中各Java服务实例的实时性能，追踪服务间调用依赖；
• 生产环境性能管理：实时监测生产环境应用健康状态，通过告警机制提前发现性能异常；
• 开发/测试环境调优：辅助性能测试，量化优化效果（如代码重构、配置调整后的性能变化）；
• 分布式问题诊断：通过调用链数据定位跨服务请求的延迟节点或错误根源。

4. 使用方法与部署示例

4.1 基础部署（Docker Run）

bash
docker run -d \
  --name apm-java-agent \
  -e APM_SERVER_URL="http://apm-server:8200" \  # APM服务器地址（必填）
  -e SERVICE_NAME="order-service" \             # 被监控应用名称（必填）
  -e ENVIRONMENT="production" \                 # 环境标识（如production/test）
  -e JVM_ARGS="-Xms512m -Xmx1g" \               # 代理进程JVM参数（可选）
  -v /var/log/java-app:/var/log/app \           # 挂载应用日志目录（可选）
  apm-java:latest

4.2 Docker Compose 集成示例

yaml
version: '3'
services:
  apm-java-agent:
    image: docker.xuanyuan.run/apm-java:latest
    container_name: apm-java-agent
    environment:
      - APM_SERVER_URL=http://apm-server:8200
      - SERVICE_NAME=payment-service
      - ENVIRONMENT=production
      - SERVICE_VERSION=2.1.0  # 应用版本（用于版本对比）
      - LOG_LEVEL=debug        # 代理日志级别（默认info）
      - SAMPLING_RATE=0.8      # 追踪采样率（0.0-1.0）
    volumes:
      - ./app-logs:/var/log/app  # 挂载应用日志目录
    depends_on:
      - apm-server  # 依赖APM服务器（需单独部署）

5. 核心配置参数说明

6. 注意事项

• 部署前需确保APM服务器（如Elastic APM Server）已启动并可被容器访问；
• SERVICE_NAME建议唯一标识应用，避免不同应用数据混淆；
• 生产环境中建议通过LOG_LEVEL=warn降低日志输出量，减少资源占用；
• 多实例部署时，可通过INSTANCE_ID环境变量区分不同应用实例（默认自动生成）。