32669 wireframe sum connector

.chloggen/32669-wireframe-sum.yaml

@@ -0,0 +1,27 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: new_component
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: sumconnector
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "creates a wireframe and initial pr to develop from"
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [32669]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

.github/CODEOWNERS

@@ -33,6 +33,7 @@ connector/roundrobinconnector/                                      @open-teleme
 connector/routingconnector/                                         @open-telemetry/collector-contrib-approvers @jpkrohling @mwear
 connector/servicegraphconnector/                                    @open-telemetry/collector-contrib-approvers @jpkrohling @mapno
 connector/spanmetricsconnector/                                     @open-telemetry/collector-contrib-approvers @portertech @Frapschen
+connector/sumconnector/                                             @open-telemetry/collector-contrib-approvers @greatestusername @shalper2 @crobert-1
 
 examples/demo/                                                      @open-telemetry/collector-contrib-approvers @open-telemetry/collector-approvers
 

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -34,6 +34,7 @@ body:
       - connector/routing
       - connector/servicegraph
       - connector/spanmetrics
+      - connector/sum
       - examples/demo
       - exporter/alertmanager
       - exporter/alibabacloudlogservice

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -28,6 +28,7 @@ body:
       - connector/routing
       - connector/servicegraph
       - connector/spanmetrics
+      - connector/sum
       - examples/demo
       - exporter/alertmanager
       - exporter/alibabacloudlogservice

.github/ISSUE_TEMPLATE/other.yaml

@@ -28,6 +28,7 @@ body:
       - connector/routing
       - connector/servicegraph
       - connector/spanmetrics
+      - connector/sum
       - examples/demo
       - exporter/alertmanager
       - exporter/alibabacloudlogservice

.github/ISSUE_TEMPLATE/unmaintained.yaml

@@ -33,6 +33,7 @@ body:
       - connector/routing
       - connector/servicegraph
       - connector/spanmetrics
+      - connector/sum
       - examples/demo
       - exporter/alertmanager
       - exporter/alibabacloudlogservice

connector/sumconnector/Makefile

@@ -0,0 +1 @@
+include ../../Makefile.Common

connector/sumconnector/README.md

