> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Sum

> OpenTelemetry connector for Sum

# Sum Connector

![Status](https://img.shields.io/badge/status-alpha-red)

**Available in:** `contrib`

**Maintainers:** [@greatestusername](https://github.com/greatestusername), [@shalper2](https://github.com/shalper2), [@crobert-1](https://github.com/crobert-1)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/sumconnector)

## 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](https://github.com/open-telemetry/opentelemetry-collector/blob/main/connector/README.md).

### 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.

```yaml theme={null}
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](#basic-configuration).
  * 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](#basic-configuration)
* `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](#basic-configuration)

#### Optional Settings

* `conditions`: [OTTL syntax](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/pkg/ottl/LANGUAGE.md) 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. Conditions support OTTL path context names (e.g. `span.attributes["x"]`, `resource.attributes["x"]`, `log.attributes["x"]`, `metric.name`). Paths without an explicit context are interpreted in the context of the enclosing block. It is recommended to switch to the new syntax to avoid breaking changes in the future.
* `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`.

```yaml theme={null}
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](https://github.com/open-telemetry/opentelemetry-log-collection/tree/main/docs/operators) (in this case from JSON) into attributes attached to the log.

```yaml theme={null}
processors:
  transform/logs:
    log_statements:
      - context: log
        statements:
          - merge_maps(attributes, ParseJSON(body), "upsert")
```

[Connectors README]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/connector/README.md

## Configuration

### Example Configuration

```yaml theme={null}
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-07-06*