Elasticsearch OTLP/HTTP 端点

除了通过 Bulk API 摄入数据外，Elasticsearch 还支持通过 OpenTelemetry 协议 (OTLP) 接收数据。Elasticsearch OTLP/HTTP 端点对外暴露了三个特定于信号的路径

对于大多数用户，建议采用以下更高级别的摄入路径之一

如果 Elastic Cloud 托管的 OTLP 端点在您的部署中可用，即使应用程序可以直接指向 Elasticsearch OTLP 端点，也请优先使用它。

有关基于 OpenTelemetry 的推荐摄入架构的概述，请参考 EDOT 参考架构。

在以下情况下，请直接使用 Elasticsearch OTLP 端点

• 您有一个原生导出 OTLP 的应用程序，并且希望在不运行 OpenTelemetry Collector 的情况下将数据发送到 Elasticsearch。例如，轻量级开发设置（从 SDK 到 Elasticsearch）。
• 您运行了一个自管理的网关 Collector，并且更喜欢使用 OTLP/HTTP 导出器而不是 Elasticsearch 导出器。

与 Bulk API 相比，通过 OTLP 摄入具有以下优势

• 提高了摄入性能，特别是对于包含大量资源属性的有效载荷。
• 简化的映射：数据流、索引模板、维度和指标均从 OTLP 元数据动态派生。无需手动设置它们。

使用 API 密钥向 Elasticsearch OTLP 端点进行身份验证。有关如何创建 API 密钥的说明，请参阅您部署类型的 API 密钥文档

• Elasticsearch API 密钥（自管理、Elastic Cloud Enterprise、Elastic Cloud on Kubernetes）
• Elastic Cloud 托管 API 密钥
• Elastic Cloud Enterprise API 密钥
• Serverless 项目 API 密钥

API 密钥需要在其写入的数据流模式上具有 create_doc 和 auto_configure 权限。create_doc 允许写入文档而不覆盖现有文档。auto_configure 允许端点在首次写入时创建目标数据流。

所需的最低索引模式取决于您摄入的信号

跟踪 (Traces) 摄入还会将 span 事件写入 logs-* 数据流，因此它需要这两种模式。

例如，允许摄入所有三种信号的 API 密钥角色描述符

{
  "indices": [
    {
      "names": ["logs-*", "metrics-*", "traces-*"],
      "privileges": ["create_doc", "auto_configure"]
    }
  ]
}
		

要将数据从 OpenTelemetry Collector 发送到 Elasticsearch OTLP 端点，请配置 OTLP/HTTP 导出器

exporters:
  otlphttp/elasticsearch:
    endpoint: <es_endpoint>/_otlp
    headers:
      Authorization: "ApiKey <api_key>"
    sending_queue:
      enabled: true
      sizer: bytes
      queue_size: 50_000_000
      block_on_overflow: true
      batch:
        flush_timeout: 1s
        min_size: 1_000_000
        max_size: 4_000_000
service:
  pipelines:
    logs:
      exporters: [otlphttp/elasticsearch]
      receivers: ...
    traces:
      exporters: [otlphttp/elasticsearch]
      receivers: ...
    metrics:
      exporters: [otlphttp/elasticsearch]
      receivers: ...
		

1. 调整队列大小并按未压缩字节进行批处理。
2. 将队列限制为 50 MB 的未压缩数据。增加此值可以吸收更长的 Elasticsearch 中断或流量突增，但也会增加 Collector 的内存使用量。
3. 控制发送到 Elasticsearch 的未压缩批处理大小。在此示例中，批处理以 1 MB 发送，上限为 4 MB。较大的批处理可减少请求开销，但会增加峰值内存使用量以及失败请求后重试的数据量。

导出器会将特定于信号的路径 (/v1/logs, /v1/traces, /v1/metrics) 附加到配置的 endpoint。

这些值是网关 Collector 的起点。请针对您的工作负载和 Collector 资源对其进行调整。它们是每个 Collector 实例本地的，并不会增加 Elasticsearch 的摄入容量。如果许多应用程序需要发送遥测数据，请扩展网关 Collector，而不是直接从每个应用程序发送。

支持的 compression 值为 gzip（OTLP/HTTP 导出器的默认值）和 none。

要从自定义应用程序发送数据，请使用您选择的 OpenTelemetry 语言 SDK，并将其 OTLP/HTTP 导出器指向相应的 Elasticsearch OTLP 端点路径。

默认情况下，记录会被写入以下数据流

有关如何将 OTLP 指标存储为时间序列数据流的更多信息，请参阅使用 OTLP/HTTP 端点将指标摄入 TSDS。

目标数据流名称遵循 <type>-<dataset>.otel-<namespace> 的模式。您可以通过在数据上设置属性来影响 dataset 和 namespace

• 将 data_stream.dataset 和/或 data_stream.namespace 设置为属性。优先级：数据点或日志记录属性，然后是作用域属性，最后是资源属性。
• 否则，如果作用域名称包含 /receiver/<somereceiver>，则 data_stream.dataset 会被设置为接收器名称。
• 否则，data_stream.dataset 回退到 generic，data_stream.namespace 回退到 default。

示例

您可以使用 xpack.otel_data.histogram_field_type 集群设置来配置 OTLP 直方图指标的映射方式。有效值为

• histogram (在 上为默认值): 将直方图映射为使用 histogram 字段类型的 T-Digests
• exponential_histogram (在 上为默认值): 将直方图映射为使用 exponential_histogram 字段类型的指数直方图

该设置是动态的，可以在运行时更新

				PUT /_cluster/settings
					{
  "persistent" : {
    "xpack.otel_data.histogram_field_type" : "exponential_histogram"
  }
}
		

由于 histogram 和 exponential_histogram 都支持 强制类型转换，因此动态更改此设置不会导致映射冲突或摄入失败。

此设置仅适用于通过 Elasticsearch OTLP 端点摄入的指标。使用 Bulk API 摄入的文档（例如通过 OpenTelemetry Collector 的 Elasticsearch 导出器）不受影响。

OTLP 端点会保留摄入指标的 时间属性 (temporality)，并将其存储在 temporality 维度中。这允许 Elasticsearch 在 ES|QL 时间序列查询和 降采样期间正确解释计数器和直方图值。

temporality 维度会根据每个指标数据点的 OTLP 聚合时间属性 (AggregationTemporality) 自动设置。无需额外配置。

请注意，只有在 xpack.otel_data.histogram_field_type 设置为 exponential_histogram（这是默认值）时，才支持直方图的累积时间属性。

• 交付保证： Elasticsearch 只能作为一个整体确认 OTLP 请求，而不能基于每条记录进行确认。如果请求的一部分失败，客户端会重试整个批次，这可能会产生重复的日志或跟踪 span。指标不受影响，因为写入时间序列数据流的指标点是基于其维度和时间戳进行去重的。
• 分析 (Profiles)： 不支持分析。要摄入分析数据，请使用包含 Elasticsearch 导出器的 OpenTelemetry Collector 发行版，例如 Elastic OpenTelemetry Collector 发行版 (EDOT)。
• 示例 (Exemplars)： 尚不支持示例。