本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 将采集管道与 C OpenSearch ollector 配合使用 OpenTelemetry
<a name="configure-client-otel"></a>

您可以使用[OpenTelemetry 收集器](https://opentelemetry.io/docs/collector/)将日志、跟踪和指标提取到 OpenSearch 摄取管道中。单个管道可用于将所有日志、跟踪和指标提取到域或集合上的不同索引。您还可以使用管道仅单独采集日志、跟踪或指标。

**Topics**
+ [先决条件](#otel-prereqs)
+ [步骤 1：配置管道角色](#otel-pipeline-role)
+ [步骤 2：创建管道](#create-otel-pipeline)
+ [跨账户连接](#x-account-connectivity)
+ [限制](#otel-limitations)
+ [为 OpenTelemetry 信号源推荐的 CloudWatch 警报](#otel-pipeline-metrics)

## 先决条件
<a name="otel-prereqs"></a>

在设置[OpenTelemetry 配置文件](https://opentelemetry.io/docs/collector/configuration/)时，必须配置以下内容才能进行摄取：
+ 摄取角色需要`osis:Ingest`权限才能与管道交互。有关更多信息，请参阅[摄取角色。](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security-overview.html#pipeline-security-same-account)
+ 端点值必须包含您的管道端点。例如，`https://pipeline-endpoint.us-east-1.osis.amazonaws.com.`
+ 服务值必须为`osis`。
+  OTLP/HTTP 导出器的压缩选项必须与管道所选源上的压缩选项相匹配。

```
extensions:
    sigv4auth:
        region: "region"
        service: "osis"

exporters:
    otlphttp:
        logs_endpoint: "https://pipeline-endpoint.us-east-1.osis.amazonaws.com/v1/logs"
        metrics_endpoint: "https://pipeline-endpoint.us-east-1.osis.amazonaws.com/v1/metrics"
        traces_endpoint: "https://pipeline-endpoint.us-east-1.osis.amazonaws.com/v1/traces"
        auth:
            authenticator: sigv4auth
        compression: none

service:
    extensions: [sigv4auth]
    pipelines:
        traces:
        receivers: [jaeger]
        exporters: [otlphttp]
```

## 步骤 1：配置管道角色
<a name="otel-pipeline-role"></a>

 设置 OpenTelemetry 收集器配置后，[设置要在工作流配置中使用的管道角色](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security-overview.html#pipeline-security-sink)。管道角色不需要 OTLP 源所需的特定权限，只有授予管道访问 OpenSearch 域或集合的权限。

## 步骤 2：创建管道
<a name="create-otel-pipeline"></a>

 然后，您可以配置如下所示的 OpenSearch Ingestion 管道，将 OTLP 指定为来源。您还可以将 OpenTelemetry 日志、指标和跟踪配置为单独的来源。

OTLP 源管道配置：

```
version: 2
otlp-pipeline:
    source:
        otlp:
            logs_path: /otlp-pipeline/v1/logs
            traces_path: /otlp-pipeline/v1/traces
            metrics_path: /otlp-pipeline/v1/metrics
    sink:
        - opensearch:
            hosts: ["https://search-mydomain.region.es.amazonaws.com"]
            index: "ss4o_metrics-otel-%{yyyy.MM.dd}"
            index_type: custom
            aws:
                region: "region"
```

OpenTelemetry 日志管道配置：

```
version: 2
otel-logs-pipeline:
  source:
    otel_logs_source:
        path: /otel-logs-pipeline/v1/logs
  sink:
    - opensearch:
        hosts: ["https://search-mydomain.region.es.amazonaws.com"]
        index: "ss4o_metrics-otel-%{yyyy.MM.dd}"
        index_type: custom
        aws:
            region: "region"
```

OpenTelemetry 指标管道配置：

```
version: 2
otel-metrics-pipeline:
  source:
    otel_metrics_source:
        path: /otel-metrics-pipeline/v1/metrics
  sink:
    - opensearch:
        hosts: ["https://search-mydomain.region.es.amazonaws.com"]
        index: "ss4o_metrics-otel-%{yyyy.MM.dd}"
        index_type: custom
        aws:
            region: "region"
```

OpenTelemetry 跟踪管道配置：

```
version: 2
otel-trace-pipeline:
  source:
    otel_trace_source:
        path: /otel-traces-pipeline/v1/traces
  sink:
    - opensearch:
        hosts: ["https://search-mydomain.region.es.amazonaws.com"]
        index: "ss4o_metrics-otel-%{yyyy.MM.dd}"
        index_type: custom
        aws:
            region: "region"
```

您可以使用预先配置的蓝图，以创建此管道。有关更多信息，请参阅 [使用蓝图](pipeline-blueprint.md)。

## 跨账户连接
<a name="x-account-connectivity"></a>

 OpenSearch 具有 OpenTelemetry 来源的摄取管道具有跨账户摄取功能。Amazon OpenSearch Ingestion 允许您共享 AWS 账户 从虚拟私有云 (VPC) 到独立 VPC 中的管道终端节点的管道。有关更多信息，请参阅 [为跨 OpenSearch 账户摄取配置摄取管道](cross-account-pipelines.md)。

## 限制
<a name="otel-limitations"></a>

 OpenSearch 摄取管道无法接收任何大于 20mb 的请求。此值由用户在`max_request_length`选项中配置。此选项默认为 10mb。

## 为 OpenTelemetry 信号源推荐的 CloudWatch 警报
<a name="otel-pipeline-metrics"></a>

 建议使用以下 CloudWatch 指标来监控您的摄取管道的性能。这些指标可能有助您确定处理的导出数据量、处理的流事件量、处理导出和流事件时的错误数以及写入目标的文档数量。您可以设置 CloudWatch 警报，以便在其中一个指标在指定时间内超过指定值时执行操作。

 OTLP 来源的 CloudWatch 指标格式为。`{pipeline-name}.otlp.{logs | traces | metrics}.{metric-name}`例如 `otel-pipeline.otlp.metrics.requestTimeouts.count`。

 如果使用单个 OpenTelemetry 来源，则指标的格式将为`{pipeline-name}.{source-name}.{metric-name}`。例如 `trace-pipeline.otel_trace_source.requestTimeouts.count`。

所有三种 OpenTelemetry 数据类型都将具有相同的指标，但为简洁起见，下表中仅列出了 OTLP 源日志类型数据的指标。


| 指标 | 说明 | 
| --- |--- |
| otel-pipeline.BlockingBuffer.bufferUsage.value |  指示正在使用的缓冲区数量。  | 
|  otel-pipeline.otlp.logs.requestTimeouts.count  |  已超时的请求数。  | 
|  otel-pipeline.otlp.logs.requestsReceived.count  |   OpenTelemetry 收集器收到的请求数。  | 
|  otel-pipeline.otlp.logs.badRequests.count  |   OpenTelemetry 收集器收到的格式错误的请求数。  | 
|  otel-pipeline.otlp.logs.requestsTooLarge.count  |   OpenTelemetry 收集器收到的大于最大值 20mb 的请求数。  | 
|  otel-pipeline.otlp.logs.internalServerError.count  | 从 OpenTelemetry 收集器收到的 HTTP 500 错误数。 | 
|  otel-pipeline.opensearch.bulkBadRequestErrors.count  | 批量请求期间由于请求格式错误而导致的错误计数。 | 
|  otel-pipeline.opensearch.bulkRequestLatency.avg  | 向发出的批量写入请求的平均延迟 OpenSearch。 | 
|  otel-pipeline.opensearch.bulkRequestNotFoundErrors.count  | 由于找不到目标数据而失败的批量请求数。 | 
|  otel-pipeline.opensearch.bulkRequestNumberOfRetries.count  | 采集管道重试写 OpenSearch 入集群的次数。 OpenSearch | 
|  otel-pipeline.opensearch.bulkRequestSizeBytes.sum  | 向发出的所有批量请求的总大小（以字节为单位） OpenSearch。 | 
|  otel-pipeline.opensearch.documentErrors.count  | 向发送文档时出现的错误数 OpenSearch。导致错误的文件将发送给 DLQ。 | 
|  otel-pipeline.opensearch.documentsSuccess.count  | 成功写入 OpenSearch 集群或集合的文档数。 | 
|  otel-pipeline.opensearch.documentsSuccessFirstAttempt.count  | 第一次尝试成功编入索引 OpenSearch 的文档数。 | 
|  `otel-pipeline.opensearch.documentsVersionConflictErrors.count`  | 处理过程中由于文档版本冲突而导致的错误计数。 | 
|  `otel-pipeline.opensearch.PipelineLatency.avg`  |  OpenSearch Ingestion 管道通过从源读取数据到写入目标来处理数据的平均延迟。 | 
|  otel-pipeline.opensearch.PipelineLatency.max  | 通过从源读取数据到写入目标来处理数据的 OpenSearch Ingestion 管道的最大延迟。 | 
|  otel-pipeline.opensearch.recordsIn.count  | 成功摄入 OpenSearch的记录数。该指标对于跟踪正在处理和存储的数据量至关重要。 | 
|  otel-pipeline.opensearch.s3.dlqS3RecordsFailed.count  | 未能写入 DLQ 的记录数。 | 
|  otel-pipeline.opensearch.s3.dlqS3RecordsSuccess.count  | 写入 DLQ 的记录数。 | 
|  otel-pipeline.opensearch.s3.dlqS3RequestLatency.count  | Amazon S3 死信队列请求的延迟测量次数。 | 
|  otel-pipeline.opensearch.s3.dlqS3RequestLatency.sum  | Amazon S3 死信队列的所有请求的总延迟 | 
|  otel-pipeline.opensearch.s3.dlqS3RequestSizeBytes.sum  | 向 Amazon S3 死信队列发出的所有请求的总大小（以字节为单位）。 | 
|  otel-pipeline.recordsProcessed.count  | 管道中处理的记录总数，这是衡量整体吞吐量的关键指标。 | 
|  `otel-pipeline.opensearch.bulkRequestInvalidInputErrors.count`  |  OpenSearch 由于输入无效而导致的批量请求错误计数，这对于监控数据质量和操作问题至关重要。 |