在 Elastic Observability 中使用 OpAmp 对 EDOT SDK 进行集中配置

作者：来自 Elastic Christoph Heger

了解如何在 Elastic Observability 中，通过使用 OpAmp 在大规模环境下通过 EDOT Collector 集中配置 Elastic Distributions of OpenTelemetry（EDOT）SDK。

使用 Elastic Distribution of OpenTelemetry（EDOT）SDK 的大量服务时，管理配置变更可能既复杂又耗时。OpenTelemetry 提供了 Open Agent Management Protocol（OpAMP），Elastic 通过 EDOT Collector 利用该协议来管理这些 SDK。在 Elastic Observability 中，Elastic 的 APM Agent 已经具备这种集中管理功能。结合 OpAMP 后，你现在可以通过 Elastic Observability 集中管理所有使用 EDOT SDK 的服务，EDOT Collector 通过 OpAMP 协助处理这些配置变更。

本文将介绍如何使用 EDOT Gateway Collector 实现 EDOT SDK 的集中配置功能。你将学习如何配置 EDOT SDK 和 EDOT Gateway Collector 以启用集中配置，最后我们会讲解集中配置所支持的配置项。

基于 OpenTelemetry Open Agent Management Protocol 的集中配置

OpenTelemetry 项目提供了 OpAMP，用于远程管理大量数据采集 Agent 及其他功能。EDOT SDK 的集中管理利用 OpAMP 分发配置。它是一个客户端---服务器网络协议，其中 OpAMP 服务器是 EDOT Collector 的一部分，而 OpAMP 客户端是 EDOT SDK 的一部分。EDOT SDK 会定期轮询 OpAMP 服务器以获取配置更新。EDOT Collector 中的 OpAMP 服务器由 Elastic APM 集中配置扩展提供，该扩展从 Elasticsearch 中读取 EDOT SDK 的配置。这个扩展的技术名称是 apmconfigextension，需要在 EDOT Collector 的配置中启用才能生效。根据 OpAMP 规范，传输层可使用 WebSocket 或普通 HTTP 连接。EDOT SDK 通过 HTTP 连接从 EDOT Collector 拉取配置。

前提条件

EDOT SDK 的集中配置需要一个以 Gateway 模式运行的独立 EDOT Collector。其他采集器（如 OpenTelemetry contrib collector 或自定义构建的采集器）则需要包含 Elastic APM 集中配置扩展。

支持集中配置的 EDOT 版本

下表概述了支持集中配置功能的 EDOT SDK 和 EDOT Collector 版本。应用程序和服务必须使用下表中列出的 EDOT SDK 版本进行检测，才能拉取并应用集中配置更改。

EDOT	Version
Android	1.2.0+
iOS	1.4.0+
Java	1.5.0+
Node.js	1.2.0+
PHP	1.1.1+
Python	1.4.0+
Collector (Gateway mode)	8.19, 9.1+

对于 EDOT 的 Java、Node.js、PHP 和 Python，集中配置不会阻塞应用程序启动。应用程序会使用默认配置或由环境变量提供的配置启动。当成功拉取集中配置后，它将优先于本地配置生效。目前，EDOT .NET 尚不支持集中配置，但计划在未来加入支持。

此外，EDOT SDK 的集中配置暂时不支持在 Elastic Cloud Serverless 或 Elastic Cloud 托管的 OTLP Endpoint 上使用。

下表概述了支持 EDOT SDK 集中配置的 Elastic Stack 版本。

Elastic	Version
Self-managed	9.1.0+
Elastic Cloud Hosted	9.1.0+

检索 Elasticsearch 端点和 API 密钥

Elastic APM 集中配置扩展需要在配置中包含 Elasticsearch 端点，以便读取 EDOT SDK 的集中配置设置。该 Elasticsearch 端点与用于将遥测数据导出到 Elasticsearch 的 Elasticsearch exporter 所使用的端点相同。集中配置文档中详细描述了获取端点和 API 密钥的步骤。

