Skip to main content

​
Sum Connector

Status Available in: contrib Maintainers: @greatestusername, @shalper2, @crobert-1 Source: opentelemetry-collector-contrib

​
Overview

The sum connector can be used to sum attribute values from spans, span events, metrics, data points, and log records.

​
Configuration

If you are not already familiar with connectors, you may find it helpful to first visit the Connectors README.

​
Basic configuration

This example configuration will sum numerical values found within the attribute attribute.with.numerical.value of any span telemetry routed to the connector. It will then output a metric time series with the name my.example.metric.name with those summed values. Note: Values found within an attribute will be converted into a float regardless of their original type before being summed and output as a metric value. Non-convertible strings will be dropped and not included. 
receivers:
  foo:
connectors:
  sum:
    spans:
      my.example.metric.name:
        source_attribute: attribute.with.numerical.value
exporters:
  bar:

service:
  pipelines:
    metrics/sum:
       receivers: [sum]
       exporters: [bar]
    traces:
       receivers: [foo]
       exporters: [sum]

​
Required Settings

The sum connector has three required configuration settings and numerous optional settings
  • Telemetry type: Nested below the sum: connector declaration. Declared as spans: in the Basic Example.
    • Can be any of spans, spanevents, datapoints, or logs.
    • For metrics use datapoints
    • For traces use spans or spanevents
  • Metric name: Nested below the telemetry type; this is the metric name the sum connector will output summed values to. Declared as my.example.metric.name in the Basic Example
  • source_attribute: A specific attribute to search for within the source telemetry being fed to the connector. This attribute is where the connector will look for numerical values to sum into the output metric value. Declared as attribute.with.numerical.value in the Basic Example

​
Optional Settings

  • conditions: OTTL syntax can be used to provide conditions for processing incoming telemetry. Conditions are ORed together, so if any condition is met the attribute’s value will be included in the resulting sum.
  • attributes: Declaration of attributes to include. Any of these attributes found will generate a separate sum for each set of unique combination of attribute values and output as its own datapoint in the metric time series.
    • key: (required for attributes) the attribute name to match against
    • default_value: (optional for attributes) a default value for the attribute when no matches are found. The default_value value can be of type string, integer, or float.

​
Detailed Example Configuration

This example declares that the sum connector is going to be ingesting logs and creating an output metric named checkout.total with numerical values found in the source_attribute total.payment. It provides a condition to check that the attribute total.payment is not NULL. It also checks any incoming log telemetry for values present in the attribute payment.processor and creates a datapoint within the metric time series for each unique value. Any logs without values in payment.processor will be included in a datapoint with the default_value of unspecified_processor. 
receivers:
  foo:
connectors:
  sum:
    logs:
      checkout.total:
        source_attribute: total.payment
        conditions:
          - attributes["total.payment"] != "NULL"
        attributes:
          - key: payment.processor
            default_value: unspecified_processor
exporters:
  bar:

service:
  pipelines:
    metrics/sum:
       receivers: [sum]
       exporters: [bar]
    logs:
       receivers: [foo]
       exporters: [sum]
Note for Log to Metrics: If your logs contain all values in their body rather than in attributes (E.G. JSON payload) use a transform processor in your pipeline to upsert parsed key/value pairs (in this case from JSON) into attributes attached to the log. 
processors:
  transform/logs:
    log_statements:
      - context: log
        statements:
          - merge_maps(attributes, ParseJSON(body), "upsert")

​
Configuration

​
Example Configuration

sum:
  sum/custom_description:
    spans:
      my.span.sum:
        description: My span record sum.
        source_attribute: my.attribute
    spanevents:
      my.spanevent.sum:
        description: My spanevent sum.
        source_attribute: my.attribute
    metrics:
      my.metric.sum:
        description: My metric sum.
        source_attribute: my.attribute
    datapoints:
      my.datapoint.sum:
        description: My datapoint sum.
        source_attribute: my.attribute
    logs:
      my.logrecord.sum:
        description: My log sum.
        source_attribute: my.attribute
  sum/custom_metric:
    spans:
      my.span.sum:
        source_attribute: my.attribute
    spanevents:
      my.spanevent.sum:
        source_attribute: my.attribute
    metrics:
      my.metric.sum:
        source_attribute: my.attribute
    datapoints:
      my.datapoint.sum:
        source_attribute: my.attribute
    logs:
      my.logrecord.sum:
        source_attribute: my.attribute
  sum/condition:
    spans:
      my.span.sum:
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-s")
    spanevents:
      my.spanevent.sum:
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-e")
    metrics:
      my.metric.sum:
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-m")
    datapoints:
      my.datapoint.sum:
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-d")
    logs:
      my.logrecord.sum:
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-l")
  sum/multiple_condition:
    spans:
      my.span.sum:
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-s")
          - IsMatch(resource.attributes["foo"], "bar-s")
    spanevents:
      my.spanevent.sum:
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-e")
          - IsMatch(resource.attributes["foo"], "bar-e")
    metrics:
      my.metric.sum:
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-m")
          - IsMatch(resource.attributes["foo"], "bar-m")
    datapoints:
      my.datapoint.sum:
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-d")
          - IsMatch(resource.attributes["foo"], "bar-d")
    logs:
      my.logrecord.sum:
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-l")
          - IsMatch(resource.attributes["foo"], "bar-l")
  sum/attribute:
    spans:
      my.span.sum:
        source_attribute: my.attribute
        attributes:
          - key: env
    spanevents:
      my.spanevent.sum:
        source_attribute: my.attribute
        attributes:
          - key: env
    metrics:
      my.metric.sum:
        source_attribute: my.attribute
        # Metrics do not have attributes.
    datapoints:
      my.datapoint.sum:
        source_attribute: my.attribute
        attributes:
          - key: env
    logs:
      my.logrecord.sum:
        source_attribute: my.attribute
        attributes:
          - key: env
  sum/multiple_metrics:
    spans:
      my.span.sum:
        description: My span sum.
        source_attribute: my.attribute
      limited.span.sum:
        description: Limited span sum.
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-s")
        attributes:
          - key: env
          - key: component
            default_value: other
    spanevents:
      my.spanevent.sum:
        description: My span event sum.
        source_attribute: my.attribute
      limited.spanevent.sum:
        description: Limited span event sum.
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-e")
        attributes:
          - key: env
          - key: component
            default_value: other
    metrics:
      my.metric.sum:
        description: My metric sum.
        source_attribute: my.attribute
      limited.metric.sum:
        description: Limited metric sum.
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-m")
    datapoints:
      my.datapoint.sum:
        description: My data point sum.
        source_attribute: my.attribute
      limited.datapoint.sum:
        description: Limited data point sum.
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-d")
        attributes:
          - key: env
          - key: component
            default_value: other
    logs:
      my.logrecord.sum:
        description: My log record sum.
        source_attribute: my.attribute
      limited.logrecord.sum:
        description: Limited log record sum.
        source_attribute: my.attribute
        conditions:
          - IsMatch(resource.attributes["host.name"], "pod-l")
        attributes:
          - key: env
          - key: component
            default_value: other
Last generated: 2026-04-13