本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 如何將相關資訊新增至傳送到 CloudWatch 的自訂遙測
<a name="adding-your-own-related-telemetry"></a>

當您將自己的指標和日誌發布至 CloudWatch 時，相關遙測所需的實體資訊預設並未包含在內。當您 (透過 [PutMetricData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html) 或 [PutLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) 操作) 將指標傳送至 CloudWatch 或者將日誌傳送至 CloudWatch Logs 時，可以將實體資訊新增至這些日誌或指標。實體資訊與遙測關聯，在「探索相關」功能中用於尋找與同一實體關聯的相關遙測。****

隨遙測傳送的實體代表該遙測關聯的資源或服務。例如，有關 服務或來自 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>

實體物件的 `KeyAttributes` 屬性 ([在 CloudWatch 中](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_Entity.html)或[在 CloudWatch Logs 中](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_Entity.html)) 可唯一識別 CloudWatch 的實體。其值為鍵/值對的清單。`KeyAttributes` 相同的實體被視為同一實體。與相同實體關聯的遙測被視為相關，可以在**探索相關**窗格中輕鬆找到。

**注意**  
在 CloudWatch API 中，屬性稱為 `KeyAttributes`。在 CloudWatch Logs API 中，屬性稱為 `keyAttributes`。在這裡，它們被視為同一項屬性。

`Entity` 可能代表五種物件類型。
+ **AWS：：Resource** – 實體代表 AWS 資源，例如 DynamoDB 資料表或 Amazon EC2 執行個體。
+ **AWS：：Service** – 實體代表 AWS 服務，例如 Amazon S3。例如，在呼叫 `ListBuckets` 操作時，可能會使用此功能，這與特定 Amazon S3 資源無關聯。
+ **Service**：實體代表在您的帳戶中執行的工作負載。例如，您管理的應用程式或服務。
+ **資源** – 實體代表不受作業系統資源管理的資源 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>"` – 資源的主要識別符。如需詳細資訊，請參閱《CloudFormation 延伸開發使用者指南》**中的 [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 [service name](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`。

------

## 透過屬性物件提供實體的額外詳細資訊
<a name="custom-related-telemetry-attributes"></a>

您可以提供有關隨遙測提供之 `Entity` 的其他詳細資訊。可以包含平台、資源、應用程式或遙測提供者的詳細資訊。下表說明您可用於每種資料類型的關鍵字。

**注意**  
在 CloudWatch API 中，屬性稱為 `Attributes`。在 CloudWatch Logs API 中，屬性稱為 `attributes`。在這裡，它們被視為同一項屬性。

**平台詳細資料**


| 關鍵字 | Usage | 值的網域 | 範例 | 
| --- | --- | --- | --- | 
| `PlatformType` | 定義託管平台。 | AWS::EKS、AWS::ECS、AWS::EC2、AWS::Lambda、K8s、Generic | `AWS::EC2` | 
| `EKS.Cluster` | Amazon MSK 叢集的名稱。 | 帶基本分隔符的英數字串。 | `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` | 

**資源詳細資訊**


| 關鍵字 | Usage | 值的網域 | 範例 | 
| --- | --- | --- | --- | 
| `AWS.Resource.ARN` |  AWS 資源的 ARN。 | 帶基本分隔符的英數字串。 | `arn:aws:dynamodb:us-east-1:123456789012:table/myDynamoDBTable` | 

**應用程式詳細資訊**


| 關鍵字 | Usage | 值的網域 | 範例 | 
| --- | --- | --- | --- | 
| `AWS.Application` | 應用程式在 AppRegistry 中的名稱。 | 帶基本分隔符的英數字串。 | `PetClinicApp` | 
| `AWS.Application.ARN` | 應用程式在 AppRegistry 中的 ARN。 | 帶基本分隔符的英數字串。 | `arn:aws:servicecatalog:us-east-1:1234567890:/applications/...` | 

**遙測提供者詳細資訊**


| 關鍵字 | Usage | 值的網域 | 範例 | 
| --- | --- | --- | --- | 
| `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` |