> ## Documentation Index > Fetch the complete documentation index at: https://otel.fyi/llms.txt > Use this file to discover all available pages before exploring further. # Awsemf > OpenTelemetry exporter for Awsemf # Awsemf Exporter ![Status](https://img.shields.io/badge/status-beta-yellow) **Available in:** `contrib` **Maintainers:** [@Aneurysm9](https://github.com/Aneurysm9), [@mxiamxia](https://github.com/mxiamxia) **Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/awsemfexporter) ## Supported Telemetry ![Metrics](https://img.shields.io/badge/metrics-beta-green) ## Overview This exporter converts OpenTelemetry metrics to [AWS CloudWatch Embedded Metric Format(EMF)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html) and then sends them directly to CloudWatch Logs using the [PutLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) API. ## Data Conversion Convert OpenTelemetry `Int64DataPoints`, `DoubleDataPoints`, `SummaryDataPoints` metrics datapoints into CloudWatch `EMF` structured log formats and send it to CloudWatch. Logs and Metrics will be displayed in CloudWatch console. NaN, Inf values are not supported by CloudWatch EMF and will be dropped by the exporter. ## Exporter Configuration The following exporter configuration parameters are supported. | Name | Description | Default | | :------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `log_group_name` | Customized log group name which supports `{ClusterName}` and `{TaskId}` placeholders. One valid example is `/aws/metrics/{ClusterName}`. It will search for `ClusterName` (or `aws.ecs.cluster.name`) resource attribute in the metrics data and replace with the actual cluster name. If none of them are found in the resource attribute map, `{ClusterName}` will be replaced by `undefined`. Similar way, for the `{TaskId}`, it searches for `TaskId` (or `aws.ecs.task.id`) key in the resource attribute map. For `{NodeName}`, it searches for `NodeName` (or `k8s.node.name`) | "/metrics/default" | | `log_stream_name` | Customized log stream name which supports `{TaskId}`, `{ClusterName}`, `{NodeName}`, `{ContainerInstanceId}`, and `{TaskDefinitionFamily}` placeholders. One valid example is `{TaskId}`. It will search for `TaskId` (or `aws.ecs.task.id`) resource attribute in the metrics data and replace with the actual task id. If none of them are found in the resource attribute map, `{TaskId}` will be replaced by `undefined`. Similarly, for the `{TaskDefinitionFamily}`, it searches for `TaskDefinitionFamily` (or `aws.ecs.task.family`). For the `{ClusterName}`, it searches for `ClusterName` (or `aws.ecs.cluster.name`). For `{NodeName}`, it searches for `NodeName` (or `k8s.node.name`). For `{ContainerInstanceId}`, it searches for `ContainerInstanceId` (or `aws.ecs.container.instance.id`). (Note: ContainerInstanceId (or `aws.ecs.container.instance.id`) only works for AWS ECS EC2 launch type. | "otel-stream" | | `log_retention` | LogRetention is the option to set the log retention policy for only newly created CloudWatch Log Groups. Defaults to Never Expire if not specified or set to 0. Possible 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. | "Never Expire" | | `tags` | Tags is the option to set tags for the CloudWatch Log Group. If specified, please add at most 50 tags. Input is a string to string map like so: \{ 'key': 'value' }. Keys must be between 1-128 characters and follow the regex pattern: `^([\p{L}\p{Z}\p{N}_.:/=+\-@]+)$`(alphanumerics, whitespace, and \_.:/=+-!). Values must be between 1-256 characters and follow the regex pattern: `^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$`(alphanumerics, whitespace, and \_.:/=+-!). [Link to tagging restrictions](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLogGroup.html#:~:text=Required%3A%20Yes-,tags,-The%20key%2Dvalue) | No tags set | | `namespace` | Customized CloudWatch metrics namespace | "default" | | `endpoint` | Optionally override the default CloudWatch service endpoint. | | | `no_verify_ssl` | Enable or disable TLS certificate verification. | false | | `proxy_address` | Upload Structured Logs to AWS CloudWatch through a proxy. | | | `region` | Send Structured Logs to AWS CloudWatch in a specific region. If this field is not present in config, environment variable "AWS\_REGION" can then be used to set region. | determined by metadata | | `role_arn` | IAM role to upload segments to a different account. | | | `external_id` | Shared identitier used when assuming an IAM role in an external AWS account. | | | `max_retries` | Maximum number of retries before abandoning an attempt to post data. | 1 | | `dimension_rollup_option` | DimensionRollupOption is the option for metrics dimension rollup. Three options are available: `NoDimensionRollup`, `SingleDimensionRollupOnly` and `ZeroAndSingleDimensionRollup`. The default value is `ZeroAndSingleDimensionRollup`. Enabling feature gate `awsemf.nodimrollupdefault` will set default to `NoDimensionRollup`. | "ZeroAndSingleDimensionRollup" (Enable both zero dimension rollup and single dimension rollup) | | `resource_to_telemetry_conversion` | "resource\_to\_telemetry\_conversion" is the option for converting resource attributes to telemetry attributes. It has only one config option- `enabled`. For metrics, if `enabled=true`, all the resource attributes will be converted to metric labels by default. See `Resource Attributes to Metric Labels` section below for examples. | `enabled=false` | | `output_destination` | "output\_destination" is an option to specify the EMFExporter output. Currently, two options are available. "cloudwatch" or "stdout" | `cloudwatch` | | `detailed_metrics` | Retain detailed datapoint values in exported metrics (e.g instead of exporting a quantile as a statistical value, preserve the quantile's population) | `false` | | `parse_json_encoded_attr_values` | List of attribute keys whose corresponding values are JSON-encoded strings and will be converted to JSON structures in emf logs. For example, the attribute string value "\{\\"x\\":5,\\"y\\":6}" will be converted to a json object: `{"x": 5, "y": 6}` | \[ ] | | [`metric_declarations`](#metric_declaration) | List of rules for filtering exported metrics and their dimensions. | \[ ] | | [`metric_descriptors`](#metric_descriptor) | List of rules for inserting or updating metric descriptors. | \[ ] | | `retain_initial_value_of_delta_metric` | This option specifies how the first value of a metric is handled. AWS EMF expects metric values to only contain deltas to the previous value. In the default case the first received value is therefor not sent to AWS but only used as a baseline for follow up changes to this metric. This is fine for high throughput metrics with stable labels (e.g. `requests{code=200}`). In this case it does not matter if the first value of this metric is discarded. However when your metric describes infrequent events or events with high label cardinality, then the exporter in default configuration would still drop the first occurrence of this metric. With this configuration value set to `true` the first value of all metrics will instead be send to AWS. | false | ### metric\_declaration A metric\_declaration section characterizes a rule to be used to set dimensions for exported metrics, filtered by the incoming metrics' labels and metric names. | Name | Description | Default | | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `dimensions` | List of dimension sets to be exported. Dimension sets that include dimensions that are not labels are ignored. Use empty dimension set `[]` for metrics without labels. | \[\[ ]] | | `metric_name_selectors` | List of regex strings to filter metric names by. | | | [`label_matchers`](#label_matcher) | (Optional) list of label matching rules to filter metrics by their labels. This rule is applied to any metric that matches any of the label matchers. | \[ ] | #### label\_matcher A label\_matcher section defines a matching rule against the labels of the incoming metric. Only metrics that match the rules will be used by the surrounding `metric_declaration`. | Name | Description | Default | | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `label_names` | List of label names to filter by. Their corresponding values are concatenated using the separator and matched against the configured regular expression. | | | `separator` | (Optional) separator placed between concatenated label values. | ";" | | `regex` | Regex string to be matched against concatenated label values. | | ### metric\_descriptor A metric descriptor section allows the schema of a metric to be overwritten before sending out to the CloudWatch backend service. Currently, we only support unit override. | Name | Description | Default | | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `metric_name` | The name of the metric to be overwritten. | | | `unit` | The overwritten value of unit. The [MetricDatum](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html) contains a full list of supported unit values. | | | `overwrite` | `true` if the schema should be overwritten with the given specification, otherwise it will only be configured if empty. | false | ## AWS Credential Configuration This exporter follows default credential resolution for the [aws-sdk-go](https://docs.aws.amazon.com/sdk-for-go/api/index.html). Follow the [guidelines](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html) for the credential configuration. ## Metric Attributes By setting attributes on your metrics you can change how individual metrics are sent to CloudWatch. Attributes can be set in code or using components like the [Attribute Processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/attributesprocessor). The AWS EMF Exporter will interpret the following metric attributes to change how it publishes metrics to CloudWatch: | Attribute Name | Description | Default | | :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | `aws.emf.storage_resolution` | This attribute should be set to an integer value of `1` or `60`. When sending the metric value to CloudWatch use the specified storage resolution value. CloudWatch currently supports a storage resolution of `1` or `60` to indicate 1 second or 60 second resolution. | `aws.emf.storage_resolution = 60` | ## Configuration Examples ### Resource Attributes to Metric Labels `resource_to_telemetry_conversion` option can be enabled to convert all the resource attributes to metric labels. By default, this option is disabled. Users need to set `enabled=true` to opt-in. See the config example below. ```yaml theme={null} exporters: awsemf: region: 'us-west-2' resource_to_telemetry_conversion: enabled: true ``` ### Metric Declaration The following is an example of how to use `metric_declaration` to select what metrics should be exported. ```yaml theme={null} exporters: awsemf: region: 'us-west-2' output_destination: stdout dimension_rollup_option: "NoDimensionRollup" metric_declarations: - dimensions: [[]] metric_name_selectors: # Metric without label - "^node_load15$" - dimensions: [[device, fstype], []] metric_name_selectors: - "^node_filesystem_readonly$" ``` ## Configuration ### Example Configuration ```yaml theme={null} awsemf: awsemf/1: region: 'us-west-2' role_arn: "arn:aws:iam::123456789:role/monitoring-EKS-NodeInstanceRole" detailed_metrics: false version: "1" awsemf/resource_attr_to_label: resource_to_telemetry_conversion: enabled: true awsemf/metric_descriptors: metric_descriptors: - metric_name: memcached_current_items unit: Count overwrite: true ``` *** *Last generated: 2026-07-06*