Transform Processor function set_semconv_span_name()

.chloggen/ottl-GetSemConvSpanName.yaml

@@ -0,0 +1,32 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: "enhancement"
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: "pkg/ottl"
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "New OTTL function `GetSemconvSpanName()` to derives a span name from the semantic conventions for HTTP, RPC, messaging, and database spans."
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [43124]
+
+# (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: |
+  In other cases, the original `span.name` is returned unchanged.
+  The primary use of `GetSemconvSpanName()` is alongside the
+  [Span Metrics Connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/spanmetricsconnector)
+  to address high-cardinality issues in span metrics when `span.name` does not comply with the OTel requirement
+  that span names be low cardinality.
+
+# 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: [user]

pkg/ottl/ottlfuncs/README.md

@@ -468,6 +468,7 @@ Available Converters:
 - [FNV](#fnv)
 - [Format](#format)
 - [FormatTime](#formattime)
+- [GetSemconvSpanName](#getsemconvspanname)
 - [GetXML](#getxml)
 - [HasPrefix](#hasprefix)
 - [HasSuffix](#hassuffix)
@@ -943,6 +944,9 @@ Examples:
 - `FormatTime(UnixNano(span.attributes["time_nanoseconds"]), "%b %d %Y %H:%M:%S")`
 - `FormatTime(TruncateTime(spanevent.time, Duration("10h 20m"))), "%Y-%m-%d %H:%M:%S")`
 
+### GetSemconvSpanName
+
+
 ### GetXML
 
 `GetXML(target, xpath)`

processor/transformprocessor/README.md

@@ -272,6 +272,10 @@ In addition to the common OTTL functions, the processor defines its own function
 - [aggregate_on_attribute_value](#aggregate_on_attribute_value)
 - [merge_histogram_buckets](#merge_histogram_buckets)
 
+**Traces only functions**
+
+- [GetSemConvSpanName](#getsemconvspanname)
+
 ### convert_sum_to_gauge
 
 `convert_sum_to_gauge()`
@@ -650,6 +654,127 @@ Examples:
 # counts: [5, 11, 1]
 ```
 
+### GetSemConvSpanName
+
+`GetSemconvSpanName()`
+
+The `GetSemconvSpanName()` function derives a span name from the OpenTelemetry semantic conventions for [HTTP](https://opentelemetry.io/docs/specs/semconv/http/http-spans/), [RPC](https://opentelemetry.io/docs/specs/semconv/rpc/rpc-spans/), [messaging](https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/), and [database](https://opentelemetry.io/docs/specs/semconv/database/) spans. In other cases, the original `span.name` is returned unchanged.
+
+Its primary use case is to address high-cardinality issues in span metrics when `span.name` does not comply with the OpenTelemetry requirement that span names be low cardinality.
+
+`GetSemconvSpanName()` returned value examples:
+
+<table>
+<thead>
+<tr>
+<th>Span</th>
+<th> <code>GetSemconvSpanName()</code> </th>
+<th>Comments</th>
+</tr>
+</thead>
+<tbody>
+<!-- HTTP SERVER SPANS -->
+<tr>
+<td>
+<pre>
+<code>
+span.name: GET /api/v1/users/{id}
+span.kind: server
+span.attributes["http.request.method"]: GET
+span.attributes["http.route"]: /api/v1/users/{id}
+</code>
+</pre>
+</td>
+<td>
+<pre>
+GET /api/v1/users/{id}
+</pre>
+</td>
+<td>
+Compliant span names don't get modified
+</td>
+</tr>
+<tr>
+<td>
+<pre>
+<code>
+span.name: GET /api/v1/users/123 # /!\ high cardinality
+span.kind: server
+span.attributes["http.request.method"]: GET
+span.attributes["http.route"]: /api/v1/users/{id}
+</code>
+</pre>
+</td>
+<td>
+<pre>
+GET /api/v1/users/{id}
+</pre>
+</td>
+<td>
+High cardinality span name <code>GET /api/v1/users/123</code> gets sanitized without loss of information when recommended semantic convention span attributes are provided (e.g. <code>http.request.method<code> and <code>http.route</code>).
+</td>
+</tr>
+<tr>
+<td>
+<pre>
+<code>
+span.name: GET /api/v1/users/123 # /!\ high cardinality
+span.kind: server
+span.attributes["http.request.method"]: GET
+</code>
+</pre>
+</td>
+<td>
+<pre>
+GET
+</pre>
+</td>
+<td>
+High-cardinality span name <code>GET /api/v1/users/123</code> is sanitized with some loss of information when recommended semantic convention span attributes are missing (e.g., <code>http.route</code>).
+</td>
+</tr>
+</table>
+
+Backward compatibility: `GetSemconvSpanName()` supports the version 1.37 of the semantic conventions and backward compatibility
+for the following attributes:
+
+| Attribute             | Backward compatibility |
+|-----------------------|------------------------|
+| `http.request.method` | `http.method`          |
+| `rpc.method`          | `rpc.grpc.method`      |
+| `rpc.service`         | `rpc.grpc.service`     |
+| `db.system.name`      | `db.system`            |
+| `db.operation.name`   | `db.operation`         |
+| `db.collection.name`  | `db.name`              |
+
+Transform processor syntax examples:
+
+- `set(span.name, GetSemconvSpanName())`
+
+- Ingestion pipeline preventing high cardinality on the `span.name` attribute of the metrics produced by the span metrics connector:
+
+    ```yaml
+    processors:
+      # prevent high-cardinality span names
+      transform/sanitize_span_name:
+        error_mode: ignore
+        trace_statements:
+          - set(span.cache["original_name"], span.name)
+          - set(span.name, GetSemconvSpanName())
+          - set(span.attributes["original_name"], span.cache["original_name"]) where span.cache["original_name"] != span.name
+    connectors:
+      spanmetrics:
+    service:
+      pipelines:
+        traces:
+          receivers: [otlp]
+          processors: [..., transform/sanitize_span_name, ...]
+          exporters: [otlp, spanmetrics]
+        metrics:
+          receivers: [spanmetrics, ...]
+          exporters: [otlp]
+    ```
+
 ## Examples
 
 ### Perform transformation if field does not exist

processor/transformprocessor/go.mod

@@ -33,6 +33,7 @@ require (
 	go.opentelemetry.io/collector/processor/processorhelper/xprocessorhelper v0.138.1-0.20251021231522-c657d5d4e920
 	go.opentelemetry.io/collector/processor/processortest v0.138.1-0.20251021231522-c657d5d4e920
 	go.opentelemetry.io/collector/processor/xprocessor v0.138.1-0.20251021231522-c657d5d4e920
+	go.opentelemetry.io/otel v1.38.0
 	golang.org/x/exp v0.0.0-20240506185415-9bf2ced13842
 )
 
@@ -78,7 +79,6 @@ require (
 	go.opentelemetry.io/collector/pdata/testdata v0.138.1-0.20251021231522-c657d5d4e920 // indirect
 	go.opentelemetry.io/collector/pipeline v1.44.1-0.20251021231522-c657d5d4e920 // indirect
 	go.opentelemetry.io/contrib/bridges/otelzap v0.13.0 // indirect
-	go.opentelemetry.io/otel v1.38.0 // indirect
 	go.opentelemetry.io/otel/log v0.14.0 // indirect
 	go.opentelemetry.io/otel/sdk v1.38.0 // indirect
 	go.opentelemetry.io/otel/sdk/metric v1.38.0 // indirect