How to add related information to custom telemetry sent to CloudWatch (original) (raw)

When you publish your own metrics and logs to CloudWatch, the entity information needed for related telemetry is not there by default. When you send metrics to CloudWatch or logs to CloudWatch Logs (with the PutMetricData or PutLogEvents operations), you can add entity information to those logs or metrics. The entity information is associated with the telemetry, and used in theExplore related feature to find related telemetry that is associated with the same entity.

The entity sent with telemetry represents a resource or service that the telemetry is associated with. For example, a metric about a service, or that comes from an AWS resource. To identify the entity associated in your code, you create a set ofKeyAttributes and optional Attributes of the entity.

Note

CloudWatch can only find related resources for entities that have had telemetry sent within the previous three hours. If your resource only emits sparse telemetry (less than once every 3 hours), you may want to send additional heartbeat telemetry, to keep the entity active within CloudWatch.

For information on how to add entity information, see Entity information in EMF format.

The following sections describe how to create the KeyAttributes andAttributes so that CloudWatch can identify the resources and services associated with the telemetry.

The KeyAttributes property of the Entity objects ( in CloudWatch orin CloudWatch logs) uniquely identifies the entity for CloudWatch. It is a list of key-value pairs. Entities with the same KeyAttributes are considered to be the same entity. Telemetry associated with the same entity are considered related, and can be easily found in the Explore related pane.

Note

In the CloudWatch API, the property is called KeyAttributes. In the CloudWatch Logs API, the property is called keyAttributes. Here they are treated as the same property.

There are five possible types of object that an Entity can represent.

• AWS::Resource – The entity represents an AWS resource, such as a DynamoDB table or Amazon EC2 instance.
• AWS::Service – The entity represent an AWS service, such as Amazon S3. This might be used, for example, when calling the ListBuckets operation, which is not associated with a specific Amazon S3 resource.
• Service – The entity represents a workload running in your account. For example, an application or service that you manage.
• Resource – The entity represents a resource that is not managed by AWS, for example, operating system resources, such as processes or file volumes.
• RemoteService – The entity represents an external service in a remote call. For example, a remote call to a database, external cache, or an external endpoint.

Depending on which of the above types you are trying to represent, you must provide the correct key-value pairs for the KeyAttributes. The following describes each type.

AWS::Resource

To specify an AWS Resource, you must include the following three key value pairs:

• "Type": "AWS::Resource" – This key-value pair identifies the entity as an AWS resource.
• "ResourceType": "_<resource-type>_" – The string value of the ResourceType is the AWS CloudFormation resource type string. For example, AWS::DynamoDB::Table.
• "Identifier": "_<resource-id>_" – The primary identifier for the resource. For more information, see primaryIdentifier in the Extension Development for CloudFormation User Guide.

AWS::Service

To specify an AWS Service, you must include the following two key value pairs:

• "Type": "AWS::Service" – This key-value pair identifies the entity as an AWS service.
• "Name": "_<service-name>_" – The value of the Name is the AWS CloudFormationservice name string. For example, AWS::DynamoDB.

Service

To specify a service that is not operated by AWS, you must include the following three key value pairs:

• "Type": "Service" – This key-value pair identifies the entity as a service.
• "Name": "_<service-name>_" – This represents the name of the service that is sending the metrics. For example, my-service-frontend or api.myservice.com.
• "Environment": "_<environment-name>_" – This attribute specifies where the service is hosted, or the environment to which it belongs. For example us-west-2, or myservice.production.

Resource

To specify a resource that is not provided by AWS, you must include the following three key value pairs:

• "Type": "Resource" – This key-value pair identifies the entity as a resource.
• "ResourceType": "_<resource-type>_" – A string specifying the type of resource. For example, K8s::Pod for a Kubernetes Pod.
• "Identifier": "_<resource-id>_" – A string identifier for the resource. Can contain multiple names, separated by pipes. For example, a Kubernetes Pod might be represented by it's cluster name, namespace, and pod name, such as MyCluster|MyNamespace|MyPod.

RemoteService

To specify a remote service, you must include the following two key value pairs:

• "Type": "RemoteService" – This key-value pair identifies the entity as a remote service.
• "Name": "_<remote-service-name>_" – Specifies how the application refers to the external service in a remote call. For example, api.test.myservice.com.

You can provide additional details about the Entity that you provide with your telemetry. This can include details about the platform, resource, application, or telemetry provider. The following tables describes the key words that you can use for each of these types of data.

Note

In the CloudWatch API, the property is called Attributes. In the CloudWatch Logs API, the property is called attributes. Here they are treated as the same property.

Platform details

Resource details

Application details

Telemetry provider details