OTEP: Span type over OTLP

[lmolkova]

Related to #4733, #531
open-telemetry/semantic-conventions#2055,
open-telemetry/semantic-conventions#3936

Changes

Some signals can be identified in OTLP by a dedicated field: metrics by name, events by name, and entities by type. Spans and profiles cannot.

This makes several things difficult:

• Validating spans in Weaver live checks. For metrics, we know which attributes are expected for a given metric name. Spans have no equivalent identity, which limits testing and conformance validation.
• Applying transformations to specific spans. OTTL has limited ability to match a particular span type.
• Querying specific span types. Each query requires a handcrafted set of heuristics that hopefully identifies the intended span type.
• Generating metrics from spans. Span-to-metrics pipelines can suffer from high-cardinality span names. A stable span type could be used instead.

This OTEP proposes adding type as a new optional, top-level OTLP field. Instrumentation may set it through the API, and samplers may use it when making sampling decisions.

The main concerns raised previously, as I recall, were:

• Overhead. Semantic conventions currently compensate for the lack of signal identity in OTLP by adding identifying attributes. A dedicated field could eliminate these workarounds and provide a consistent approach across semantic conventions. I.e. overhead is introduced when identity is important anyway.
• Span following multipole definitions. Such a span should either have its own distinct type or no type at all. A span has one name, one kind, and one status. If a span is considered to have multiple types simultaneously, it means we don't meaningfully describe these properties.

An attribute could serve a similar purpose, but we already explored that approach for events and ultimately introduced a top-level field. A dedicated field avoids concerns around attribute merging, modification, and removal due to limits, while improving performance and simplifying routing and filtering.

This proposal is not breaking. Instrumentation does not need to populate the field immediately, and consumers may ignore it until they have a use for it. Applications don't need to set it directly unless they want to identify spans for querying or validation.

• Related issues #above
• Links to the prototypes (when adding or changing features)
  • Python Prototype for span type OTEP opentelemetry-python#5464
  • Weaver live check wip: live-check based on span type weaver#1648
  • Semconv: no need, we already have span type in definitions - https://github.com/open-telemetry/semantic-conventions/blob/a793bf3d5356790910e5a9a2e93bb3b40f3c8594/model/messaging/spans.yaml#L84
• CHANGELOG.md file updated for non-trivial changes
  • For trivial changes, include [chore] in the PR title to skip the changelog check
• Declarative config data model is updated if SDK config surface is changed

[trask]

🎉

[trask]

yes! but also #1588 😅 (this seems like the kind of detail that can be worked on post-OTEP)

[jack-berg]

