Merge pull request #88479 from max-cx/OBSDOCS-1617

OBSDOCS-1617,OBSDOCS-1615,OBSDOCS-1616: Docs for TP features: AWS CloudWatch Exporter, AWS EMF Exporter, AWS X-Ray Exporter

Author: skopacz1

observability/otel/otel-collector/otel-collector-exporters.adoc

@@ -17,6 +17,9 @@ Currently, the following General Availability and Technology Preview exporters a
 - xref:../../../observability/otel/otel-collector/otel-collector-exporters.adoc#prometheus-exporter_otel-collector-exporters[Prometheus Exporter]
 - xref:../../../observability/otel/otel-collector/otel-collector-exporters.adoc#prometheus-remote-write-exporter_otel-collector-exporters[Prometheus Remote Write Exporter]
 - xref:../../../observability/otel/otel-collector/otel-collector-exporters.adoc#kafka-exporter_otel-collector-exporters[Kafka Exporter]
+- xref:../../../observability/otel/otel-collector/otel-collector-exporters.adoc#aws-cloudwatch-exporter_otel-collector-exporters[AWS CloudWatch Exporter]
+- xref:../../../observability/otel/otel-collector/otel-collector-exporters.adoc#aws-emf-exporter_otel-collector-exporters[AWS EMF Exporter]
+- xref:../../../observability/otel/otel-collector/otel-collector-exporters.adoc#aws-xray-exporter_otel-collector-exporters[AWS X-Ray Exporter]
 
 [id="otlp-exporter_{context}"]
 == OTLP Exporter
@@ -290,6 +293,160 @@ include::snippets/technology-preview.adoc[]
 <6> Disables verifying the server's certificate chain and host name. The default is `+false+`.
 <7> ServerName indicates the name of the server requested by the client to support virtual hosting.
 
