# 如何向发送到 CloudWatch 的自定义遥测添加相关信息
<a name="adding-your-own-related-telemetry"></a>

当您将自己的指标和日志发布到 CloudWatch 时，默认情况下，其中不存在相关遥测所需的实体信息。当您向 CloudWatch 发送指标或向 CloudWatch Logs 发送日志（使用 [PutMetricData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html) 或 [PutLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) 操作）时，您可以向这些日志或指标添加实体信息。实体信息与遥测相关联，并在**探索相关**功能中用于查找与同一实体关联的相关遥测。

通过遥测发送的实体表示与遥测相关的资源或服务。例如关于服务的指标或来自 AWS 资源的指标。要识别代码中关联的实体，请创建该实体的一组 `KeyAttributes` 和可选 `Attributes`。

**注意**  
CloudWatch 只能找到在过去三个小时内发送了遥测的实体的相关资源。如果您的资源仅发出稀疏遥测（少于每 3 小时发出一次），则可能需要发送额外的*心跳*遥测，以使实体在 CloudWatch 中保持活动状态。

要了解如何添加实体信息，请参阅 [采用 EMF 格式的实体信息](CloudWatch_Embedded_Metric_Format_Specification.md#entity-information-emf-format)。

以下各节介绍如何创建 `KeyAttributes` 和 `Attributes`，以便 CloudWatch 可以识别与遥测相关的资源和服务。

## 使用 KeyAttributes 对象标识实体
<a name="custom-related-telemetry-keyattributes"></a>

实体对象（[在 CloudWatch 中](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_Entity.html)或 [CloudWatch 日志中](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_Entity.html)）的 `KeyAttributes` 属性唯一标识了 CloudWatch 的实体。其值是一个键值对列表。具有相同 `KeyAttributes` 的实体被视为同一实体。与同一实体关联的遥测被视为相关，可以在**探索相关**窗格中轻松找到。

**注意**  
在 CloudWatch API 中，该属性称为 `KeyAttributes`。在 CloudWatch Logs API 中，该属性称为 `keyAttributes`。在这里，它们被视为相同的属性。

`Entity` 可以表示的对象有五种可能的类型。
+ **AWS::Resource**：该实体代表 AWS 资源，例如 DynamoDB 表或 Amazon EC2 实例。
+ **AWS::Service**：该实体代表 AWS 服务，例如 Amazon S3。例如，在调用与特定的 Amazon S3 资源无关的 `ListBuckets` 操作时，可能会使用此方法。
+ **Service**：该实体代表在您的账户中运行的工作负载。例如您管理的应用程序或服务。
+ **Resource**：该实体表示不由 AWS 管理的资源，例如操作系统资源（例如进程或文件卷）。
+ **RemoteService**：该实体代表远程调用中的外部服务。例如，对数据库、外部缓存或外部端点的远程调用。

根据您要表示的上述类型的种类，您必须为 `KeyAttributes` 提供正确的键值对。以下介绍每种类型。

------
#### [ AWS::Resource ]

要指定 AWS 资源，必须包括以下三个键值对：
+ `"Type": "AWS::Resource"`：此键值对将实体标识为 AWS 资源。
+ `"ResourceType": "<resource-type>"`：`ResourceType` 的字符串值是 CloudFormation [资源类型](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html)字符串。例如 `AWS::DynamoDB::Table`。
+ `"Identifier": "<resource-id>"`：变体的资源标识符。有关更多信息，请参阅《Extension Development for CloudFormation User Guide》**中的 [primaryIdentifier](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-schema.html#schema-properties-primaryidentifier)。

------
#### [ AWS::Service ]

要指定 AWS 服务，必须包括以下两个键值对：
+ `"Type": "AWS::Service"`：此键值对将 AWS 服务标识为实体。
+ `"Name": "<service-name>"`：`Name` 的值是 CloudFormation [服务名称](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html)字符串。例如 `AWS::DynamoDB`。

------
#### [ Service ]

要指定不由 AWS 运营的服务，必须包括以下三个键值对：
+ `"Type": "Service"`：此键值对将实体标识为服务。
+ `"Name": "<service-name>"`：此键值对表示发送指标的服务的名称。例如，`my-service-frontend` 或 `api.myservice.com`。
+ `"Environment": "<environment-name>"`：此属性指定服务的托管位置或服务所属的环境。例如，`us-west-2` 或 `myservice.production`。

------
#### [ Resource ]

要指定不由 AWS 提供的资源，必须包括以下三个键值对：
+ `"Type": "Resource"`：此键值对将实体标识为资源。
+ `"ResourceType": "<resource-type>"`：指定资源类型的字符串。例如，`K8s::Pod` 表示 Kubernetes 容器组（pod）。
+ `"Identifier": "<resource-id>"`：资源的字符串标识符。可以包含多个命名空间，用逗号分隔。例如，Kubernetes 容器组（pod）可能由其集群名称、命名空间和容器组（pod）名称来表示，例如 `MyCluster|MyNamespace|MyPod`。

------
#### [ RemoteService ]

要指定远程服务，必须包括以下两个键值对：
+ `"Type": "RemoteService"`：此键值对将实体标识为远程服务。
+ `"Name": "<remote-service-name>"`：此键值对指定应用程序在远程调用中如何引用外部服务。例如 `api.test.myservice.com`。

------

## 提供有关具有 Attributes 对象的实体的更多详细信息
<a name="custom-related-telemetry-attributes"></a>

您可以提供有关您在遥测中提供的 `Entity` 的更多详细信息。这可能包括有关平台、资源、应用程序或遥测提供商的详细信息。下表描述了可用于每种数据类型的关键词。

**注意**  
在 CloudWatch API 中，该属性称为 `Attributes`。在 CloudWatch Logs API 中，该属性称为 `attributes`。在这里，它们被视为相同的属性。

**平台详细信息**


| Keyword | 用法 | 值的域 | 示例 | 
| --- | --- | --- | --- | 
| `PlatformType` | 定义托管平台。 | AWS::EKS、AWS::ECS、AWS::EC2、AWS::Lambda、K8s、Generic | `AWS::EC2` | 
| `EKS.Cluster` | Amazon EKS 集群的名称。 | 带有基本分隔符的字母数字字符串。 | `FlyingSquad` | 
| `K8s.Cluster` | 自托管式 Kubernetes 集群的名称。 | 带有基本分隔符的字母数字字符串。 | `minicube` | 
| `K8s.Namespace` | Amazon EKS 或 K8s 集群中 Kubernetes 命名空间的名称。 | 带有基本分隔符的字母数字字符串。 | `default`, `pet-clinic` | 
| `K8s.Workload` | Amazon EKS 和 K8s 集群中的 Kubernetes 工作负载的名称。 | 带有基本分隔符的字母数字字符串。 | `frontend` | 
| `K8s.Node` | Amazon EKS 和 K8s 集群中 Kubernetes 节点的身份。 | K8s 节点名称（例如，Amazon EC2 实例 DNS 名称）。 | `ip-11-22-33-44.ec2.internal` | 
| `K8s.Pod` | Amazon EKS 和 K8s 集群中 Kubernetes 容器组（pod）的身份。 | K8s 容器组（pod）标识符。 | `frontend-1234abcd56-ef7890` | 
| `EC2.AutoScalingGroup` | Amazon EC2 AutoScaling 组的名称。 | 带有基本分隔符的字母数字字符串。 | `my-asg-name-1` | 
| `EC2.InstanceId` | Amazon EC2 实例的身份。 | Amazon EC2 实例标识符。 | `i-1234abcd5678ef90` | 
| `ECS.Cluster` | Amazon ECS 集群的身份。 | Amazon ECS 集群。 | `MyCluster` | 
| `ECS.Service` | Amazon ECS 服务的身份。 | Amazon ECS 服务。 | `MyService` | 
| `ECS.Task` | Amazon ECS 任务的身份。 | Amazon ECS 任务 ID。 | `task-123abc` | 
| `Lambda.Function` | Lambda 函数的身份。 | Lambda 函数名称。 | `MyFunction` | 
| `Host` | 所有平台类型的主机名称。 | 子域格式。 | `ip-111-22-33-44.example.com` | 

**资源详细信息**


| Keyword | 用法 | 值的域 | 示例 | 
| --- | --- | --- | --- | 
| `AWS.Resource.ARN` | AWS 资源的 ARN。 | 带有基本分隔符的字母数字字符串。 | `arn:aws:dynamodb:us-east-1:123456789012:table/myDynamoDBTable` | 

**应用程序详细信息**


| Keyword | 用法 | 值的域 | 示例 | 
| --- | --- | --- | --- | 
| `AWS.Application` | 应用程序内部流的名称。 | 带有基本分隔符的字母数字字符串。 | `PetClinicApp` | 
| `AWS.Application.ARN` | AppRegistry 中应用程序的 ARN。 | 带有基本分隔符的字母数字字符串。 | `arn:aws:servicecatalog:us-east-1:1234567890:/applications/...` | 

**遥测提供商详细信息**


| Keyword | 用法 | 值的域 | 示例 | 
| --- | --- | --- | --- | 
| `Telemetry.SDK` | 用于检测服务的 OTEL SDK 版本的指纹。 | 带有基本分隔符的字母数字字符串。 | `opentelemetry,1.32.0-aws-SNAPSHOT,java,Auto` | 
| `Telemetry.Agent` | 用于收集和发送遥测的代理的指纹。 | 带有基本分隔符的字母数字字符串。 | `CWAgent/1.300026.3, ADOTCollector/1.x` | 
| `Telemetry.Source` | 指定收集遥测的应用程序点或用于遥测数据源的内容。 | ServerSpan、ClientSpan、ProducerSpan、ConsumerSpan、LocalRoot Span、JMX、OS。 | `ClientSpan, JMX` |