observability-onboarding

可观测性接入

使用 Elastic Distribution of OpenTelemetry（EDOT）为应用添加埋点，并验证遥测数据已送达。埋点变更只完成了一半：即使应用配置完全正确，也可能仍然没有发出任何数据。因此，本技能最后会查询 Elasticsearch 中该服务的数据，而不是根据配置差异就宣告成功。

本技能的范围是使用 EDOT SDK 为应用添加埋点。部署 EDOT Collector、从文件或基础设施采集日志，以及通过 Elastic Agent、Fleet 或集成包接入数据，都属于单独的数据接入路径，不在本技能涵盖范围内。

遥测数据开始流动后，使用 observability-sre-triage 技能评估服务健康状况，使用 observability-k8s-investigation 调查 Kubernetes 层故障，使用 observability-service-reliability 基于新信号定义 SLO 和告警，并使用 observability-llm-obs 处理 GenAI 和 Agentic 工作负载。

环境配置

本技能通过 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。

无法访问集群时的分析

上述 CLI 检查限制的是_查询集群_，而不是分析。如果用户已在问题中提供证据（指标值、计数、状态原因、日志行、告警负载、配置），请基于这些证据推理并给出结论。

如果确实需要用户尚未提供的数据，请说明要检查什么以及如何检查——指出能够确定问题的具体查询、索引和字段，然后请求用户配置 CLI。即使没有集群访问权限，明确指出检查项的回答仍然有用；只要求用户配置 CLI 则不然。

本技能中只有验证步骤会与 Elasticsearch 通信；该步骤通过 POST /_query 执行。其他所有操作都只会修改用户工作区中的应用代码和配置。

待完成事项

• 判断服务是否需要新增埋点，或从经典版 Elastic APM Agent 迁移
• 应用适用于该服务语言和运行时的 EDOT 配置
• 将遥测数据指向正确的 OTLP 目标地址，并拒绝使用 APM Server URL
• 验证 traces、metrics 和 logs 是否以预期的 service.name 写入 Elasticsearch
• 诊断已添加埋点但未报告任何数据，或使用了错误 Agent 的服务

输出规范

适用于使用本技能生成的每条回复。

• 直接修改。 已知语言、当前 Agent 和目标地址时，直接应用变更。不要描述计划后逐个文件请求批准；只有在确实无法推断某项决策时才询问。
• 不要倾倒文档内容。 链接相关页面，并说明适用于该服务的两三条规则。在回复中粘贴整份设置指南属于缺陷。
• 报告成功前先验证。 “配置正确”不是结论，“遥测数据已送达”才是。如果验证没有返回任何行，请说明该服务未报告数据，并给出最可能的原因。
• 不要超出证据范围猜测。 验证查询结果为空只是一个事实，背后可能有多种原因——指出最可能的原因以及如何区分，而不要断言其中一种。
• 以结果收尾。 不要在末尾提出“要我接着设置仪表板吗？”之类的建议性问题。后续工作应列入建议清单，并以建议的方式表述。

流程：路由请求

1. 识别语言和运行时。 阅读项目的依赖清单——pom.xml 或 build.gradle、 requirements.txt 或 pyproject.toml、*.csproj、composer.json。据此决定打开哪份语言参考文档。 还要留意进程的启动方式（Dockerfile ENTRYPOINT、Kubernetes Pod 规范或 systemd 单元），因为 Agent 会在此处接入，也必须在此处设置环境变量。

   运行时	参考文档	EDOT 的接入方式
   Java	references/java.md	-javaagent: 标志或 JAVA_TOOL_OPTIONS
   Python	references/python.md	opentelemetry-instrument 入口包装器
   .NET	references/dotnet.md	启动代码中的 builder.AddElasticOpenTelemetry()
   PHP	references/php.md	通过 OS 软件包安装原生扩展，然后完整重启进程

   对于未列出的语言，遵循相同的模式——所需配置和后续验证步骤与语言无关——并使用上游 EDOT SDK 文档了解接入方式。

2. 检测经典 Elastic APM Agent。 据此决定采用插桩路径还是迁移路径。各语言参考文档会列出相关标记；常见标记包括 ELASTIC_APM_* 环境变量和特定语言的 Elastic APM 软件包。 如果存在任何标记，请采用迁移路径——不要在其上叠加 EDOT。