启用 EDOT 的集中配置

要启用集中配置，EDOT Collector 需要在 extensions 部分中配置 apmconfigextension。这需要前面获取的 Elasticsearch 端点和 Elasticsearch API 密钥。同时，需要设置环境变量 ELASTIC_OTEL_OPAMP_ENDPOINT 以在 EDOT SDK 中启用集中配置。

下面说明了如何为 EDOT Gateway Collector 和 EDOT SDK 启用集中配置。

配置 EDOT Collector 以启用集中配置

在 EDOT Collector 中启用集中配置支持，需要将 Elastic APM 集中配置扩展（apmconfigextension）的配置添加到配置文件中。

为 apmconfigextension 与 Elasticsearch 端点的身份验证配置 bearertokenauth 认证器。该认证器为发往 Elasticsearch 端点的出站请求配置客户端类型的身份验证机制。apmconfigextension 充当客户端，而 Elasticsearch 端点充当服务器。apmconfig 部分配置 OpAMP 服务器端点，EDOT SDK 将连接该端点以获取配置。service 部分则激活 apmconfig 和 bearertokenauth 扩展。

以下代码片段展示了 EDOT Collector 的配置示例，其中包含 bearertoken 认证器和用于集中配置的 apmconfig 配置。

yaml 复制代码

