Awsemf Exporter

Available in: contrib Maintainers: @Aneurysm9, @mxiamxia Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

This exporter converts OpenTelemetry metrics to AWS CloudWatch Embedded Metric Format(EMF) and then sends them directly to CloudWatch Logs using the PutLogEvents 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	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`	List of rules for filtering exported metrics and their dimensions.	[ ]
`metric_descriptors`	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`	(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 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. Follow the guidelines 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. 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

The resource_to_telemetry_conversion option can be used to convert resource attributes to metric labels. By default, this option is disabled. You can specify included and excluded wildcard pattern lists to match attribute keys. Legacy options enabled and exclude_service_attributes are deprecated (and can be disabled via the exporter.awsemf.DisableLegacyResourceToTelemetryConversion feature gate). When migrating from enabled: true, the equivalent configuration is setting included: ["*"]. See the config example below:

exporters:
    awsemf:
        region: 'us-west-2'
        resource_to_telemetry_conversion:
            included:
                - "*"

Metric Declaration

The following is an example of how to use metric_declaration to select what metrics should be exported.

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

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-10-05

​Awsemf Exporter

​Supported Telemetry

​Overview

​Data Conversion

​Exporter Configuration

​metric_declaration

​label_matcher

​metric_descriptor

​AWS Credential Configuration

​Metric Attributes

​Configuration Examples

​Resource Attributes to Metric Labels

​Metric Declaration

​Configuration

​Example Configuration