ambrosiaaaaa/apm-python

apm-python Docker镜像文档

1. 镜像概述

apm-python是针对Python应用设计的应用性能监控(APM)工具镜像，集成了性能数据采集、分析及可视化能力。该镜像基于轻量级架构，可快速接入各类Python应用（包括Web应用、微服务、后台任务等），通过实时收集关键性能指标、追踪请求链路及捕获错误信息，帮助开发团队全面掌握应用运行状态，精准定位性能瓶颈。

2. 核心功能与特性

2.1 性能指标收集

• 实时采集Python应用关键指标：响应时间（平均/最大/最小）、请求吞吐量、CPU/内存使用率、GC频率及耗时
• 支持自定义指标扩展，可通过API上报业务相关性能数据

2.2 分布式追踪

• 基于OpenTelemetry规范实现分布式追踪，支持跨服务请求链路追踪
• 自动生成调用链路拓扑图，展示服务间依赖关系及调用耗时
• 支持追踪上下文传递，适配HTTP、RPC、消息队列等多种通信场景

2.3 错误监控

• 实时捕获Python应用异常及错误堆栈信息
• 支持错误分级（警告/错误/严重）及自定义告警规则
• 提供错误发生频率统计及趋势分析

2.4 轻量级设计

• 低性能损耗（CPU占用<2%，内存占用<50MB）
• 支持按需启用功能模块，减少资源消耗
• 兼容Python 3.6+版本，无需修改应用源码即可接入

3. 使用场景

3.1 Python Web应用监控

适用于Django、Flask、FastAPI等Web框架构建的应用，监控接口响应性能、数据库查询耗时、缓存命中率等关键指标。

3.2 微服务性能分析

在Python微服务架构中，追踪跨服务调用链路，定位服务间通信瓶颈（如网络延迟、依赖服务响应慢等）。

3.3 开发/测试环境性能调试

在开发或测试阶段接入，实时监控代码变更对性能的影响，提前发现潜在性能问题。

3.4 生产环境性能监控

在生产环境持续运行，通过告警机制及时发现性能异常，结合历史数据进行趋势分析及容量规划。

4. 使用方法

4.1 基本运行命令

bash
docker run -d \
  --name apm-python \
  --network=host \  # 如需监控主机网络中的Python应用，使用host网络模式
  -e APP_NAME="my-python-app" \  # 应用名称（用于标识监控目标）
  -e APM_SERVER="http://apm-collector:8200" \  # APM数据收集服务器地址
  -e SAMPLING_RATE=1.0 \  # 追踪采样率（0.0-1.0，1.0为全量采样）
  -v /path/to/python/app:/app \  # 挂载Python应用目录（可选，用于源码级分析）
  apm-python:latest

4.2 与Python应用集成

1. 在Python应用中安装apm-python客户端依赖：

   bash
   pip install apm-python-agent
   

2. 在应用入口文件添加初始化代码：

   python
   from docker.xuanyuan.run/apm_python_agent import init_agent
   init_agent(
       app_name="my-python-app",  # 需与容器环境变量APP_NAME一致
       server_url="http://apm-collector:8200"  # 需与容器环境变量APM_SERVER一致
   )
   

5. 配置参数说明

5.1 环境变量配置

5.2 自定义配置文件

如需更复杂配置（如自定义指标、告警规则等），可通过挂载配置文件实现：

bash
docker run -d \
  --name apm-python \
  -v /path/to/custom-config.yaml:/etc/apm-python/config.yaml \  # 挂载自定义配置文件
  apm-python:latest

配置文件示例（config.yaml）：

yaml
agent:
  app_name: "my-python-app"
  server_url: "http://apm-collector:8200"
  sampling_rate: 0.5
metrics:
  enabled: true
  include: ["http.request.duration", "db.query.duration"]  # 仅采集指定指标
tracing:
  enabled: true
  exclude_paths: ["/health", "/metrics"]  # 排除指定路径追踪
alert:
  thresholds:
    http_request_duration: 500ms  # HTTP请求超时告警阈值

6. 部署示例（Docker Compose）

以下是apm-python与Python Web应用（FastAPI）及APM收集服务器的docker-compose部署示例：

yaml
version: '3.8'

services:
  apm-collector:  # APM数据收集服务器（可使用Elastic APM Server、Jaeger等）
    image: docker.xuanyuan.run/elastic/apm-server:8.10.4
    ports:
      - "8200:8200"
    environment:
      - output.elasticsearch.hosts=["elasticsearch:9200"]
    depends_on:
      - elasticsearch

  elasticsearch:  # 用于存储APM数据（可选，根据APM服务器配置调整）
    image: docker.xuanyuan.run/elasticsearch:8.10.4
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
    ports:
      - "9200:9200"

  my-python-app:  # 目标Python应用
    build: ./my-python-app
    ports:
      - "8000:8000"
    environment:
      - APM_AGENT_URL=http://apm-python:8201  # apm-python代理地址
    depends_on:
      - apm-python

  apm-python:  # apm-python监控代理
    image: docker.xuanyuan.run/apm-python:latest
    environment:
      - APP_NAME=my-python-app
      - APM_SERVER=http://apm-collector:8200
      - SAMPLING_RATE=0.5
    ports:
      - "8201:8201"  # 提供给Python应用的代理接口

7. 注意事项

• 确保apm-python容器与目标Python应用网络互通，以便正常采集数据
• 生产环境建议调整SAMPLING_RATE（如0.1-0.5）以减少数据量，测试环境可设为1.0全量采样
• 对于高并发Python应用，建议通过REPORT_INTERVAL调整上报间隔（如5-20秒），平衡实时性与性能消耗