90DaysOfDevOps Elastic Stack 实战：用 APM Server 扩展接入 APM Agent 并可视化应用性能追踪

• 文档/教程

本文基于 90DaysOfDevOps 仓库中 Elastic Stack 监控栈的 apm-server 扩展，系统讲解如何用 Docker Compose 为现有 ELK 栈叠加 APM Server 服务，将 APM Agent 采集到的应用性能追踪（traces）写入 Elasticsearch 并在 Kibana 的 APM 应用中完成可视化。读完本文，你将掌握 APM Server 扩展的启动方式、配置文件的关键参数、Python Flask Agent 的接入配置，以及 Kibana 中检查连通性与导入默认 APM 仪表盘的完整流程。

APM Server 在 Elastic Stack 中的角色

在 90DaysOfDevOps 的 Monitoring/Elastic Stack 目录中，主栈由 docker-compose.yaml 定义的setup、elasticsearch、logstash、kibana四个服务组成。而extensions/目录下的内容，正如其 README 所述，是"为 Elastic Stack 提供额外集成的第三方扩展"。

APM Server 就是其中之一。它的职责可以概括为一句话：

APM Server 从 APM Agents 接收数据，并将其转换为可在 Kibana 中可视化的 Elasticsearch 文档。

也就是说，APM Server 是整个 APM 数据链路中的"中转与加工站"：由运行在应用进程内的 APM Agent（如 Python、Java、Node.js 的 elasticapm SDK）采集分布式追踪数据，通过 HTTP 协议上报给 APM Server，APM Server 再将数据规整为 Elasticsearch 文档写入索引，最终由 Kibana 的APM应用以仪表盘形式呈现。

将 APM Server 扩展叠加到 Elastic Stack 栈中

APM Server 扩展的 Docker Compose 服务定义在 apm-server-compose.yml 中。启用它的方式与启用其他扩展（filebeat、metricbeat、curator 等）一致：从仓库根目录执行docker-compose，同时传入主栈与扩展两个 compose 文件：

$ docker-compose -f docker-compose.yml -f extensions/apm-server/apm-server-compose.yml up

这里docker-compose.yml是仓库根目录下 90DaysOfDevOps 的总编排入口，extensions/apm-server/apm-server-compose.yml是相对仓库根目录的扩展路径（原文档中写作apm-server-compose.yml的局部相对路径，实际在 2022/tr/Days/Monitoring/Elastic Stack/extensions/apm-server/ 目录下）。Compose 会将两个文件中的服务定义合并：主栈的elasticsearch、kibana等照常启动，同时追加apm-server服务。

启动完成后，可以打开 Kibana 中的APM应用，按其中的引导步骤开始接入。

深入 apm-server 扩展的 Compose 服务定义

apm-server服务的完整定义如下（apm-server-compose.yml）：

version: '3.7' services: apm-server: build: context: extensions/apm-server/ args: ELASTIC_VERSION: ${ELASTIC_VERSION} command: # Disable strict permission checking on 'apm-server.yml' configuration file - --strict.perms=false volumes: - ./extensions/apm-server/config/apm-server.yml:/usr/share/apm-server/apm-server.yml:ro,Z ports: - '8200:8200' environment: ELASTIC_PASSWORD: ${ELASTIC_PASSWORD:-} networks: - elk depends_on: - elasticsearch

关键点逐项说明：

• 镜像构建：build.context指向extensions/apm-server/目录，并通过ELASTIC_VERSION构建参数注入版本号。对应的 Dockerfile 只有两行：FROM docker.elastic.co/apm/apm-server:${ELASTIC_VERSION}，即直接基于官方 APM Server 镜像。ELASTIC_VERSION的值来自仓库根目录的 .env 文件，其中ELASTIC_VERSION=8.1.0，这意味着本仓库默认采用 Elastic Stack 8.1.0 版本构建整套栈。
• 启动参数：--strict.perms=false用于关闭对apm-server.yml配置文件的严格权限校验。当配置文件通过卷挂载进容器、权限位与官方镜像内默认值不一致时（例如以只读方式挂载:ro），该参数可避免因权限检查失败导致的服务启动报错，这是容器化部署 APM Server 的常见做法。
• 卷挂载：将本地的extensions/apm-server/config/apm-server.yml只读挂载到容器内/usr/share/apm-server/apm-server.yml，实现配置外置化；Z标志用于 SELinux 环境下自动设置正确的标签。
• 端口映射：8200:8200将 APM Server 默认监听端口暴露到宿主机，APM Agent 通过该端口上报数据。
• 环境变量：ELASTIC_PASSWORD读取.env中ELASTIC_PASSWORD的值（默认'90DaysOfDevOps'），用于向 Elasticsearch 认证。.env中还定义了ELASTIC_PASSWORD（内置超级用户elastic）、LOGSTASH_INTERNAL_PASSWORD（Logstash 专用）与KIBANA_SYSTEM_PASSWORD（Kibana 系统用户）三组口令，可见本栈启用了 X-Pack 安全特性（见 elasticsearch.yml 中xpack.security.enabled: true）。
• 网络与依赖：服务加入elk桥接网络，与主栈的elasticsearch处于同一网络，因此配置文件中可以直接使用服务名elasticsearch作为主机名访问；depends_on: elasticsearch保证 APM Server 在 Elasticsearch 就绪后才启动。