`

1.  extensions:
2.    bearertokenauth:
3.      scheme: "APIKey"
4.      token: "<ENCODED_ELASTICSEARCH_APIKEY>"
5.    source:
6.       elasticsearch:
7.         endpoint: "<YOUR_ELASTICSEARCH_ENDPOINT>"
8.         auth:
9.           authenticator: bearertokenauth
10.    apmconfig:
11.      opamp:
12.        protocols:
13.          http:
14.            # Default is localhost:4320
15.            # To specify a custom endpoint, uncomment the following line
16.            # and set the endpoint to the custom endpoint
17.            # endpoint: "<CUSTOM_OPAMP_ENDPOINT>"
18.    service:
19.      extensions: [bearertokenauth, apmconfig]

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

下载 EDOT Collector，并在 otel.yml 配置文件中包含上面的配置片段以启用集中配置。otel.yml 配置文件示例可在 EDOT Collector 文档中找到，可参考直接将数据摄取至 Elasticsearch 的示例。

配置 EDOT SDK 以启用集中配置

要在 EDOT SDKs（Java、Node.js、PHP 和 Python） 中启用集中配置，需要将环境变量 ELASTIC_OTEL_OPAMP_ENDPOINT 设置为 EDOT Collector 的 OpAMP 服务器端点，并设置所需的资源属性。

启用 EDOT SDK 的集中配置

下面的代码片段展示了如何在 shell 中使用 export 命令设置 ELASTIC_OTEL_OPAMP_ENDPOINT 环境变量。

ini 复制代码

`export ELASTIC_OTEL_OPAMP_ENDPOINT="http://<your-opamp-end-point>:4320/v1/opamp"` AI写代码

必须将 <your-opamp-end-point> 设置为提供集中配置用的 OpAMP 服务器端点的 EDOT Gateway Collector 的地址或主机名。

如果你在移动端使用 EDOT SDKs ，相关文档会说明如何在 EDOT Android 和 EDOT iOS 中启用集中配置支持。

配置资源属性

集中配置要求设置 OpenTelemetry 的资源属性 service.name 和 deployment.environment.name 。其中 service.name 是必填项，deployment.environment.name 虽然是可选的，但强烈建议设置。如果未设置 deployment.environment.name，则无法创建适用于整个环境的配置。

设置环境变量 OTEL_RESOURCE_ATTRIBUTES ，其中包含 service.name 和 deployment.environment.name ，如下代码片段所示。键值对之间用逗号分隔，并作为值提供给 OTEL_RESOURCE_ATTRIBUTES 环境变量。

arduino 复制代码

`export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.` AI写代码

支持的配置设置

下表概述了截至本文撰写时，非移动端 EDOT SDK 的支持的集中配置设置。

非移动端 EDOT SDK

表格显示了 EDOT Java、Node.js、PHP 和 Python SDK 支持的集中配置设置。

设置	说明	Java	Node.js	PHP	Python	Kibana
logging_level	EDOT SDK 的日志级别	1.5.0+	1.2.0+	1.1.0+	1.4.0+	9.1.0+
deactivate_instrumentations	关闭选定的 instrumentation	1.5.0+	1.2.0+	-	-	9.1.0+
deactivate_all_instrumentations	关闭所有 instrumentation	1.5.0+	1.2.0+	-	-	9.1.0+
send_traces	控制是否发送 traces	1.5.0+	1.3.0+	-	-	9.1.0+
send_metrics	控制是否发送 metrics	1.5.0+	1.3.0+	-	-	9.1.0+
send_logs	控制是否发送 logs	1.5.0+	1.3.0+	-	-	9.1.0+
opamp_polling_interval	连续拉取集中配置的时间间隔	1.6.0+	-	-	-	9.2.0+（计划中）
sampling_rate	head-based trace 的采样率	1.6.0+	-	-	1.7.0+	9.2.0+（计划中）
infer_spans	激活/关闭推断 spans	1.7.0+	-	-	-	9.2.0+（计划中）

移动 EDOT SDK

下表显示了 EDOT Android 和 iOS SDK 支持的中央配置设置。

设置	描述	Android	iOS	Kibana
recording	记录并发送遥测	1.2.0+	1.4.0+	9.1.0+
session_sample_rate	基于会话采样的采样率	1.2.0+	1.4.0+	9.1.0+

使用 Elastic Observability 更改 EDOT SDK 的配置设置

应用程序必须生成并发送遥测数据，否则 EDOT SDK 不会出现在 Elastic Observability 的 Agent 配置 UI 中。因为 Elastic Observability 中的 Agent 配置在接收到遥测数据之前，不知道 EDOT SDK 的存在。OpenTelemetry 资源属性 service.name 用作将配置分配给 EDOT SDK 的关键。目前，EDOT SDK 不会显示在 Agent Explorer 中。

进入 Kibana -> Observability -> Applications -> Service Inventory -> Settings -> Agent Configuration 创建你的 EDOT SDK 的新配置。

上述 EDOT Java SDK 配置通过将 deactivate_all_instrumentations 设置为 true 来禁用所有 instrumentation。这在需要关闭 instrumentation 的情况下非常有用。当需要更改 EDOT SDK 的采样率时，sampling_rate 设置就很有用。可以根据需求选择采样率，如下所示。

禁用中央配置

禁用中央配置很简单。移除环境变量 ELASTIC_OTEL_OPAMP_ENDPOINT 并重启应用，即可在 EDOT SDK 中禁用中央配置支持。移除 EDOT Collector 配置中 service 部分的 apmconfig 扩展并重启 Collector，即可在 EDOT Collector 中禁用 Elastic APM 中央配置扩展。

Elastic 对 OpenTelemetry 的贡献

Elastic 致力于 OpenTelemetry 项目。Elastic 向 OpenTelemetry 项目贡献了 Java OpAMP 客户端实现（Github PR），并正在进行 Python（Github PR）和 Node.js 的贡献。PHP 的 OpAMP 客户端将作为 Elastic 的更大贡献（Github issue）的一部分。

结论

在本文中，你学习了如何在 Elastic Observability 中通过 Gateway Collector 和 OpAMP 对 EDOT SDK 进行集中配置。你了解了如何在 Collector 中配置 apmconfigextension，以及如何设置 ELASTIC_OTEL_OPAMP_ENDPOINT 环境变量以启用 EDOT SDK 的中央配置，哪些 SDK 和 Collector 版本支持中央配置，以及当前支持的配置设置。现在，你可以在大规模部署中利用中央配置来管理 EDOT SDK 的配置。

原文：www.elastic.co/observabili...