上游 OpenTelemetry 收集器和语言 SDK
Elastic Stack Serverless
在 Elastic Cloud Hosted 中，*APM Server* 接收来自 Elastic APM Agent 的数据，并将其转换为 Elasticsearch 文档。 在 Elastic Cloud Serverless 中，实际上没有 APM Server 运行，而是由*托管摄取服务*接收和转换数据。
这是您可以用来将 Elastic 与 OpenTelemetry 集成的几种方法之一。**要比较方法并为您的用例选择最佳方法，请参阅 OpenTelemetry。**
Elastic Stack 原生支持 OpenTelemetry 协议 (OTLP)。 这意味着可以直接将从您的应用程序和基础设施收集的跟踪数据和指标发送到 Elastic Stack。
- 从上游 OpenTelemetry 收集器向 Elastic 发送数据
- 从上游 OpenTelemetry 语言 SDK向 Elastic 发送数据
使用 OTLP 导出器将 OpenTelemetry 收集器实例连接到 Elastic Observability 或 Elastic Observability Serverless
receivers:
# ...
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
# ...
memory_limiter:
check_interval: 1s
limit_mib: 2000
batch:
exporters:
debug:
verbosity: detailed
otlp:
# Elastic APM server https endpoint without the "https://" prefix
endpoint: "${env:ELASTIC_APM_SERVER_ENDPOINT}" <5>
headers:
# Elastic APM Server secret token
Authorization: "Bearer ${env:ELASTIC_APM_SECRET_TOKEN}" <6>
service:
pipelines:
traces:
receivers: [otlp]
processors: [..., memory_limiter, batch]
exporters: [debug, otlp]
metrics:
receivers: [otlp]
processors: [..., memory_limiter, batch]
exporters: [debug, otlp]
logs:
receivers: [otlp]
processors: [..., memory_limiter, batch]
exporters: [debug, otlp]
- 接收器，例如 OTLP 接收器（转发由 APM Agent 发出的数据）或 主机指标接收器。
- 我们建议使用 批处理处理器和 内存限制器处理器。 有关更多信息，请参见 推荐的处理器。
- 调试导出器有助于进行问题排查，并支持可配置的详细级别：
basic（默认）、normal和detailed。 - Elastic Observability 端点配置。 APM Server 通过 gRPC 传输的 OTLP 协议 (OTLP/gRPC) 和通过 HTTP 传输的 OTLP 协议 (OTLP/HTTP) 支持 ProtoBuf 有效负载。 要了解有关这些导出器的更多信息，请参阅 OpenTelemetry 收集器文档：OTLP/HTTP 导出器 或 OTLP/gRPC 导出器。 将端点添加到现有配置时，可以添加可选的名称组件，例如
otlp/elastic，以区分端点，如 OpenTelemetry 收集器配置基础知识中所述。 - APM Server 端点的主机名和端口。 例如，
elastic-apm-server:8200。 - Elastic APM 的凭据 密钥令牌授权 (
Authorization: "Bearer a_secret_token") 或 API 密钥授权 (Authorization: "ApiKey an_api_key")。 - 特定于环境的配置参数可以方便地作为环境变量传递，如 此处所述（例如，
ELASTIC_APM_SERVER_ENDPOINT和ELASTIC_APM_SECRET_TOKEN）。 - [预览] 要将 OpenTelemetry 日志发送到 Elastic Stack 8.0+ 版本，请声明一个
logs管道。
receivers:
# ...
otlp:
processors:
# ...
memory_limiter:
check_interval: 1s
limit_mib: 2000
batch:
exporters:
logging:
loglevel: warn
otlp/elastic:
# Elastic https endpoint without the "https://" prefix
endpoint: "${ELASTIC_APM_SERVER_ENDPOINT}" <5>
headers:
# Elastic API key
Authorization: "ApiKey ${ELASTIC_APM_API_KEY}" <6>
service:
pipelines:
traces:
receivers: [otlp]
processors: [..., memory_limiter, batch]
exporters: [logging, otlp/elastic]
metrics:
receivers: [otlp]
processors: [..., memory_limiter, batch]
exporters: [logging, otlp/elastic]
logs:
receivers: [otlp]
processors: [..., memory_limiter, batch]
exporters: [logging, otlp/elastic]
- 接收器，例如 OTLP 接收器（转发由 APM Agent 发出的数据）或 主机指标接收器。
- 我们建议使用 批处理处理器和 内存限制器处理器。 有关更多信息，请参见 推荐的处理器。
- 日志记录导出器有助于进行问题排查，并支持各种日志记录级别，例如
debug、info、warn和error。 - Elastic Observability Serverless 端点配置。 Elastic 通过 gRPC 传输的 OTLP 协议 (OTLP/gRPC) 和通过 HTTP 传输的 OTLP 协议 (OTLP/HTTP) 支持 ProtoBuf 有效负载。 要了解有关这些导出器的更多信息，请参阅 OpenTelemetry 收集器文档：OTLP/HTTP 导出器 或 OTLP/gRPC 导出器。
- Elastic 端点的主机名和端口。 例如，
elastic-apm-server:8200。 - Elastic APM API 密钥授权凭据 (
Authorization: "ApiKey an_api_key")。 - 特定于环境的配置参数可以方便地作为环境变量传递，如 此处所述（例如，
ELASTIC_APM_SERVER_ENDPOINT和ELASTIC_APM_API_KEY）。 - [预览] 要将 OpenTelemetry 日志发送到您的项目，请声明一个
logs管道。
您现在可以从您的服务和应用程序导出跟踪和指标。
使用 OpenTelemetry 收集器时，您应始终首选通过 OTLP 导出器发送数据。 使用其他方法，例如 elasticsearch 导出器，将绕过 Elastic 执行的所有验证和数据处理。 此外，如果您使用 elasticsearch 导出器，则您的数据将无法在您的 Observability 项目中查看。
本文档概述了如何直接从上游 OpenTelemetry SDK 向 Elastic 发送数据，这适合入门时使用。 但是，在许多情况下，您应该使用 OpenTelemetry SDK 将数据发送到 OpenTelemetry 收集器，该收集器处理数据并将其导出到 Elastic。 在 OpenTelemetry 文档中阅读有关何时以及如何使用收集器的更多信息。
要将跟踪和指标导出到 Elastic，请使用 OpenTelemetry API、SDK 或两者来检测您的服务和应用程序。 例如，如果您是 Java 开发人员，则需要使用 OpenTelemetry agent for Java 检测您的 Java 应用程序。 请参阅 OpenTelemetry Instrumentation 指南，以下载您的语言的 OpenTelemetry Agent 或 SDK。
定义环境变量以配置 OpenTelemetry Agent 或 SDK 并启用与 Elastic APM 的通信。 例如，如果您正在检测 Java 应用程序，请定义以下环境变量
export OTEL_RESOURCE_ATTRIBUTES=service.name=checkoutService,service.version=1.1,deployment.environment=production
export OTEL_EXPORTER_OTLP_ENDPOINT=https://apm_server_url:8200
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer an_apm_secret_token"
export OTEL_METRICS_EXPORTER="otlp" \
export OTEL_LOGS_EXPORTER="otlp" \
java -javaagent:/path/to/opentelemetry-javaagent-all.jar \
-classpath lib/*:classes/ \
com.mycompany.checkout.CheckoutServiceServer
- [预览] 当前通过 APM Server 接收 OpenTelemetry 日志的功能处于技术预览阶段。
OTEL_RESOURCE_ATTRIBUTES- 描述服务和服务运行环境的字段。 有关更多信息，请参见 属性。
OTEL_EXPORTER_OTLP_ENDPOINT- APM Server URL。 APM Server 侦听事件的主机和端口。
OTEL_EXPORTER_OTLP_HEADERS-
包含 Elastic APM 密钥令牌或 API 密钥的授权标头：
"Authorization=Bearer an_apm_secret_token"或"Authorization=ApiKey an_api_key"。有关如何格式化 API 密钥的信息，请参见 API 密钥。
请注意
Bearer和an_apm_secret_token以及ApiKey和an_api_key之间所需的空格。注意如果您使用的是 Python OpenTelemetry Agent 的早于 1.27.0 的版本，则标头的内容必须经过 URL 编码。 您可以使用 Python 标准库的
urllib.parse.quote函数来对标头的内容进行编码。 OTEL_METRICS_EXPORTER- 要使用的指标导出器。 有关更多信息，请参见 导出器选择。
OTEL_LOGS_EXPORTER-
要使用的日志导出器。 有关更多信息，请参见 导出器选择。
export OTEL_RESOURCE_ATTRIBUTES=service.name=checkoutService,service.version=1.1,deployment.environment=production
export OTEL_EXPORTER_OTLP_ENDPOINT=https://apm_server_url:8200
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey an_apm_api_key"
export OTEL_METRICS_EXPORTER="otlp" \
export OTEL_LOGS_EXPORTER="otlp" \
java -javaagent:/path/to/opentelemetry-javaagent-all.jar \
-classpath lib/*:classes/ \
com.mycompany.checkout.CheckoutServiceServer
- [预览] 当前通过 Elastic 接收 OpenTelemetry 日志的功能处于技术预览阶段。
OTEL_RESOURCE_ATTRIBUTES- 描述服务和服务运行环境的字段。 有关更多信息，请参见 属性。
OTEL_EXPORTER_OTLP_ENDPOINT- Elastic URL。 Elastic 侦听 APM 事件的主机和端口。
OTEL_EXPORTER_OTLP_HEADERS-
包含 Elastic APM API 密钥的授权标头：
"Authorization=ApiKey an_api_key"。 请注意ApiKey和an_api_key之间所需的空格。有关如何格式化 API 密钥的信息，请参阅 与 APM Agent 的安全通信。
注意如果您使用的是 Python OpenTelemetry Agent 的早于 1.27.0 的版本，则标头的内容必须经过 URL 编码。 您可以使用 Python 标准库的
urllib.parse.quote函数来对标头的内容进行编码。 OTEL_METRICS_EXPORTER- 要使用的指标导出器。 有关更多信息，请参见 导出器选择。
OTEL_LOGS_EXPORTER-
要使用的日志导出器。 有关更多信息，请参见 导出器选择。
您现在可以收集跟踪和 指标，然后再 验证指标和 可视化指标。
APM Server 在与 Elastic APM Agent 请求相同的端口上同时支持 OTLP/gRPC 和 OTLP/HTTP 协议。 为了便于设置，我们建议在代理或负载平衡到 Elastic 的请求时使用 OTLP/HTTP。
如果您使用 OTLP/gRPC 协议，则到 Elastic 的请求必须使用通过 TLS 的 HTTP/2 或 HTTP/2 明文 (H2C)。 无论使用哪种协议，OTLP/gRPC 请求都将具有以下标头："Content-Type: application/grpc"。
当使用像 AWS ALB 这样的第 7 层 (L7) 代理时，必须以确保对 Elastic 的请求遵循上述规则的方式进行代理。例如，使用 ALB，您可以创建规则来基于进入 ALB 的请求的标头选择备用的后端协议。在此示例中，当请求中存在 "Content-Type: application/grpc" 标头时，您将选择 gRPC 协议。
许多 L7 负载均衡器分别处理 HTTP 和 gRPC 流量，并依赖于明确定义的路由和服务配置来正确代理请求。由于 APM Server 在同一端口上提供这两种协议，因此它可能与某些 L7 负载均衡器不兼容。例如，为了解决 Kubernetes 的 Ingress NGINX Controller 中的这个问题，可以
- 在 OTel 收集器中使用
otlp导出器。在代理到 APM Server 的 K8s Ingress 对象上设置注释nginx.ingress.kubernetes.io/backend-protocol: "GRPC"。 - 在 OTel 收集器中使用
otlphttp导出器。在代理到 APM Server 的 K8s Ingress 对象上设置注释nginx.ingress.kubernetes.io/backend-protocol: "HTTP"(如果 APM Server 期望 TLS，则为"HTTPS")。
首选方法是在 APM Server 前面部署 L4 (TCP) 负载均衡器（例如 AWS 上的 NLB），该负载均衡器透明地转发原始 TCP 流量，而无需协议检查。
有关如何配置 AWS ALB 以支持 gRPC 的更多信息，请参阅这篇 AWS 博客文章：Application Load Balancer Support for End-to-End HTTP/2 and gRPC。
有关 APM Server 如何服务 gRPC 请求的更多信息，请参阅 Muxing gRPC and HTTP/1.1。