SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场observability-onboarding

observability-onboarding

部署与运维

查看项目

更新于 10-13 21:32

技能介绍

用途

Observability Onboarding 用于把应用程序接入 Elastic Observability，埋点方式采用 Elastic Distribution of OpenTelemetry（EDOT）。它解决的核心问题是：仅完成配置不等于可观测，应用可能配置正确却不发出任何数据，因此该技能以「证明遥测真的到达」为终点，通过查询 Elasticsearch 中该服务的数据来确认，而不是凭配置差异宣告成功。

适用范围是应用侧埋点（EDOT SDK）。部署 EDOT Collector、从文件或基础设施采集日志、通过 Elastic Agent、Fleet 或集成包接入数据属于其他 ingest 路径，不在本技能范围内。

遥测开始流动后，可以继续使用 observability-sre-triage 评估服务健康、observability-k8s-investigation 排查 Kubernetes 层故障、observability-service-reliability 基于新信号定义 SLO 与告警、observability-llm-obs 处理 GenAI 与智能体工作负载。

主要能力

  • 判断服务需要全新埋点，还是从经典 Elastic APM agent 迁移到 EDOT。
  • 按服务的语言与运行时应用对应 EDOT 配置。
  • 将遥测指向正确的 OTLP 目的地，并拒绝 APM Server URL。
  • 验证 traces、metrics、logs 是否以预期的 service.name 落入 Elasticsearch。
  • 诊断已埋点服务完全不上报，或由错误 agent 上报的问题。

使用方式

技能通过 elastic CLI 执行 Elasticsearch 操作。若未安装 elastic CLI，需告知用户其用途，不得猜测凭据、直接调用 HTTP API 或尝试其他变通方式。文档中出现的 HTTP 简写（如 GET /、GET /_cat/indices、GET /{index}/_mapping、GET /{index}/_settings/index.mode、POST /_query）在操作表中映射到等价的 elastic CLI 命令，应始终使用 CLI，而不是直接调用 HTTP API。

流程大致如下：

  1. 路由请求：读取项目依赖清单（pom.xml 或 build.gradle、requirements.txt 或 pyproject.toml、*.csproj、composer.json）识别语言与运行时，并记录进程启动方式（Dockerfile ENTRYPOINT、Kubernetes pod spec、systemd unit），因为 agent 挂载点和环境变量都设置在这里。Java 使用 -javaagent: 标志或 JAVA_TOOL_OPTIONS；Python 使用 opentelemetry-instrument 入口包装器；.NET 在启动时调用 builder.AddElasticOpenTelemetry()；PHP 通过 OS 包安装原生扩展后完整重启进程。
  2. 检测经典 Elastic APM agent：常见标记是 ELASTIC_APM_* 环境变量和对应语言的 Elastic APM 包。找到任一标记即走迁移路径，不要在 EDOT 之上叠加。
  3. 确定遥测目的地：OTEL_EXPORTER_OTLP_ENDPOINT 可填部署或 Serverless 项目的 Elastic 托管 OTLP 端点，或用户已有的 EDOT Collector（需要在数据抵达 Elastic 前做富化、采样或分发）。绝不能填 APM Server URL——若候选值包含 apm-server、以端口 8200 结尾或带有 /intake/v2/events 路径，即为经典 ingest 端点，EDOT 无法使用。迁移路径上最常见的错误就是把旧的 ELASTIC_APM_SERVER_URL 沿用过来。
  4. 应用共享配置：设置且只设置三个环境变量。OTEL_SERVICE_NAME 为服务名，会成为 Elasticsearch 中的 service.name；OTEL_EXPORTER_OTLP_ENDPOINT 为第 3 步解析出的地址；OTEL_EXPORTER_OTLP_HEADERS 为凭据，形如 Authorization=ApiKey <key> 或 Authorization=Bearer <token>。不要设置 OTEL_TRACES_EXPORTER、OTEL_METRICS_EXPORTER、OTEL_LOGS_EXPORTER，默认值已经正确，设置它们通常是「只有 traces 没有 metrics 或 logs」的原因。切勿在同一进程上同时运行经典 Elastic APM agent 和 EDOT，二者会重复埋点并产生不一致的 traces，移除与替换应在同一次变更中完成。
  5. 验证遥测抵达：每次埋点或迁移变更后都执行，也作为用户报告已埋点服务缺失数据时的入口。部署重启后先等待一两分钟再下结论。

验证与诊断

通过 POST /_query 执行 ES|QL 查询（CLI 命令为 elastic es esql query --format tsv --query '<esql>'）。

