ob-col/exporter/awsemfexporter

AWS CloudWatch EMF Exporter for OpenTelemetry Collector

Status
Stability	beta: metrics
Distributions	contrib, aws, observiq
Issues
Code Owners	@Aneurysm9, @shaochengwang, @mxiamxia, @bryan-aguilar

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 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.
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 onption- 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 ful 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.

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.

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.

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$"