@@ -0,0 +1,107 @@
+# Sum Connector
+<!-- status autogenerated section -->
+| Status        |           |
+| ------------- |-----------|
+| Distributions | [] |
+| Issues        | [![Open issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aopen%20label%3Aconnector%2Fsum%20&label=open&color=orange&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aopen+is%3Aissue+label%3Aconnector%2Fsum) [![Closed issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aclosed%20label%3Aconnector%2Fsum%20&label=closed&color=blue&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aclosed+is%3Aissue+label%3Aconnector%2Fsum) |
+| [Code Owners](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#becoming-a-code-owner)    | [@greatestusername](https://www.github.com/greatestusername), [@shalper2](https://www.github.com/shalper2), [@crobert-1](https://www.github.com/crobert-1) |
+
+[development]: https://github.com/open-telemetry/opentelemetry-collector#development
+
+## Supported Pipeline Types
+
+| [Exporter Pipeline Type] | [Receiver Pipeline Type] | [Stability Level] |
+| ------------------------ | ------------------------ | ----------------- |
+| traces | metrics | [development] |
+| metrics | metrics | [development] |
+| logs | metrics | [development] |
+
+[Exporter Pipeline Type]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/connector/README.md#exporter-pipeline-type
+[Receiver Pipeline Type]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/connector/README.md#receiver-pipeline-type
+[Stability Level]: https://github.com/open-telemetry/opentelemetry-collector#stability-levels
+<!-- end autogenerated section -->
+
+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).
+
+### Configuration
+
+#### Basic configuration
+
+This configuration will sum numerical values found within the attribute `attribute.with.numerical.value` of any log telemetry routed to the connector. It will then output a metric time series with the name `my.example.metric.name` with those summed values.
+
+```yaml
+receivers:
+  foo:
+connectors:
+  sum:
+    logs:
+      my.example.metric.name:
+        source_attribute: 
+          - attributes["attribute.with.numerical.value"]
+exporters:
+  bar:
+
+service:
+  pipelines:
+    metrics/sum:
+       receivers: [sum]
+       exporters: [bar]
+    logs:
+       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 `logs:` in the [Basic Example](#basic-configuration). 
+  - Can be any of `spans`, `spanevents`, `metrics`, `datapoints`, or `logs`.
+- 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 `attributes["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 and matching any condition will result in summing. 
+- `attributes`: Declaration of attributes to include. Any attributes found will generate a separate sum for each set of unique attributes 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 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
+receivers:
+  foo:
+connectors:
+  sum:
+    logs:
+      checkout.total:
+        source_attribute: 
+          - attributes["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]
+```
+
+[Connectors README]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/connector/README.md

connector/sumconnector/config.go

@@ -0,0 +1,25 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package sumconnector // import "github.com/open-telemetry/opentelemetry-collector-contrib/connector/sumconnector"
+
+// Config for the connector
+type Config struct {
+	Spans      map[string]MetricInfo `mapstructure:"spans"`
+	SpanEvents map[string]MetricInfo `mapstructure:"spanevents"`
+	Metrics    map[string]MetricInfo `mapstructure:"metrics"`
+	DataPoints map[string]MetricInfo `mapstructure:"datapoints"`
+	Logs       map[string]MetricInfo `mapstructure:"logs"`
+}
+
+// MetricInfo for a data type
+type MetricInfo struct {
+	Description string            `mapstructure:"description"`
+	Conditions  []string          `mapstructure:"conditions"`
+	Attributes  []AttributeConfig `mapstructure:"attributes"`
+}
+
+type AttributeConfig struct {
+	Key          string `mapstructure:"key"`
+	DefaultValue any    `mapstructure:"default_value"`
+}

connector/sumconnector/connector.go

@@ -0,0 +1,59 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package sumconnector // import "github.com/open-telemetry/opentelemetry-collector-contrib/connector/sumconnector"
+
+import (
+	"context"
+
+	"go.opentelemetry.io/collector/component"
+	"go.opentelemetry.io/collector/consumer"
+	"go.opentelemetry.io/collector/pdata/plog"
+	"go.opentelemetry.io/collector/pdata/pmetric"
+	"go.opentelemetry.io/collector/pdata/ptrace"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl/contexts/ottldatapoint"
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl/contexts/ottllog"
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl/contexts/ottlmetric"
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl/contexts/ottlspan"
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl/contexts/ottlspanevent"
+)
+
+// sum can sum attribute values from spans, span event, metrics, data points, or log records
+// and emit the sums onto a metrics pipeline.
+type sum struct {
+	metricsConsumer consumer.Metrics
+	component.StartFunc
+	component.ShutdownFunc
+
+	spansMetricDefs      map[string]metricDef[ottlspan.TransformContext]
+	spanEventsMetricDefs map[string]metricDef[ottlspanevent.TransformContext]
+	metricsMetricDefs    map[string]metricDef[ottlmetric.TransformContext]
+	dataPointsMetricDefs map[string]metricDef[ottldatapoint.TransformContext]
+	logsMetricDefs       map[string]metricDef[ottllog.TransformContext]
+}
+
+func (c *sum) Capabilities() consumer.Capabilities {
+	return consumer.Capabilities{MutatesData: false}
+}
+
+func (c *sum) ConsumeTraces(ctx context.Context, td ptrace.Traces) error {
+	sumMetrics := pmetric.NewMetrics()
+	sumMetrics.ResourceMetrics().EnsureCapacity(td.ResourceSpans().Len())
+
+	return c.metricsConsumer.ConsumeMetrics(ctx, sumMetrics)
+}
+
+func (c *sum) ConsumeMetrics(ctx context.Context, md pmetric.Metrics) error {
+	sumMetrics := pmetric.NewMetrics()
+	sumMetrics.ResourceMetrics().EnsureCapacity(md.ResourceMetrics().Len())
+
+	return c.metricsConsumer.ConsumeMetrics(ctx, sumMetrics)
+}
+
+func (c *sum) ConsumeLogs(ctx context.Context, ld plog.Logs) error {
+	sumMetrics := pmetric.NewMetrics()
+	sumMetrics.ResourceMetrics().EnsureCapacity(ld.ResourceLogs().Len())
+
+	return c.metricsConsumer.ConsumeMetrics(ctx, sumMetrics)
+}