# 开始使用
要开始在 CloudWatch 中使用 OpenTelemetry，可以使用 CloudWatch 代理提供的预打包的 OpenTelemetry 设置以及适用于 OpenTelemetry SDK 的 AWS Distro。这为您带来了 CloudWatch 中集成度最高的监控体验。
**注意**
在将 OTLP 端点用于跟踪数据之前，请确保启用事务搜索功能。
或者，您可以灵活地使用 OpenTelemetry Collector 或您自己的自定义 OpenTelemetry Collector 将遥测数据直接发送到 OTLP 端点。可以使用 AWS Distro for OpenTelemetry 实现无收集器，并将遥测数据直接发送到 OTLP 端点。根据功能支持做出明智的选择：
| 功能 | OpenTelemetry 收集器 | 自定义 OpenTelemetry Collector | 适用于 OpenTelemetry 的 AWS Distro |
| --- | --- | --- | --- |
| CloudWatch Application Signals（应用程序性能指标、服务发现、应用程序图） | 支持 | 是 | 是 |
| 搜索并分析跨度和跟踪摘要 | 支持 | 是 | 是 |
| 搜索并分析日志摘要 | 支持 | 是 | 是 |
| 使用托管应用程序的 AWS 基础设施属性来丰富应用程序性能监控遥测数据。 | 否 | 是 | 是 |
| 运行时指标与您的应用程序相关。例如，JVM 指标 | 否 | 是 | 否 |
| AWS 支持 | AWS 接收的数据 | AWS 接收的数据 | AWS 接收的数据 |
| 支持遥测 | 日志、指标、跟踪数据 | 日志、跟踪信息、指标 | 指标、跟踪数据 |
**Topics**
+ [OpenTelemetry 收集器](CloudWatch-OTLPSimplesetup.md)
+ [构建您自己的自定义 OpenTelemetry Collector](CloudWatch-OTLPAdvancedsetup.md)
+ [使用 AWS Distro for OpenTelemetry（ADOT）SDK 导出无收集器模式的遥测数据](CloudWatch-OTLP-UsingADOT.md)
+ [在 PromQL 中启用已出售指标](CloudWatch-OTelEnrichment.md)
# OpenTelemetry 收集器
OpenTelemetry Collector 是一个与供应商无关的开源代理，可接收、处理和导出遥测数据。该代理充当应用程序与 Amazon CloudWatch 之间的中心管道，从多个来源收集指标、日志和跟踪数据，然后使用 OpenTelemetry Protocol（OTLP）将其发送到 CloudWatch。
将 OpenTelemetry Collector 与 CloudWatch 搭配使用具有以下优势：
+ 通过单个代理从多个应用程序和主机收集遥测数据，从而减少与 CloudWatch 的连接数量。
+ 在将遥测数据发送到 CloudWatch 之前，对数据进行处理和筛选，包括添加或删除属性、批处理数据和采样跟踪数据。
+ 在 AWS、本地和其他云环境中使用相同的收集器配置，无论应用程序在哪里运行，都能提供一致的遥测管道。
+ 将带有丰富标签的指标发送到 CloudWatch，且可在 CloudWatch Query Studio 中使用 Prometheus 查询语言（PromQL）查询这些标签。
## 支持的接收器
OpenTelemetry Collector 支持各种用于摄取遥测数据的接收器。可以使用 OpenTelemetry 接收器，例如将 OTLP 接收器用于使用 OpenTelemetry SDK 埋点的应用程序，或者使用 Prometheus 接收器从现有 Prometheus 导出器中抓取指标。与 CloudWatch 一起使用的常见 Prometheus 接收器包括：
+ Prometheus 接收器，用于抓取任何兼容 Prometheus 的端点
+ 主机指标接收器，用于从主机收集系统级指标
+ Kubernetes 集群接收器，用于从 Kubernetes API 服务器收集集群级别的指标
您可以在单个收集器中配置多个接收器，从而收集 OpenTelemetry 和 Prometheus 指标，并通过同一个管道将它们发送到 CloudWatch。有关可用接收器的完整列表，请参阅 OpenTelemetry Collector [存储库](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver)。
## 开始使用
先决条件：如果使用 OTLP 端点进行跟踪，请确保启用事务搜索功能。
步骤：
1. 下载最新版本的 OpenTelemetry Collector 发行版。有关更多信息，请参阅 OpenTelemetry Collector [版本](https://github.com/open-telemetry/opentelemetry-collector-releases/releases)。
1. 在主机上安装 OpenTelemetry Collector。该收集器可在任何操作系统和平台上运行。有关更多信息，请参阅 [Install the Collector](https://opentelemetry.io/docs/collector/installation/)。
1. 在 Amazon EC2 或本地主机上配置 AWS 凭证。发送遥测数据时，该收集器使用这些凭证向 CloudWatch 进行身份验证。有关详细信息，请参阅下文。
------
#### [ Setup IAM permissions for Amazon EC2 ]
**按照以下步骤将 `CloudWatchAgentServerPolicy` IAM 策略附加到 Amazon EC2 实例的 IAM 角色。**
1. 通过 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 打开 IAM 控制台。
1. 选择**角色**，查找并选择您的 Amazon EC2 实例使用的角色。
1. 在**权限**选项卡下，选择**添加权限**、**附加策略**。
1. 使用搜索框，搜索 `CloudWatchAgentServerPolicy` 策略。
1. 选择 **CloudWatchAgentServerPolicy** 策略，然后选择**添加权限**。
------
#### [ Setup IAM permissions for on-premise hosts ]
**可以创建用于向本地主机提供权限的 IAM 用户：**
1. 通过 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 打开 IAM 控制台。
1. 依次选择**用户**、**创建用户**。
1. 在**用户详细信息**下，为**用户名**输入新 IAM 用户的名称。这是 AWS 的登录名，将用于对您的主机进行身份验证。
1. 选择**下一步**。
1. 在**设置权限**页面的**权限选项**下，选择**直接附加策略**。
1. 从**权限策略**列表中，选择要添加到您的用户的 **CloudWatchAgentServerPolicy** 策略。
1. 选择**下一步**。
1. 在**审核并创建**页面上，确保您对用户名满意，并且 **CloudWatchAgentServerPolicy** 策略位于**权限摘要**下。
1. 选择**创建用户**。
1. **创建并检索您的 AWS 访问密钥和秘密密钥** – 在 IAM 控制台的导航窗格中，选择**用户**，然后选择您在上一步中所创建用户的用户名。
1. 在用户的页面上，选择**安全凭证**选项卡。
1. 在**访问密钥**部分，选择**创建访问密钥**。
1. 对于**创建访问密钥步骤 1**，选择**命令行界面 (CLI)**。
1. 对于**创建访问密钥步骤 2**，（可选）输入标记，然后选择**下一步**。
1. 对于**创建访问密钥步骤 3**，选择**下载.csv 文件**以保存包含您的 IAM 用户访问密钥和秘密访问密钥的 .csv 文件。您在后续步骤中需要此信息。
1. 选择**完成**。
1. 通过输入以下命令，在本地主机中配置 AWS 凭证。将 *ACCESS\$1KEY\$1ID* 和 *SECRET\$1ACCESS\$1ID* 替换为您在上一步中下载的 .csv 文件中新生成的访问密钥和秘密访问密钥。
```
$ aws configure
AWS Access Key ID [None]: ACCESS_KEY_ID
AWS Secret Access Key [None]: SECRET_ACCESS_ID
Default region name [None]: MY_REGION
Default output format [None]: json
```
------
1. 为 Amazon EKS 或 Kubernetes 集群设置 AWS 凭证。开始使用 Amazon EKS 的最简单方式是使用 EKS OTel Container Insights 附加组件。如果您偏好直接使用 OpenTelemetry Collector，请按照以下步骤为 Amazon EKS 或 Kubernetes 集群设置 AWS 凭证，以向 CloudWatch 发送遥测数据。
------
#### [ Setup IAM permissions for Amazon EKS ]
1. 使用以下命令为您的集群创建 IAM OIDC 身份提供商。
```
eksctl utils associate-iam-oidc-provider --cluster ${CLUSTER_NAME} --region ${REGION} --approve
```
1. 使用以下命令为 OTel Collector 的 Kubernetes 服务账户分配 IAM 角色。
```
eksctl create iamserviceaccount \
--name ${COLLECTOR_SERVICE_ACCOUNT}\
--namespace ${NAMESPACE} \
--cluster ${CLUSTER_NAME} \
--region ${REGION} \
--attach-policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
--approve \
--override-existing-serviceaccounts
```
------
#### [ Setup IAM permissions for Kubernetes ]
1. 通过输入以下命令，在本地主机中配置 AWS 凭证。将 *ACCESS\$1KEY\$1ID* 和 *SECRET\$1ACCESS\$1ID* 替换为您在上一步中下载的 .csv 文件中新生成的访问密钥和秘密访问密钥。默认情况下，凭证文件保存在 */home/user/.aws/credentials* 下。
```
aws configure
AWS Access Key ID [None]: ACCESS_KEY_ID
AWS Secret Access Key [None]: SECRET_ACCESS_ID
Default region name [None]: MY_REGION
Default output format [None]: json
```
1. 使用以下命令编辑 OpenTelemetry Collector 资源以添加新创建的 Amazon 凭证密钥：`kubectl edit OpenTelemetryCollector otel_collector`
1. 使用文件编辑器，通过将以下配置添加到部署顶部，将 AWS 凭证添加到 OpenTelemetryCollector 容器中。将路径 */home/user/.aws/credentials* 替换为本地 AWS 凭证文件的位置。
```
spec:
volumeMounts:
- mountPath: /rootfs
volumeMounts:
- name: aws-credentials
mountPath: /root/.aws
readOnly: true
volumes:
- hostPath:
path: /home/user/.aws/credentials
name: aws-credentials
```
------
1. 在收集器配置中配置 OTLP 导出器，以将遥测数据发送到 CloudWatch 端点。请参阅以下示例。
## 收集器配置示例
复制并粘贴以下内容，以配置您的收集器将日志和跟踪发送到 OTLP 端点。
```
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
exporters:
otlphttp/logs:
compression: gzip
logs_endpoint: logs_otlp_endpoint
headers:
x-aws-log-group: ency_log_group
x-aws-log-stream: default
auth:
authenticator: sigv4auth/logs
otlphttp/traces:
compression: gzip
traces_endpoint: traces_otlp_endpoint
auth:
authenticator: sigv4auth/traces
extensions:
sigv4auth/logs:
region: "region"
service: "logs"
sigv4auth/traces:
region: "region"
service: "xray"
service:
telemetry:
extensions: [sigv4auth/logs, sigv4auth/traces]
pipelines:
logs:
receivers: [otlp]
exporters: [otlphttp/logs]
traces:
receivers: [otlp]
exporters: [otlphttp/traces]
```
下面是使用 sigv4 向 us-east-1 发送日志和跟踪的示例。
```
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
exporters:
otlphttp/logs:
compression: gzip
logs_endpoint: https://logs.us-east-1.amazonaws.com/v1/logs
headers:
x-aws-log-group: MyApplicationLogs
x-aws-log-stream: default
auth:
authenticator: sigv4auth/logs
otlphttp/traces:
compression: gzip
traces_endpoint: https://xray.us-east-1.amazonaws.com/v1/traces
auth:
authenticator: sigv4auth/traces
extensions:
sigv4auth/logs:
region: "us-east-1"
service: "logs"
sigv4auth/traces:
region: "us-east-1"
service: "xray"
service:
telemetry:
extensions: [sigv4auth/logs, sigv4auth/traces]
pipelines:
logs:
receivers: [otlp]
exporters: [otlphttp/logs]
traces:
receivers: [otlp]
exporters: [otlphttp/traces]
```
**注意**
将 OpenTelemetry SDK 配置为 *always\$1on* 采样配置，进而可靠地记录 100% 的跨度，并通过 CloudWatch Application Signals 全面了解您的关键应用程序。有关更多信息，请参阅 [OpenTelemetry Java SDK 采样器配置](https://opentelemetry.io/docs/languages/java/sdk/#sampler)示例。有关使用 X-Ray OTLP 端点设置 OpenTelemetry Collector 的示例，请参阅[应用程序信号演示](https://github.com/aws-observability/application-signals-demo/blob/main/scripts/opentelemetry/otel_simple_setup/opentelemetry.yaml)存储库。
复制并粘贴以下内容，将您的收集器配置为向 OTLP 端点发送指标。
```
receivers:
otlp:
protocols:
http:
endpoint: "0.0.0.0:4318"
processors:
batch:
send_batch_size: 200
timeout: 10s
exporters:
otlphttp:
tls:
insecure: false
endpoint: metrics_otlp_endpoint
auth:
authenticator: sigv4auth
extensions:
sigv4auth:
service: "monitoring"
region: "region"
service:
extensions: [sigv4auth]
pipelines:
metrics:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp]
```
下面是使用 sigv4 向 us-east-1 发送指标的示例。
```
receivers:
otlp:
protocols:
http:
endpoint: "0.0.0.0:4318"
processors:
batch:
send_batch_size: 200
timeout: 10s
exporters:
otlphttp:
tls:
insecure: false
endpoint: "https://monitoring.us-east-1.amazonaws.com/v1/metrics:443"
auth:
authenticator: sigv4auth
extensions:
sigv4auth:
service: "monitoring"
region: "us-east-1"
service:
extensions: [sigv4auth]
pipelines:
metrics:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp]
```
# 构建您自己的自定义 OpenTelemetry Collector
您可以构建自己的自定义 OpenTelemetry Collector，进而通过 OpenTelemetry 在 CloudWatch 中获得极佳的应用程序可观测性体验。在此设置中，您需要使用开源 CloudWatch 组件构建自己的 OpenTelemetry Collector。
## 先决条件
确保在 CloudWatch 中启用了 *Transaction Search*。有关更多信息，请参阅 [Transaction Search](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html)。
## 构建您自己的收集器
您可以使用以下配置构建自己的收集器，进而使用 OpenTelemetry 在 CloudWatch 中监控您的应用程序。有关更多信息，请参阅 [Building a custom collector](https://opentelemetry.io/docs/collector/custom-collector/)。
CloudWatch 的常用配置。
```
dist:
name: otelcol-dev
description: OTel Collector for sending telemetry to CloudWatch.
output_path: ./otelcol-dev
extensions:
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/sigv4authextension v0.111.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/awsproxy v0.113.0
exporters:
- gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.111.0
- gomod: go.opentelemetry.io/collector/exporter/otlphttpexporter v0.111.0
receivers:
- gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.111.0
```
跟踪的额外配置。
```
# Enable Tracing
dist:
name: otelcol-dev
description: OTel Collector for sending telemetry to CloudWatch.
output_path: ./otelcol-dev
extensions:
#Include common configurations and your custom extensions
exporters:
#Include common configurations and your custom extensions
receivers:
- gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.111.0
processors:
- gomod: github.com/amazon-contributing/opentelemetry-collector-contrib/processor/awsapplicationsignalsprocessor v0.113.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/resourcedetectionprocessor v0.113.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricstransformprocessor v0.113.0
replaces:
- github.com/open-telemetry/opentelemetry-collector-contrib/internal/aws/awsutil v0.113.0 => github.com/amazon-contributing/opentelemetry-collector-contrib/internal/aws/awsutil v0.113.0
- github.com/open-telemetry/opentelemetry-collector-contrib/internal/aws/cwlogs v0.113.0 => github.com/amazon-contributing/opentelemetry-collector-contrib/internal/aws/cwlogs v0.113.0
- github.com/open-telemetry/opentelemetry-collector-contrib/exporter/awsemfexporter v0.113.0 => github.com/amazon-contributing/opentelemetry-collector-contrib/exporter/awsemfexporter v0.113.0
- github.com/openshift/api v3.9.0+incompatible => github.com/openshift/api v0.0.0-20180801171038-322a19404e37
```
**注意**
请注意以下几点：
构建收集器后，按照 [OpenTelemetry 收集器](CloudWatch-OTLPSimplesetup.md) 中的步骤在主机或 Kubernetes 环境中部署和配置自定义收集器。
有关 Application Signals Processor 设置自定义 OpenTelemetry 收集器的信息，请参阅 [Application Signals 自定义配置](https://github.com/aws-observability/application-signals-demo/blob/main/scripts/opentelemetry/appsignals_custom_otel_setup/custom-opentelemetry.yaml)示例。Application Signals Processor 仅支持用于自定义版本的最新版本的 OpenTelemetry 收集器。有关支持版本的信息，请参阅 [opentelemetry-collector-contrib 存储库](https://github.com/amazon-contributing/opentelemetry-collector-contrib/tags)。
# 使用 AWS Distro for OpenTelemetry（ADOT）SDK 导出无收集器模式的遥测数据
您可以使用 ADOT SDK 以无收集器模式直接将指标、跟踪数据和日志发送到 OTLP 端点。
**注意**
Application Signals 包含事务搜索功能。为避免重复计费，请在 ADOT SDK 中禁用 Application Signals，同时将 `OTEL_AWS_APPLICATION_SIGNALS_ENABLED` 设为 false（默认设置）。
**Topics**
+ [先决条件](#CloudWatch-OTLP-UsingADOT-Prerequisite)
+ [为角色设置 IAM 权限](#setup-iam-permissions-role)
+ [配置凭证提供者](#configure-credentials-providers)
+ [启用 ADOT SDK](#Enabling-ADOT)
## 先决条件
如果在使用跟踪数据，请确保启用事务搜索功能，以向 X-ray OTLP 端点发送跨度。有关更多信息，请参阅[开始使用 Transaction Search](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search-getting-started.html)。
## 为角色设置 IAM 权限
按照以下步骤将必要 IAM 策略附加到 IAM 角色：
**跟踪：**
1. 通过 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 打开 IAM 控制台。
1. 选择**角色**，然后找到并选择配置的角色。
1. 在**权限**选项卡下，依次选择**添加权限**、**附加策略**。
1. 使用搜索框，搜索 `AWSXrayWriteOnlyPolicy`。
1. 选择 `AWSXrayWriteOnlyPolicy` 策略，然后选择**添加权限**。
**日志：**
1. 通过 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 打开 IAM 控制台。
1. 选择**角色**，然后找到并选择配置的角色。
1. 在**权限**选项卡中，选择**添加权限**，然后选择**创建内联策略**。
1. 为服务选择 **CloudWatch Logs**，然后在**允许的操作**下筛选并选择：
```
logs:PutLogEvents
logs:DescribeLogGroups
logs:DescribeLogStreams
```
1. 以下是授予所需权限的示例 IAM 策略：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "CloudWatchLogsAccess",
"Effect": "Allow",
"Action": [
"logs:PutLogEvents",
"logs:DescribeLogGroups",
"logs:DescribeLogStreams"
],
"Resource": [
"arn:aws:logs:*:*:log-group:*"
]
}
]
}
```
------
## 配置凭证提供者
ADOT 使用 AWS SDK 自动发现将遥测数据导出到 AWS 所需的有效凭证。有关为特定环境配置凭证的指导说明，[请参阅关于 AWS SDK 如何检索凭证的文档](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html)。
**设置本地主机的 IAM 凭证：**
通过输入以下命令，在本地主机中配置 AWS 凭证。将 **ACCESS\$1KEY\$1ID** 和 **SECRET\$1ACCESS\$1KEY** 替换为所配置 IAM 角色或用户的凭证。
```
$ aws configure
AWS Access Key ID [None]: ACCESS_KEY_ID
AWS Secret Access Key [None]: SECRET_ACCESS_ID
Default region name [None]: MY_REGION
Default output format [None]: json
```
## 启用 ADOT SDK
在 Java、Node.js、Python 和 .Net 上，可以将应用程序的日志和跟踪信息从 AWS Distro for OpenTelemetry（ADOT）SDK 发直接送到 OTLP 端点。
------
#### [ Java ]
**注意**
必须采用 **2.11.2 或更高版本的 ADOT Java 代理**，才能使用这些功能。
1. 下载最新版本的 AWS Distro for OpenTelemetry Java 自动检测代理。您可以使用此命令下载最新版本：
```
curl -L -O https://github.com/aws-observability/aws-otel-java-instrumentation/releases/latest/download/aws-opentelemetry-agent.jar
```
您可以在 [aws-otel-java-instrumentation 版本](https://github.com/aws-observability/aws-otel-java-instrumentation/releases)上查看有关所有已发布版本的信息。
1. 要启用直接向 OTLP 端点发送遥测数据的其他导出器并充分发挥其优势，请在启动应用程序之前配置以下环境变量：
**跟踪：**
+ 设置 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 以指定 X-Ray OTLP 跟踪端点：`https://xray.[AWSRegion].amazonaws.com/v1/traces`
例如：
```
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"
```
+ 将 `OTEL_TRACES_EXPORTER` 设置为 `otlp`（此为可选设置，如果未设置此环境变量，则使用默认值）。
+ 将 `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` 变量设置为 `http/protobuf`（此为可选设置，如果未设置此环境变量，则使用默认值）。
+ 设置 `OTEL_RESOURCE_ATTRIBUTES` 变量以将以下信息指定为键值对。这些环境变量供 Application Signals 使用，并会被转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。
+ （可选）`service.name` 设置服务的名称。这将作为应用程序的服务名称在 Application Signals 控制面板中显示。如果您不提供此键的值，将使用默认值 `UnknownService`。
+ （可选）`deployment.environment` 设置应用程序运行所在的环境。这将显示为应用程序的**托管**环境。
+ （可选）要启用跟踪日志关联，请在 `OTEL_RESOURCE_ATTRIBUTES` 中为应用程序的日志组设置其他环境变量 `aws.log.group.names`。这样，应用程序的跟踪和指标便可与这些特定日志组的相关日志条目相关联。对于此变量，将 `$YOUR_APPLICATION_LOG_GROUP` 替换为应用程序的日志组名称。如果您有多个日志组，则可以使用和号（`&`）分隔它们，如以下示例所示：`aws.log.group.names=log-group-1&log-group-2`。要启用指标与日志关联的功能，设置此当前环境变量已足够。有关更多信息，请参阅[启用指标与日志关联](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Application-Signals-MetricLogCorrelation.html)。要启用跟踪与日志关联，您还需要更改应用程序中的日志记录配置。有关更多信息，请参阅[启用跟踪与日志关联](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Application-Signals-TraceLogCorrelation.html)。
**日志：**
+ 设置 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` 以指定 CloudWatch OTLP 日志端点：`https://logs.[AWSRegion].amazonaws.com/v1/logs`
例如：
```
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="https://logs.us-west-2.amazonaws.com/v1/logs"
```
+ 设置 `OTEL_EXPORTER_OTLP_LOGS_HEADERS` 以指定日志导出到的目标日志组和日志流（注意：这些必须在运行 ADOT **之前**创建）：`x-aws-log-group=[CW-LOG-GROUP-NAME],x-aws-log-stream=[CW-LOG-STREAM-NAME]`
例如：
```
export OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=MyLogGroup,x-aws-log-stream=default
```
+ 将 `OTEL_LOGS_EXPORTER` 设置为 `otlp`（此为可选设置，如果未设置此环境变量，则使用默认值）。
+ 将 `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` 变量设置为 `http/protobuf`（此为可选设置，如果未设置此环境变量，则使用默认值）。
1. 设置 `JAVA_TOOL_OPTIONS` 以指定存储 AWS Distro for OpenTelemetry Java 自动插桩代理的路径。例如：
```
export JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH"
export AWS_ADOT_JAVA_INSTRUMENTATION_PATH="./aws-opentelemetry-agent.jar"
```
1. 您的应用程序现在应已启用 ADOT Java 插桩并正常运行，且会生成追踪跨度和日志文件。跨度将存储在 `aws/spans` CloudWatch 日志组中，而日志将存储在 `OTEL_EXPORTER_OTLP_LOGS_HEADERS` 标题指定的日志组中。您还可以在 CloudWatch 跟踪和指标控制台中查看与跨度相关的日志及指标。
1. 使用上一步中列出的环境变量启动应用程序。以下是启动脚本的示例。
```
JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
OTEL_METRICS_EXPORTER=none \
OTEL_TRACES_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_LOGS_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://logs.us-east-1.amazonaws.com/v1/logs \
OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=MyLogGroup,x-aws-log-stream=default
OTEL_RESOURCE_ATTRIBUTES="service.name=$YOUR_SVC_NAME" \
java -jar $MY_JAVA_APP.jar
```
------
#### [ Node.js ]
**注意**
必须采用 **0.7.0 或更高版本的 ADOT JavaScript**，才能使用这些功能。
1. 下载最新版本的 AWS Distro for OpenTelemetry Java 自动插桩。通过运行以下 命令安装它。
```
npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
```
您可以在 [aws-otel-js-instrumentation 版本](https://github.com/aws-observability/aws-otel-js-instrumentation/releases)发布页面查看所有已发布版本的详细信息。
1. 要启用直接向 OTLP 端点发送遥测数据的其他导出器并充分发挥其优势，请在启动应用程序之前配置以下环境变量：
**跟踪：**
+ 设置 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 以指定 X-Ray OTLP 跟踪端点：`https://xray.[AWSRegion].amazonaws.com/v1/traces`
例如：
```
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"
```
+ 将 `OTEL_TRACES_EXPORTER` 设置为 `otlp`（此为可选设置，如果未设置此环境变量，则使用默认值）。
+ 将 `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` 变量设置为 `http/protobuf`（此为可选设置，如果未设置此环境变量，则使用默认值）。
+ 设置 `OTEL_RESOURCE_ATTRIBUTES` 变量以将以下信息指定为键值对。这些环境变量供 Application Signals 使用，并会被转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。
+ （可选）`service.name` 设置服务的名称。这将作为应用程序的服务名称在 Application Signals 控制面板中显示。如果您不提供此键的值，将使用默认值 `UnknownService`。
+ （可选）`deployment.environment` 设置应用程序运行所在的环境。这将显示为应用程序的**托管**环境。
+ （可选）要启用跟踪日志关联，请在 `OTEL_RESOURCE_ATTRIBUTES` 中为应用程序的日志组设置其他环境变量 `aws.log.group.names`。这样，应用程序的跟踪和指标便可与这些特定日志组的相关日志条目相关联。对于此变量，将 `$YOUR_APPLICATION_LOG_GROUP` 替换为应用程序的日志组名称。如果您有多个日志组，则可以使用和号（`&`）分隔它们，如以下示例所示：`aws.log.group.names=log-group-1&log-group-2`。要启用指标与日志关联的功能，设置此当前环境变量已足够。有关更多信息，请参阅[启用指标与日志关联](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Application-Signals-MetricLogCorrelation.html)。要启用跟踪与日志关联，您还需要更改应用程序中的日志记录配置。有关更多信息，请参阅[启用跟踪与日志关联](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Application-Signals-TraceLogCorrelation.html)。
**日志：**
+ 设置 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` 以指定 CloudWatch OTLP 日志端点：`https://logs.[AWSRegion].amazonaws.com/v1/logs`
例如：
```
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="https://logs.us-west-2.amazonaws.com/v1/logs"
```
+ 设置 `OTEL_EXPORTER_OTLP_LOGS_HEADERS` 以指定日志导出到的目标日志组和日志流（注意：这些必须在运行 ADOT **之前**创建）：`x-aws-log-group=[CW-LOG-GROUP-NAME],x-aws-log-stream=[CW-LOG-STREAM-NAME]`
例如：
```
export OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=MyLogGroup,x-aws-log-stream=default
```
+ 将 `OTEL_LOGS_EXPORTER` 设置为 `otlp`（此为可选设置，如果未设置此环境变量，则使用默认值）。
+ 将 `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` 变量设置为 `http/protobuf`（此为可选设置，如果未设置此环境变量，则使用默认值）。
1. 您的应用程序现在应已启用 ADOT JavaScript 插桩并正常运行，且会生成追踪跨度和日志文件。跨度将存储在 `aws/spans` CloudWatch 日志组中，而日志将存储在 `OTEL_EXPORTER_OTLP_LOGS_HEADERS` 标题指定的日志组中。您还可以在 CloudWatch 跟踪和指标控制台中查看与跨度相关的日志及指标。
1. 使用上一步中列出的环境变量启动应用程序。以下是启动脚本的示例。
将 `$SVC_NAME` 替换为您的应用程序的名称。此变量将显示为应用程序的名称。
```
OTEL_METRICS_EXPORTER=none \
OTEL_TRACES_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_LOGS_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://logs.us-east-1.amazonaws.com/v1/logs \
OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=MyLogGroup,x-aws-log-stream=default
OTEL_RESOURCE_ATTRIBUTES="service.name=$YOUR_SVC_NAME" \
node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
```
------
#### [ Python ]
**注意**
必须采用 **0.10.0 或更高版本的 ADOT Python** 并且已安装 **`botocore`**，才能使用这些功能。
1. 下载最新版本的 AWS Distro for OpenTelemetry Python 自动插桩。通过运行以下 命令安装它。
```
pip install aws-opentelemetry-distro
```
您可以在 [aws-otel-python-instrumentation 版本](https://github.com/aws-observability/aws-otel-python-instrumentation/releases)发布页面查看所有已发布版本的详细信息。
1. 要启用直接向 OTLP 端点发送遥测数据的其他导出器并充分发挥其优势，请在启动应用程序之前配置以下环境变量：
**对于跟踪和日志配置，必须设置以下环境变量：**
+ `OTEL_PYTHON_DISTRO` 到 `aws_distro`
+ `OTEL_PYTHON_CONFIGURATOR` 到 `aws_configurator`
**跟踪：**
+ 设置 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 以指定 X-Ray OTLP 跟踪端点：`https://xray.[AWSRegion].amazonaws.com/v1/traces`
例如：
```
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"
```
+ 将 `OTEL_TRACES_EXPORTER` 设置为 `otlp`（此为可选设置，如果未设置此环境变量，则使用默认值）。
+ 将 `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` 变量设置为 `http/protobuf`（此为可选设置，如果未设置此环境变量，则使用默认值）。
+ 设置 `OTEL_RESOURCE_ATTRIBUTES` 变量以将以下信息指定为键值对。这些环境变量供 Application Signals 使用，并会被转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。
+ （可选）`service.name` 设置服务的名称。这将作为应用程序的服务名称在 Application Signals 控制面板中显示。如果您不提供此键的值，将使用默认值 `UnknownService`。
+ （可选）`deployment.environment` 设置应用程序运行所在的环境。这将显示为应用程序的**托管**环境。
+ （可选）要启用跟踪日志关联，请在 `OTEL_RESOURCE_ATTRIBUTES` 中为应用程序的日志组设置其他环境变量 `aws.log.group.names`。这样，应用程序的跟踪和指标便可与这些特定日志组的相关日志条目相关联。对于此变量，将 `$YOUR_APPLICATION_LOG_GROUP` 替换为应用程序的日志组名称。如果您有多个日志组，则可以使用和号（`&`）分隔它们，如以下示例所示：`aws.log.group.names=log-group-1&log-group-2`。要启用指标与日志关联的功能，设置此当前环境变量已足够。有关更多信息，请参阅[启用指标与日志关联](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Application-Signals-MetricLogCorrelation.html)。要启用跟踪与日志关联，您还需要更改应用程序中的日志记录配置。有关更多信息，请参阅[启用跟踪与日志关联](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Application-Signals-TraceLogCorrelation.html)。
**日志：**
+ 将 `OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED` 设置为 `true`
+ 设置 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` 以指定 CloudWatch OTLP 日志端点：`https://logs.[AWSRegion].amazonaws.com/v1/logs`
例如：
```
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="https://logs.us-west-2.amazonaws.com/v1/logs"
```
+ 设置 `OTEL_EXPORTER_OTLP_LOGS_HEADERS` 以指定日志导出到的目标日志组和日志流（注意：这些必须在运行 ADOT **之前**创建）：`x-aws-log-group=[CW-LOG-GROUP-NAME],x-aws-log-stream=[CW-LOG-STREAM-NAME]`
例如：
```
export OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=MyLogGroup,x-aws-log-stream=default
```
+ 将 `OTEL_LOGS_EXPORTER` 设置为 `otlp`（此为可选设置，如果未设置此环境变量，则使用默认值）。
+ 将 `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` 变量设置为 `http/protobuf`（此为可选设置，如果未设置此环境变量，则使用默认值）。
1. 您的应用程序现在应已启用 ADOT Python 插桩并正常运行，且会生成追踪跨度和日志文件。跨度将存储在 `aws/spans` CloudWatch 日志组中，而日志将存储在 `OTEL_EXPORTER_OTLP_LOGS_HEADERS` 标题指定的日志组中。您还可以在 CloudWatch 跟踪和指标控制台中查看与跨度相关的日志及指标。
1. 使用上一步中列出的环境变量启动应用程序。以下是启动脚本的示例。
将 `$SVC_NAME` 替换为您的应用程序的名称。此变量将显示为应用程序的名称。
将 `$PYTHON_APP` 替换为您的应用程序的位置和名称。
```
OTEL_METRICS_EXPORTER=none \
OTEL_TRACES_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_LOGS_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://logs.us-east-1.amazonaws.com/v1/logs \
OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=MyLogGroup,x-aws-log-stream=default
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_RESOURCE_ATTRIBUTES="service.name=$YOUR_SVC_NAME" \
opentelemetry-instrument python $MY_PYTHON_APP.py
```
------
#### [ .Net ]
**注意**
必须采用 **1.8.0 或更高版本的 ADOT .NET**，才能使用这些功能。
目前不支持压缩。
当前不支持日志。
下载最新版本适用于 OpenTelemetry 的 AWS Distro .NET 自动仪表化工具包。您可以在 [aws-otel-dotnet-instrumentation 版本](https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases)发布页面查看所有已发布版本的详细信息。
要启用直接向 OTLP 端点发送遥测数据的其他导出器并充分发挥其优势，请在启动应用程序之前配置以下环境变量（将 `OTEL_RESOURCE_ATTRIBUTES` 环境变量中的 `dotnet-service-name` 替换为您选择的服务名称）：
**跟踪：**
+ **必须**将 `OTEL_TRACES_EXPORTER` 设置为 `none`
+ **必须**将 `OTEL_AWS_SIG_V4_ENABLED` 设置为 `true`
此功能**在 .NET 中不会自动启用**。该环境变量是专门为了在 .NET 插桩中明确标识该使用案例而专门要求设置的。此要求仅针对 .NET，**不适用于其他支持的语言**。
以下是适用于 Linux 的设置示例。
```
export INSTALL_DIR=OpenTelemetryDistribution
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318}
export CORECLR_PROFILER_PATH=${INSTALL_DIR}/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
export DOTNET_ADDITIONAL_DEPS=${INSTALL_DIR}/AdditionalDeps
export DOTNET_SHARED_STORE=${INSTALL_DIR}/store
export DOTNET_STARTUP_HOOKS=${INSTALL_DIR}/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
export OTEL_DOTNET_AUTO_HOME=${INSTALL_DIR}
export OTEL_DOTNET_AUTO_PLUGINS="AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
export OTEL_TRACES_EXPORTER=none
export OTEL_AWS_SIG_V4_ENABLED=true
export OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces
```
以下是适用于 Windows Server 的设置示例：
```
$env:INSTALL_DIR = "OpenTelemetryDistribution"
$env:CORECLR_ENABLE_PROFILING = 1
$env:CORECLR_PROFILER = "{918728DD-259F-4A6A-AC2B-B85E1B658318}"
$env:CORECLR_PROFILER_PATH = Join-Path $env:INSTALL_DIR "win-x64/OpenTelemetry.AutoInstrumentation.Native.dll"
$env:DOTNET_ADDITIONAL_DEPS = Join-Path $env:INSTALL_DIR "AdditionalDeps"
$env:DOTNET_SHARED_STORE = Join-Path $env:INSTALL_DIR "store"
$env:DOTNET_STARTUP_HOOKS = Join-Path $env:INSTALL_DIR "net/OpenTelemetry.AutoInstrumentation.StartupHook.dll"
$env:OTEL_DOTNET_AUTO_HOME = $env:INSTALL_DIR
$env:OTEL_DOTNET_AUTO_PLUGINS = "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
$env:OTEL_TRACES_EXPORTER=none
$env:OTEL_AWS_SIG_V4_ENABLED=true
$env:OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
$env:OTEL_METRICS_EXPORTER=none
$env:OTEL_LOGS_EXPORTER=none
$env:OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
$env:OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces
```
1. 使用上一步中列出的环境变量启动应用程序。
1. （可选）或者，您可以使用提供的安装脚本来帮助安装和设置 AWS Distro for OpenTelemetry .NET 自动检测包。
对于 Linux，请从 GitHub 发布页面下载并安装 Bash 安装脚本：
```
# Download and Install
curl -L -O https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/aws-otel-dotnet-install.sh
chmod +x ./aws-otel-dotnet-install.sh
./aws-otel-dotnet-install.sh
# Instrument
. $HOME/.otel-dotnet-auto/instrument.shexport OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
```
对于 Windows Server，请从 GitHub 发布页面下载并安装 PowerShell 安装脚本：
```
# Download and Install
$module_url = "https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/AWS.Otel.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "AWS.Otel.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path
Import-Module $download_path
Install-OpenTelemetryCore
# Instrument
Import-Module $download_path
Register-OpenTelemetryForCurrentSession -OTelServiceName "dotnet-service-name"
Register-OpenTelemetryForIIS
```
您可以在[官方 NuGet 存储库](https://www.nuget.org/packages/AWS.Distro.OpenTelemetry.AutoInstrumentation)中找到 AWS Distro for OpenTelemetry .NET 自动检测包的 NuGet 包。请务必查看[自述文件](https://github.com/aws-observability/aws-otel-dotnet-instrumentation/blob/main/src/AWS.Distro.OpenTelemetry.AutoInstrumentation/nuget-readme.md)以获取说明。
------
# 在 PromQL 中启用已出售指标
您可以启用 OTel 补充功能，使[支持的 AWS 资源](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/UsingResourceTagsForTelemetry.html)的已出售指标可通过 PromQL 进行查询。启用后，包含资源标识符维度的指标（例如，具有 InstanceId 维度的 EC2 CPUUtilization）将补充资源 ARN 和资源标注标签，并且可以使用 PromQL 进行查询。
补充指标保留了原始指标名称和 CloudWatch 维度，并添加了：
+ **资源属性** – 资源 ARN (`cloud.resource_id`)、云提供商、区域和账户 ID。
+ **埋点范围** – 标识源服务并将该指标标记为“OTel 已补充”。
+ **资源标签** – 与资源关联的任何 AWS 资源标签，可作为 PromQL 标签进行查询。
原始的经典 CloudWatch 指标未经修改，仍可通过现有的 CloudWatch API 使用。
## 为已出售指标启用 OpenTelemetry 补充功能
在开始 OTel 补充之前，您必须为账户[针对遥测启用资源标签](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/EnableResourceTagsOnTelemetry.html)。
您可以使用 CloudWatch 控制台、AWS CLI 或 AWS SDK，为特定区域的账户启用 OTel 补充功能。
您需要以下操作的权限：`cloudwatch:StartOTelEnrichment`
**为 AWS 指标启用 OTel 补充功能（CloudWatch 控制台）**
1. 通过 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 打开 CloudWatch 控制台。
1. 在导航面板中选择 **CloudWatch**，再选择**设置**。
1. 在**为 AWS 指标启用 OTel 补充**”窗格中，将功能开关切换为“开启”状态。
**AWS CLI**
```
aws cloudwatch start-o-tel-enrichment
```
要跨多个区域启用，请在每个感兴趣区域中调用 API。
启用补充功能后，便可开始通过 PromQL 查询已出售指标。请参阅：[使用 PromQL 查询 AWS 已出售指标](CloudWatch-PromQL-Querying.md#CloudWatch-PromQL-Querying-Vended)。