+[id="aws-cloudwatch-exporter_{context}"]
+== AWS CloudWatch Logs Exporter
+
+The AWS CloudWatch Logs Exporter sends logs data to the Amazon CloudWatch Logs service and signs requests by using the AWS SDK for Go and the default credential provider chain.
+
+:FeatureName: The AWS CloudWatch Logs Exporter
+include::snippets/technology-preview.adoc[]
+
+.OpenTelemetry Collector custom resource with the enabled AWS CloudWatch Logs Exporter
+[source,yaml]
+----
+# ...
+  config:
+    exporters:
+      awscloudwatchlogs:
+        log_group_name: "<group_name_of_amazon_cloudwatch_logs>" # <1>
+        log_stream_name: "<log_stream_of_amazon_cloudwatch_logs>" # <2>
+        region: <aws_region_of_log_stream> # <3>
+        endpoint: <service_endpoint_of_amazon_cloudwatch_logs> # <4>
+        log_retention: <supported_value_in_days> # <5>
+# ...
+----
+<1> Required. If the log group does not exist yet, it is automatically created.
+<2> Required. If the log stream does not exist yet, it is automatically created.
+<3> Optional. If the AWS region is not already set in the default credential chain, you must specify it.
+<4> Optional. You can override the default Amazon CloudWatch Logs service endpoint to which the requests are forwarded. For the list of service endpoints by region, see link:https://docs.aws.amazon.com/general/latest/gr/cwl_region.html[Amazon CloudWatch Logs endpoints and quotas] (AWS General Reference).
+<5> Optional. With this parameter, you can set the log retention policy for new Amazon CloudWatch log groups. If this parameter is omitted or set to `0`, the logs never expire by default. Supported values for retention in days are `1`, `3`, `5`, `7`, `14`, `30`, `60`, `90`, `120`, `150`, `180`, `365`, `400`, `545`, `731`, `1827`, `2192`, `2557`, `2922`, `3288`, or `3653`.
+
+[role="_additional-resources"]
+.Additional resources
+* link:https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html[What is Amazon CloudWatch Logs?] (Amazon CloudWatch Logs User Guide)
+* link:https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials[Specifying Credentials] (AWS SDK for Go Developer Guide)
+// * link:https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-auth.html[Configure Authentication] (AWS SDK for Go v2 Developer Guide)
+* link:https://docs.aws.amazon.com/general/latest/gr/cwl_region.html[Amazon CloudWatch Logs endpoints and quotas] (AWS General Reference)
+
+[id="aws-emf-exporter_{context}"]
+== AWS EMF Exporter
+
+The AWS EMF Exporter converts the following OpenTelemetry metrics datapoints to the AWS CloudWatch Embedded Metric Format (EMF):
+
+- `Int64DataPoints`
+- `DoubleDataPoints`
+- `SummaryDataPoints`
+
+The EMF metrics are then sent directly to the Amazon CloudWatch Logs service by using the `PutLogEvents` API.
+
+One of the benefits of using this exporter is the possibility to view logs and metrics in the Amazon CloudWatch console at link:https://console.aws.amazon.com/cloudwatch/[].
+
+:FeatureName: The AWS EMF Exporter
+include::snippets/technology-preview.adoc[]
+
+.OpenTelemetry Collector custom resource with the enabled AWS EMF Exporter
+[source,yaml]
+----
+# ...
+  config:
+    exporters:
+      awsemf:
+        log_group_name: "<group_name_of_amazon_cloudwatch_logs>" # <1>
+        log_stream_name: "<log_stream_of_amazon_cloudwatch_logs>" # <2>
+        resource_to_telemetry_conversion: # <3>
+          enabled: true
+        region: <region> # <4>
+        endpoint: <endpoint> # <5>
+        log_retention: <supported_value_in_days> # <6>
+        namespace: <custom_namespace> # <7>
+# ...
+----
+<1> Customized log group name.
+<2> Customized log stream name.
+<3> Optional. Converts resource attributes to telemetry attributes such as metric labels. Disabled by default.
+<4> The AWS region of the log stream. If a region is not already set in the default credential provider chain, you must specify the region.
+<5> Optional. You can override the default Amazon CloudWatch Logs service endpoint to which the requests are forwarded. For the list of service endpoints by region, see link:https://docs.aws.amazon.com/general/latest/gr/cwl_region.html[Amazon CloudWatch Logs endpoints and quotas] (AWS General Reference).
+<6> Optional. With this parameter, you can set the log retention policy for new Amazon CloudWatch log groups. If this parameter is omitted or set to `0`, the logs never expire by default. Supported values for retention in days are `1`, `3`, `5`, `7`, `14`, `30`, `60`, `90`, `120`, `150`, `180`, `365`, `400`, `545`, `731`, `1827`, `2192`, `2557`, `2922`, `3288`, or `3653`.
+<7> Optional. A custom namespace for the Amazon CloudWatch metrics.
+
+[discrete]
+[id="log-group-name_{context}"]
+=== Log group name
+
+The `log_group_name` parameter allows you to customize the log group name and supports the default `+/metrics/default+` value or the following placeholders:
+
+`+/aws/metrics/{ClusterName}+`:: This placeholder is used to search for the `ClusterName` or `+aws.ecs.cluster.name+` resource attribute in the metrics data and replace it with the actual cluster name.
+
+`+{NodeName}+`:: This placeholder is used to search for the `NodeName` or `+k8s.node.name+` resource attribute.
+
+`+{TaskId}+`:: This placeholder is used to search for the `TaskId` or `+aws.ecs.task.id+` resource attribute.
+
+If no resource attribute is found in the resource attribute map, the placeholder is replaced by the `undefined` value.
+
+[discrete]
+[id="log-stream-name_{context}"]
+=== Log stream name
+
+The `log_stream_name` parameter allows you to customize the log stream name and supports the default `+otel-stream+` value or the following placeholders:
+
+`+{ClusterName}+`:: This placeholder is used to search for the `+ClusterName+` or `+aws.ecs.cluster.name+` resource attribute.
+
+`+{ContainerInstanceId}+`:: This placeholder is used to search for the `+ContainerInstanceId+` or `+aws.ecs.container.instance.id+` resource attribute. This resource attribute is valid only for the AWS ECS EC2 launch type.
+
+`+{NodeName}+`:: This placeholder is used to search for the `+NodeName+` or `+k8s.node.name+` resource attribute.
+
+`+{TaskDefinitionFamily}+`:: This placeholder is used to search for the `+TaskDefinitionFamily+` or `+aws.ecs.task.family+` resource attribute.
+
+`+{TaskId}+`:: This placeholder is used to search for the `TaskId` or `+aws.ecs.task.id+` resource attribute in the metrics data and replace it with the actual task ID.
+
+If no resource attribute is found in the resource attribute map, the placeholder is replaced by the `undefined` value.
+
+[role="_additional-resources"]
+.Additional resources
+* link:https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html[Specification: Embedded metric format] (Amazon CloudWatch User Guide)
+* link:https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html[PutLogEvents] (Amazon CloudWatch Logs API Reference)
+* link:https://docs.aws.amazon.com/general/latest/gr/cwl_region.html[Amazon CloudWatch Logs endpoints and quotas] (AWS General Reference)
+
+[id="aws-xray-exporter_{context}"]
+== AWS X-Ray Exporter
+
+The AWS X-Ray Exporter converts OpenTelemetry spans to AWS X-Ray Segment Documents and then sends them directly to the AWS X-Ray service. The AWS X-Ray Exporter uses the `PutTraceSegments` API and signs requests by using the AWS SDK for Go and the default credential provider chain.
+
+:FeatureName: The AWS X-Ray Exporter
+include::snippets/technology-preview.adoc[]
+
+.OpenTelemetry Collector custom resource with the enabled AWS X-Ray Exporter
+[source,yaml]
+----
+# ...
+  config:
+    exporters:
+      awsxray:
+        region: "<region>" # <1>
+        endpoint: <endpoint> # <2>
+        resource_arn: "<aws_resource_arn>" # <3>
+        role_arn: "<iam_role>" # <4>
+        indexed_attributes: [ "<indexed_attr_0>", "<indexed_attr_1>" ] # <5>
+        aws_log_groups: ["<group1>", "<group2>"] # <6>
+        request_timeout_seconds: 120 # <7>
+# ...
+----
+<1> The destination region for the X-Ray segments sent to the AWS X-Ray service. For example, `eu-west-1`.
+<2> Optional. You can override the default Amazon CloudWatch Logs service endpoint to which the requests are forwarded. For the list of service endpoints by region, see link:https://docs.aws.amazon.com/general/latest/gr/cwl_region.html[Amazon CloudWatch Logs endpoints and quotas] (AWS General Reference).
+<3> The Amazon Resource Name (ARN) of the AWS resource that is running the Collector.
+<4> The AWS Identity and Access Management (IAM) role for uploading the X-Ray segments to a different account.
+<5> The list of attribute names to be converted to X-Ray annotations.
+<6> The list of log group names for Amazon CloudWatch Logs.
+<7> Time duration in seconds before timing out a request. If omitted, the default value is `30`.
+
+[role="_additional-resources"]
+.Additional resources
+* link:https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html[What is AWS X-Ray?] (AWS X-Ray Developer Guide)
+* link:https://docs.aws.amazon.com/sdk-for-go/api/index.html[AWS SDK for Go API Reference] (AWS Documentation)
+* link:https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials[Specifying Credentials] (AWS SDK for Go Developer Guide)
+// * link:https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-auth.html[Configure Authentication] (AWS SDK for Go v2 Developer Guide)
+* link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html[IAM roles] (AWS Identity and Access Management User Guide)
+
 [role="_additional-resources"]
 [id="additional-resources_otel-collector-exporters_{context}"]
 == Additional resources