确认服务是否有文档落入：按设置的服务名过滤，统计 traces-、metrics-、logs-* 中各索引的文档数与最后出现时间。健康结果是 traces、metrics、logs 数据流都有行，且 last_seen 在一两分钟内。

如果没有任何返回，需要查明服务实际以什么名字上报。空结果在「完全没有遥测」和「遥测以其他名字抵达」之间含义不明，可能是 OTEL_SERVICE_NAME 拼写错误，或 SDK 默认的 unknown_service。去掉服务名过滤再看实际上报情况。若服务以意外的名字出现，修正 OTEL_SERVICE_NAME；若完全不出现，说明 exporter 没有到达目的地，回到第 3 步检查端点与凭据。

确认上报方是 EDOT 而非其他：查询 traces-* 中按 telemetry.sdk.language、telemetry.sdk.name、telemetry.distro.name、telemetry.distro.version 分组统计。当 EDOT SDK 上报时，telemetry.distro.name 为 elastic；若 distro 为 null 且 telemetry.sdk.name == "opentelemetry"，说明应用使用的是上游 OpenTelemetry SDK。同一服务出现两行——一个带 Elastic distro 一个不带，或两个不同的 telemetry.sdk.language——意味着挂了多个 agent，或旧部署仍在运行。

常见结果形态与最可能原因：

  • 服务无行且名字处处缺失：exporter 从未到达目的地，端点错误或凭据无效。
  • 服务以不同名字出现：OTEL_SERVICE_NAME 未设置或拼写错误，SDK 回退到默认值。
  • 只有 traces，没有 metrics 或 logs：设置了 OTEL_*_EXPORTER 变量覆盖了默认值。
  • 有行但 last_seen 陈旧：进程已退出，或部署被回滚。
  • 同一服务出现两个 distro 值：经典 agent 与 EDOT 同时挂载，或旧副本仍在运行。

若映射中缺少上述字段，先用 GET /<index>/_mapping（CLI：elastic es indices get-mapping --index '<index>'）确认可用字段，再下结论。

适用场景

  • 「为我的 Spring Boot 服务加上可观测性」：读 pom.xml 确认 Java，检查 co.elastic.apm 与 ELASTIC_APM_* 标记，没有则走埋点路径，在容器入口加 -javaagent 标志，针对托管 OTLP 端点设置三个环境变量，然后运行验证查询并报告哪些信号抵达。
  • 「我们正在从 Elastic APM agent 迁移到 EDOT，用的是 .NET」：走迁移路径。在同一次变更中移除 Elastic.Apm.* 包、AddAllElasticApm() 调用以及 appsettings.json 中的 ElasticApm 块，同时加入 Elastic.OpenTelemetry 与 builder.AddElasticOpenTelemetry()。配置要转换而不是照抄，尤其不要把 ELASTIC_APM_SERVER_URLS 当作 OTLP 端点。
  • 「我的 Python 应用做了埋点但 Elastic 里没有数据」：从验证流程而不是配置开始。若为空，运行第二步看服务是否以其他名字上报。若服务完全缺失，两个候选原因是入口未包装（缺少 opentelemetry-instrument）和端点仍指向 APM Server，先查入口，因为它更常见。
  • 「服务发送 traces 但没有 logs 或 metrics」：这是 OTEL_*_EXPORTER 的典型特征，确认后从部署中移除相应变量并重新验证。

限制与注意事项

  • 不覆盖 EDOT Collector 部署、文件或基础设施日志采集，以及 Elastic Agent、Fleet、集成包接入。
  • 编辑前应阅读对应语言的安装或迁移指南，各运行时的挂载机制差异较大，照搬其他语言的模式会产生错误配置。
  • 移除与替换必须在同一次变更中完成，过渡期双 agent 并存会产生比任一单独使用都更差的 traces。
  • 切勿把经典服务器 URL 沿用过来。
  • 只设置三个变量，额外的 OTEL_* 调优偶尔合理，但 exporter 相关变量应保持默认。
  • 空验证结果应视为未知，而不是某一组件的失败，先用第二步区分原因再给出修复建议。
  • 切勿将凭据放入技能输出或提交的文件，OTEL_EXPORTER_OTLP_HEADERS 应放在部署的 secret 机制中。
  • 各语言 EDOT 指南由 apm-agent-devs 团队整理。

操作对照

  • GET / → elastic es info
  • POST /_query → elastic es esql query --format tsv --query '<esql>'
  • GET /<index>/_mapping → elastic es indices get-mapping --index '<index>'