APM Server 配置文件解析

APM Server 的运行时行为由 apm-server.yml 控制，内容如下：

apm-server: host: 0.0.0.0:8200 output: elasticsearch: hosts: ['http://elasticsearch:9200'] username: elastic password: ${ELASTIC_PASSWORD}

• apm-server.host: 0.0.0.0:8200：监听所有网络接口的 8200 端口，与 Compose 中的端口映射一致。默认情况下 APM Server 即监听localhost:8200，此处显式绑定0.0.0.0是为了让容器内外的 Agent 都能访问。
• output.elasticsearch：定义数据输出目标——写入http://elasticsearch:9200（同一elk网络内的服务名解析），并使用elastic用户与${ELASTIC_PASSWORD}环境变量完成认证。ELASTIC_PASSWORD由 Compose 服务定义中的environment注入，因此配置文件里直接引用该变量即可。

从源码结构看，这套配置与主栈中其他 Beats 系列扩展（如 metricbeat.yml）保持一致的约定：以output.elasticsearch为输出端、以elastic+ELASTIC_PASSWORD为凭证、以服务名elasticsearch作为主机名，便于在多服务 Compose 网络中统一管理。

连接一个 APM Agent：Python Flask 示例

要让应用产生 APM 数据，需要在应用进程中运行一个 APM Agent。文档给出的最小配置只需指定SERVICE_NAME与SERVER_URL两项。以 Python Flask 应用为例：

import elasticapm from elasticapm.contrib.flask import ElasticAPM from flask import Flask app = Flask(__name__) app.config['ELASTIC_APM'] = { # Set required service name. Allowed characters: # a-z, A-Z, 0-9, -, _, and space 'SERVICE_NAME': 'PYTHON_FLASK_TEST_APP', # Set custom APM Server URL (default: http://localhost:8200) 'SERVER_URL': 'http://apm-server:8200', 'DEBUG': True, }

参数要点：

• SERVICE_NAME：服务唯一标识，将出现在 Kibana APM 的服务列表中。允许的字符为a-z、A-Z、0-9、-、_和空格，命名需遵守该约束。
• SERVER_URL：APM Server 地址，默认值是http://localhost:8200。在 Docker Compose 场景下，Agent 若运行在容器内，应使用服务名http://apm-server:8200（与 Compose 网络内服务名对应）；若 Agent 运行在宿主机上，则使用映射端口http://localhost:8200。
• DEBUG: True：开启调试输出，便于排障，生产环境可关闭。

不同语言（Java、Node.js、Ruby 等）的 Agent 配置项略有差异，但SERVICE_NAME与SERVER_URL这两项核心参数在所有官方 APM Agent 中都是通用的；各语言完整的配置项说明可在 Elastic 官方 APM 文档的 APM Agents 章节中查阅。

在 Kibana 中检查连通性并导入默认 APM 仪表盘

数据接入后，按以下步骤在 Kibana 中完成连通性检查与仪表盘初始化：

1. 在 Kibana 首页的Observability面板下点击Add APM；
2. 点击Check APM Server status，确认 APM Server 已启动并运行；
3. 点击Check agent status，验证你的 Agent 已正确注册并能成功上报；
4. 点击Load Kibana objects，为 APM 创建索引模式（index pattern），即导入 Kibana 默认的 APM 仪表盘对象；
5. 点击Launch APM，进入 APM 仪表盘查看服务、事务与追踪数据。

第 2、3 步是典型的两端连通性验证：前者验证 APM Server 到 Elasticsearch 的写入链路，后者验证 Agent 到 APM Server 的上报链路。第 4 步则保证 Kibana 具备可查询 APM 索引的映射视图。

与 Elastic Stack 其他扩展的协同

在 90DaysOfDevOps 的 extensions 目录下，除 apm-server 外还提供了 filebeat、metricbeat、logspout、curator、enterprise-search 等扩展，它们共享同一种使用模式：docker-compose -f docker-compose.yml -f extensions/<name>/<name>-compose.yml up。APM Server 聚焦应用性能追踪数据，metricbeat 采集系统与容器指标，filebeat 负责日志收集——三者可以同时叠加，构成"指标 + 日志 + 追踪"三件套的可观测性闭环，数据统一汇入同一套 Elasticsearch 集群，并在 Kibana 中分别呈现。

小结

APM Server 扩展让这套 Elastic Stack 从"日志/指标监控"进一步延伸到了"应用性能监控"：通过一条docker-compose -f docker-compose.yml -f extensions/apm-server/apm-server-compose.yml up命令即可在栈中叠加 APM 能力；配合apm-server.yml的监听与输出配置、.env中的版本与口令，以及 Agent 侧SERVICE_NAME+SERVER_URL的最小接入，即可在 Kibana 的 APM 应用中查看应用追踪数据。相关实现细节可进一步查阅 apm-server-compose.yml、apm-server.yml 与 Dockerfile，以及 Elastic 官方文档中"Running APM Server on Docker"一节了解容器化运行 APM Server 的更多细节。

• 文档/教程