3. 确定遥测数据的目标位置。 据此决定将哪个 URL 填入 OTEL_EXPORTER_OTLP_ENDPOINT。有两个有效选项，另有一个常见错误选项：

   • 部署或 Serverless 项目的 Elastic 托管 OTLP 端点。这是正确的默认选项。
   • 用户已运行的 EDOT Collector，适用于遥测数据必须先经过丰富处理、采样或扇出，然后再发送到 Elastic 的情况。
   • 绝不能使用 APM Server URL。 如果候选 URL 包含 apm-server、以端口 8200 结尾，或包含 /intake/v2/events 路径，那么它就是经典摄取端点，EDOT 无法使用。在迁移路径中，这是最常见的错误——不得沿用旧的 ELASTIC_APM_SERVER_URL 值。

4. 先应用以下共享配置，再参考语言文档。 共享规则适用于所有运行时；参考文档仅说明语言特有的内容。

5. 验证。 不要仅凭配置就报告成功——请运行验证流程。

必需配置

所有 EDOT SDK 的配置都相同。恰好设置以下三个环境变量：

变量	值
OTEL_SERVICE_NAME	服务名称。此值会成为 Elasticsearch 中的 service.name，也是其他所有 Observability 技能查找该服务的依据。
OTEL_EXPORTER_OTLP_ENDPOINT	第 3 步中解析出的托管 OTLP 端点或 EDOT Collector URL。
OTEL_EXPORTER_OTLP_HEADERS	凭据，格式为 Authorization=ApiKey <key> 或 Authorization=Bearer <token>。

适用于所有语言的两条规则：

• 不要设置 OTEL_TRACES_EXPORTER、OTEL_METRICS_EXPORTER 或 OTEL_LOGS_EXPORTER。 默认值已经正确。 设置这些变量通常会导致服务报告了追踪信息，却没有指标或日志。
• 切勿在同一进程中同时运行经典 Elastic APM Agent 和 EDOT。 它们会重复插桩并产生不一致的追踪信息。移除和替换应在同一项变更中完成。

流程：验证遥测数据是否到达

每次修改插桩或迁移后都运行此流程；当用户报告已插桩的服务未显示时，也以此作为排查入口。部署重启后，先给流水线一两分钟时间，再得出结论。

1. 确认该服务的文档正在写入。 查询 POST /_query，按在 OTEL_SERVICE_NAME 中设置的服务名称进行筛选。判断标准：是否有数据到达，以及到达的是哪些信号。

   FROM traces-*,metrics-*,logs-* METADATA _index
   | WHERE @timestamp > NOW() - 15 minutes AND service.name == "<service>"
   | STATS docs = COUNT(*), last_seen = MAX(@timestamp) BY _index
   | SORT docs DESC
   | LIMIT 20
   

   正常结果应包含来自 traces 数据流、metrics 数据流和 logs 数据流的行，且 last_seen 时间在最近一两分钟内。信号缺失属于诊断线索，而非表面问题：通常只有 traces，没有 metrics 或 logs，意味着设置了 OTEL_*_EXPORTER 变量。

2. 如果没有返回任何结果，查明服务上报时使用的名称。 结果为空，既可能表示“完全没有遥测数据”，也可能表示“遥测数据使用了其他名称”——例如 OTEL_SERVICE_NAME 拼写错误，或 SDK 默认使用了 unknown_service。移除服务筛选条件，查看实际到达的数据。

   FROM traces-*,metrics-*,logs-*
   | WHERE @timestamp > NOW() - 15 minutes
   | STATS docs = COUNT(*), last_seen = MAX(@timestamp) BY service.name
   | SORT docs DESC
   | LIMIT 25
   

   判断标准：如果服务显示为意外名称，请修正 OTEL_SERVICE_NAME。如果完全没有显示，则说明导出器未能连接到目标位置——返回路由流程的第 3 步，重新检查端点和凭据。

3. 确认上报方是 EDOT，而非其他组件。 这能区分正确完成的迁移与尚未完成的迁移，也能区分原生 OpenTelemetry 与 EDOT。

   FROM traces-*
   | WHERE @timestamp > NOW() - 15 minutes AND service.name == "<service>"
   | STATS spans = COUNT(*) BY telemetry.sdk.language, telemetry.sdk.name, telemetry.distro.name, telemetry.distro.version
   | SORT spans DESC
   | LIMIT 10
   

   EDOT SDK 上报时，telemetry.distro.name 的值为 elastic。如果 distro 为 null，且 telemetry.sdk.name == "opentelemetry"，则说明应用使用的是上游 OpenTelemetry SDK，而非 EDOT。同一服务对应两行——一行包含 Elastic distro，另一行不包含，或者 telemetry.sdk.language 的值不同——表示连接了多个 Agent，或仍有旧部署在运行。

