# 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 時間以内にテレメトリが送信されたエンティティの関連リソースのみを検索できます。リソースのテレメトリ発信頻度が低い (3 時間に 1 回未満) 場合、追加の*ハートビート*テレメトリを送信し、CloudWatch 内でエンティティをアクティブにしておくことができます。

エンティティ情報を追加する方法については、「[EMF 形式のエンティティ情報](CloudWatch_Embedded_Metric_Format_Specification.md#entity-information-emf-format)」を参照してください。

CloudWatch がテレメトリに関連付けられたリソースおよびサービスを識別できるように、次のセクションでは `KeyAttributes` および `Attributes` を作成する方法について説明します。

## 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` が表すことができるオブジェクトには、5 つのタイプがあります。
+ **AWS::Resource** – エンティティは、DynamoDB テーブルや Amazon EC2 インスタンスなどの AWS リソースを表します。
+ **AWS::Service** – エンティティは Amazon S3 などの AWS サービスを表します。例えば、特定の Amazon S3 リソースに関連付けられていない `ListBuckets` オペレーションを呼び出すときに使用される場合があります。
+ **サービス** – エンティティは、アカウントで実行されているワークロードを表します。例えば、管理するアプリケーションまたはサービスなどです。
+ **リソース** – エンティティは、AWS によって管理されていないリソースを表します (例えば、プロセスやファイルボリュームなどのオペレーティングシステムリソースなど)。
+ **RemoteService** – エンティティは、リモート呼び出しの外部サービスを表します。例えば、データベース、外部キャッシュ、外部エンドポイントへのリモート呼び出しなど。

上記のタイプのうち、表しているタイプによっては、`KeyAttributes` に正しいキーと値のペアを指定する必要があります。次の内容は、各タイプについて説明します。

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

AWS リソースを指定するには、次の 3 つのキーと値のペアを含める必要があります。
+ `"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 サービスを指定するには、次の 2 つのキーと値のペアを含める必要があります。
+ `"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 によって運用されていないサービスを指定するには、次の 3 つのキーと値のペアを含める必要があります。
+ `"Type": "Service"` – このキーと値のペアは、エンティティをサービスとして識別します。
+ `"Name": "<service-name>"` – メトリクスを送信しているサービスの名前を表します。例えば、`my-service-frontend`、`api.myservice.com` です。
+ `"Environment": "<environment-name>"` – この属性はサービスがホストされている場所、あるいはサービスが属する環境を指定します。例えば、`us-west-2` または `myservice.production` など。

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

AWS によって提供されていないリソースを指定するには、次の 3 つのキーと値のペアを含める必要があります。
+ `"Type": "Resource"` – このキーと値のペアは、エンティティをリソースとして識別します。
+ `"ResourceType": "<resource-type>"` – リソースのタイプを指定する文字列。例えば、Kubernetes ポッドの `K8s::Pod`。
+ `"Identifier": "<resource-id>"` - リソースの文字列識別子。複数の名前を含めて、パイプ文字で区切ることができます。例えば、Kubernetes ポッドは、クラスター名、名前空間、ポッド名 (`MyCluster|MyNamespace|MyPod` など) で表される場合があります。

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

リモートサービスを指定するには、次の 2 つのキーと値のペアを含める必要があります。
+ `"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` と呼ばれます。ここでは、同じプロパティとして扱われます。

**プラットフォームの詳細**


| キーワード | 使用方法 | 値のドメイン | 例 | 
| --- | --- | --- | --- | 
| `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 ノードの ID。 | K8s ノード名 (例えば、Amazon EC2 インスタンスの DNS 名など)。 | `ip-11-22-33-44.ec2.internal` | 
| `K8s.Pod` | Amazon EKS および K8s クラスターの Kubernetes ポッドの ID。 | K8s ポッド識別子。 | `frontend-1234abcd56-ef7890` | 
| `EC2.AutoScalingGroup` | Amazon EC2 AutoScaling グループの名前。 | 基本的な区切り文字を含む英数字の文字列。 | `my-asg-name-1` | 
| `EC2.InstanceId` | Amazon EC2 インスタンスの ID。 | Amazon EC2 インスタンス識別子。 | `i-1234abcd5678ef90` | 
| `ECS.Cluster` | Amazon ECS クラスターの ID。 | Amazon ECS クラスター名。 | `MyCluster` | 
| `ECS.Service` | Amazon ECS サービスの ID。 | Amazon ECS サービス名。 | `MyService` | 
| `ECS.Task` | Amazon ECS タスクの ID。 | Amazon ECS タスク ID。 | `task-123abc` | 
| `Lambda.Function` | Lambda 関数の ID。 | Lambda 関数の名前。 | `MyFunction` | 
| `Host` | すべてのプラットフォームタイプにおけるホストの名前。 | サブドメイン形式。 | `ip-111-22-33-44.example.com` | 

**リソースの詳細**


| キーワード | 使用方法 | 値のドメイン | 例 | 
| --- | --- | --- | --- | 
| `AWS.Resource.ARN` | AWS リソースの ARN。 | 基本的な区切り文字を含む英数字の文字列。 | `arn:aws:dynamodb:us-east-1:123456789012:table/myDynamoDBTable` | 

**アプリケーションの詳細**


| キーワード | 使用方法 | 値のドメイン | 例 | 
| --- | --- | --- | --- | 
| `AWS.Application` | AppRegistry のアプリケーションの名前。 | 基本的な区切り文字を含む英数字の文字列。 | `PetClinicApp` | 
| `AWS.Application.ARN` | AppRegistry のアプリケーションの ARN。 | 基本的な区切り文字を含む英数字の文字列。 | `arn:aws:servicecatalog:us-east-1:1234567890:/applications/...` | 

**テレメトリプロバイダーの詳細**


| キーワード | 使用方法 | 値のドメイン | 例 | 
| --- | --- | --- | --- | 
| `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` |