I think the real issue (which #1588 touches on) is that its hard to evolve the parameters made accessible to Sampler. I don't think we should let that get in the way.

[lmolkova]

It makes sense for SDKs to bundle these changes together at least when stabilizing this API to minimize churn and forward compatibility pains. Added a note to consider it when working on the spec.

[cijothomas]

Looks good and I agree with the direction. Details can be specified at specification time.

(Left a non-blocking comment about "span.type" and "log.event_name" assymetry, but don't have any bette suggestions myself)

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on the author · refreshed 2026-09-01 21:41 UTC

Respond to 1 review item (e.g. link a commit, explain why not, ask a follow-up):

• Inline threads: 1

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Should this be with reviewers? Comment /dashboard route:reviewers to route it to them.
• Anything wrong — including the routing? Report it with what you expected; it helps us improve the dashboard.

[jack-berg]

I think the real issue (which #1588 touches on) is that its hard to evolve the parameters made accessible to Sampler. I don't think we should let that get in the way.

[MrAlias]

I support adding a scalar span-definition identity and agree that multiple semantic facets should not turn type into a list. The proposal still needs a viable cross-language compatibility and identity model before we commit this direction across the API, SDK, and protocol.

[MrAlias]

{area}.{kind}.{domain-specific-name} only avoids collisions within one resolved registry. Since third-party registries may define the same string, the OTEP needs to say whether identity is globally namespaced or scoped by schema_url; this also determines what samplers must receive to match a definition unambiguously.

[lmolkova]

addressed in 1f94542 - uniqueness is per schema-url.

Schema URL would become visible to samplers via #1588. Given we don't demand schema url in metric views, I don't think it's practical to demand access to schema url either. Still the OTEP recommends doing span type along with #1588

[MrAlias]

Scoping uniqueness to schema URL makes sense, and clarifies the registry model, but the matching model still needs to be clarified. Schema URL is optional, while the sampler and configuration proposals match only on span type. Two registries can therefore define the same type and produce indistinguishable matches. We need either globally unique type names (I'm guessing not likely), or identity and matching consistently defined as (schema_url, span_type), including behavior when the Schema URL is absent.

[MrAlias]

Neither linked prototype exercises the proposed top-level OTLP field: Python exports otel.span.type as an attribute, and Weaver reads that attribute. This change also spans stable API/SDK surfaces, so before approving the OTEP we need the typed-OO and structural-language API/SDK prototypes, plus actual Span.type protocol prototypes on both client and server, called for by the Specification Principles.

[lmolkova]

What exactly the otlp prototype would show? That we can add a top-level string property into span proto and use it in exporters? I can burn some tokens on this, but I don't believe such prototype would be useful or reveal anything new. We've done it relatively recently for event name on logs #4320 and it was uneventful.

The OTEP is a design doc, not the actual change to specification - it might require prototypes in multiple languages but does not necessarily require them.

[MrAlias]

I'm guessing the intent of the specification principles was to show compatibility and viability of the approach:

The specification is useless without the ecosystem it enables. Changes should focus on real world use cases, and real user needs. Additionally, changes should be implementable across the entire OpenTelemetry ecosystem.

This means proposals should think "end-to-end" not "add this one little thing".

Projects and proposals should provide prototypes or implementations before changes are made to the Specification.

We have a few simple rules of thumb regarding prototypes:

• API/SDK changes should be prototyped in three languages. The goal is coverage of possible API designs, not any specific language:
  • One language should cover typed Object-Oriented ecosystems (Java, .NET, etc.)
  • One language should cover dynamically typed ecosystems (Python, JavaScript)
  • One language should cover structural ecosystems (Go, Rust)
• Protocol changes should be prototyped both on the client and the server.
• Prototypes can be unmerged Pull Requests, existing projects, etc. but must demonstrate the feature with confidence that the Specification of it will be successful.

The current Python prototype still exports an attribute rather than the proposed top-level OTLP field. Based on this, I'm not sure we can say there is a prototype that is showing this proposal in its described state.

Having a prototype would be helpful to me to see this in action, but I'm also fine resolving this if there explicit maintainer agreement to waive that guidance here. I can wait for implementations afterwards if that's the agreement.

[MrAlias]

This adds sampler configuration that matches on span type, but the PR does not link a corresponding proposal in opentelemetry-configuration. CONTRIBUTING.md requires SDK component configuration changes to be proposed and approved there together; could we either add that proposal or remove this configuration change from scope?

[lmolkova]

added more details on config in 13e40a5 and python prototype in open-telemetry/opentelemetry-python@937c832

I believe configuration PR is needed when implementing OTEP in the spec, but not for the OTEP itself - it does not add SDK component config just yet.

opentelemetry-specification/CONTRIBUTING.md

Lines 48 to 51 in 8057bf6

	If the change adds or modifies SDK component configuration, the PR must link
	to a corresponding proposed change to the
	[declarative configuration schema](https://github.com/open-telemetry/opentelemetry-configuration).
	These PRs should be approved and merged together.

My goal here is to outline direction and show it's possible and can fit nicely into declarative config.

[MrAlias]

The OTEP does say the rule-based sampler schema gains span_types, so it is proposing an SDK component configuration modification, right? Should we just defer this configuration change from the OTEP’s scope and add it as a follow-up task?

[lmolkova]

@MrAlias thanks for the review! I believe I addressed some of your comments and replied to others. Could you please take another look? Thanks!

[MrAlias]

@lmolkova I think some strange GitHub issues is occurring. GitHub still shows this PR at 7f69c92, while lmolkova:span-type-otep is at 6bc3dcd. The linked fixes therefore aren’t part of the PR diff or its CI yet. Could you update or repush the PR branch so the PR head reflects the new commits? I reviewed the fork branch directly in the meantime, but don't have code here to reference in a review.

[dashpole]

Quick Go prototype looks ok to me: open-telemetry/opentelemetry-go#8914

[lmolkova]

I think some strange GitHub issues is occurring. GitHub still shows this PR at 7f69c92, while lmolkova:span-type-otep is at 6bc3dcd. The linked fixes therefore aren’t part of the PR diff or its CI yet. Could you update or repush the PR branch so the PR head reflects the new commits? I reviewed the fork branch directly in the meantime, but don't have code here to reference in a review.

oh, merged main and it fixed things. thank you @MrAlias !