4. 根据结果的表现进行诊断。

   验证结果	最可能的原因
   服务没有任何行，且在任何位置都找不到该名称	导出器未能连接到目标位置——端点错误或凭据无效
   服务显示为其他名称	OTEL_SERVICE_NAME 未设置或拼写错误；SDK 回退到了默认值
   只有 traces，没有 metrics 或 logs	设置了 OTEL_*_EXPORTER 变量，并覆盖了默认设置
   存在行，但 last_seen 已过时	进程已退出，或部署已回滚
   同一服务存在两个 distro 值	Classic agent 和 EDOT 均已连接，或仍有旧副本在运行

   如果映射中没有上述字段，请先通过 GET /<index>/_mapping 确认有哪些字段，再判断遥测数据是否有误。

示例

“为我的 Spring Boot 服务添加可观测性” —— 读取 pom.xml 以确认 Java，检查是否存在 co.elastic.apm 和 ELASTIC_APM_* 标记；若没有，则按照 references/java.md 中的说明采用插桩路径。将 -javaagent 标志添加到容器入口点， 针对托管 OTLP 端点设置三个环境变量，然后运行验证查询并报告哪些信号已送达。

“我们要从 Elastic APM agent 迁移到 EDOT，我们使用的是 .NET” —— 这是迁移路径。在同一次更改中移除 Elastic.Apm.* 包、AddAllElasticApm() 调用和 appsettings.json 中的 ElasticApm 配置块，同时添加 Elastic.OpenTelemetry 和 builder.AddElasticOpenTelemetry()。应转换配置，而不是直接复制——尤其不要将 ELASTIC_APM_SERVER_URLS 作为 OTLP 端点重复使用。按照步骤 3 验证，并确认只有一个发行版在报告数据。

“我为 Python 应用添加了插桩，但 Elastic 中什么都没有显示” —— 从验证流程入手，而不是从配置入手。运行步骤 1；如果结果为空，则运行步骤 2，查看服务是否以其他名称报告。如果服务完全不存在，可能的原因有两个：未包装的入口点（缺少 opentelemetry-instrument）以及端点仍指向 APM Server。先检查入口点——这两种情况中它更常见。

“我们的服务会发送跟踪，但没有日志或指标” —— 这是 OTEL_*_EXPORTER 特征。运行步骤 1 以确认；它会显示跟踪数据流，但没有其他内容。然后从部署中移除 OTEL_TRACES_EXPORTER、OTEL_METRICS_EXPORTER 或 OTEL_LOGS_EXPORTER 变量，并重新验证。

指南

• 编辑前，先阅读该语言的设置或迁移指南。 各语言的参考文档会链接到权威页面；不同运行时的接入机制差异足够大，照搬其他语言的模式会导致配置错误。
• 移除和替换应在同一次更改中完成。 经典 Agent 和 EDOT 同时接入的时间窗口会产生双重插桩的跟踪，比单独使用任一方案都更糟。
• 切勿沿用经典服务器 URL。 ELASTIC_APM_SERVER_URL 指向 APM Server； OTEL_EXPORTER_OTLP_ENDPOINT 必须指向托管 OTLP 端点或 EDOT Collector。
• 只设置三个变量，不要设置更多。 有时确实需要额外的 OTEL_* 调优，但导出器变量应保持默认值。
• 将空的验证结果视为未知，而不是某个特定组件故障。 在建议修复方案前，先通过步骤 2 区分原因。
• 切勿在技能的输出或已提交的文件中放置凭据。 OTEL_EXPORTER_OTLP_HEADERS 应放在部署的密钥管理机制中。
• 归属：此处汇总的各语言 EDOT 指南源自 apm-agent-devs 团队。

操作

HTTP API（简写）	elastic CLI 命令
GET /	elastic es info
POST /_query	elastic es esql query --format tsv --query '<esql>'
GET /<index>/_mapping	elastic es indices get-mapping --index '<index>'