Mapping Canonical Cloud Resources ID to OpenTelemetry resource attributes

content/en/opentelemetry/mapping/host_metadata.md

@@ -90,6 +90,65 @@
 
 **Note:** You need to add these processors and receivers in the Collector running on the host that you want to monitor. A gateway host does not collect this information from remote hosts.
 
+
+## Canonical cloud resource IDs
+
+Canonical cloud resource IDs (CCRIDs) are cloud provider-assigned resource IDs that uniquely identify a cloud resource. After adding CCRIDs across your different observability types, you can use them to consistently link different types of data for a given cloud resource. You can add CCRIDs in the same format across all cloud resource types. Widespread addition and adoption of CCRIDs gives you access to a variety of use cases across customers and internal teams.
+
+Enable CCRIDs to jump between resources and their associated metrics, traces, and logs for all resource types, eliminating context switching and giving you an end-to-end view of your resources within the same workflow.
+
+To use this feature, set the `datadog.ccrid` resource attribute to the value of the CCRID in all OTLP payloads.
+
+See below for the list of identifier formats per-cloud:
+| Cloud   | Identifier Type    | Example                                                                                                                                      |
+|---------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
+| AWS     | ARN                | `arn:aws:sns:us-east-1:123456789012:instance/example-sns-topic-name`                                                                                  |
+| Azure   | Resource ID        | `/subscriptions/0b62a232-b8db-4380-9da6-640f7272ed6d/resourcegroups/lfotriggertest/providers/microsoft.web/sites/resources-task-19cb7afdcbbc`|
+| GCP     | CAI Resource Name  | `//file.googleapis.com/projects/datadog-sandbox/locations/us-central1/backups/kevin-test-backup`                                             |
+| OCI     | OCID               | `ocid1.bucket.oc1.eu-frankfurt-1.aaaaaaaa5b5d7phlob22x4xin2lopq33ugriqiglek2ecxecrjx2awceb7eq`                                               |
+
+How to form a CCRID:
+ * [AWS (EC2 Instance)][13]: `arn:aws:ec2:{region}:{accountId}:instance/{instanceId}`. 
+    Use this command to retrieve the `instanceId`:
+    ```shell
+    ec2metadata --instance-id
+    ```
+ * [Azure][11]: `/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}`
+ * GCP: `//compute.googleapis.com/projects/{projectID}/zones/{zoneName}/instances/{instanceName}"`
+ * OCI/Oracle: The CCRID can be obtained by [sending a request][12] at: `http://169.254.169.254/opc/v2/instance/id`
+
+
+For example, to set an AWS CCRID for all resources in metrics, traces, and logs, use the [transform processor][2] with the following configuration:
+```yaml
+processors:
+  transform:
+    metric_statements:
+      - context: resource
+        statements:
+          - set(attributes["datadog.ccrid"], "arn:aws:sns:us-east-1:123456789012:instance/example-sns-topic-name")
+    trace_statements:
+      - context: resource
+        statements:
+          - set(attributes["datadog.ccrid"], "arn:aws:sns:us-east-1:123456789012:instance/example-sns-topic-name")
+    log_statements:
+      - context: resource
+        statements:
+          - set(attributes["datadog.ccrid"], "arn:aws:sns:us-east-1:123456789012:instance/example-sns-topic-name")
+```
+
+The OpenTelemetry semantic conventions also define the [cloud.resource_id][14] attribute, which can be mapped in the configuration using the [attributes processor][15].
+
+Example: 
+```yaml
+processors:
+  attributes/example:
+    actions:
+      - key: datadog.ccrid
+        from_attribute: cloud.resource_id
+        action: upsert
+```
+
+
 ## Further reading
 
 {{< partial name="whats-next/whats-next.html" >}}
@@ -104,3 +163,8 @@
 [8]: https://opentelemetry.io/docs/specs/semconv/resource/os/
 [9]: https://opentelemetry.io/docs/collector/deployment/
 [10]: /opentelemetry/schema_semantics/hostname/
+[11]: https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/move-resource-group-and-subscription?tabs=azure-cli
+[12]: https://docs.oracle.com/en-us/iaas/Content/Compute/Tasks/gettingmetadata.htm
+[13]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-policies-for-amazon-ec2.html#policy-syntax
+[14]: https://opentelemetry.io/docs/specs/semconv/registry/attributes/cloud/#cloud-resource-id
+[15]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/attributesprocessor