From e94937881b5f7e9edf30481594e0e5c391b90d90 Mon Sep 17 00:00:00 2001 From: Pavol Loffay Date: Thu, 6 Feb 2025 17:56:12 +0100 Subject: [PATCH] OBSDOCS-1617,OBSDOCS-1615,OBSDOCS-1616: Docs for TP features: AWS CloudWatch Exporter, AWS EMF Exporter, AWS X-Ray Exporter --- .../otel-collector-exporters.adoc | 157 ++++++++++++++++++ 1 file changed, 157 insertions(+) diff --git a/observability/otel/otel-collector/otel-collector-exporters.adoc b/observability/otel/otel-collector/otel-collector-exporters.adoc index 76bd455151..2c1c5cc735 100644 --- a/observability/otel/otel-collector/otel-collector-exporters.adoc +++ b/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: "" # <1> + log_stream_name: "" # <2> + region: # <3> + endpoint: # <4> + log_retention: # <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: "" # <1> + log_stream_name: "" # <2> + resource_to_telemetry_conversion: # <3> + enabled: true + region: # <4> + endpoint: # <5> + log_retention: # <6> + 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: "" # <1> + endpoint: # <2> + resource_arn: "" # <3> + role_arn: "" # <4> + indexed_attributes: [ "", "" ] # <5> + aws_log_groups: ["", ""] # <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