Skip to content

Add server span name feature to metadata #15221

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add server span name feature to metadata #15221

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/contributing/documenting-instrumentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,8 @@ the relevant functionality descriptions.

List of possible options:

* `HTTP_ROUTE`: Instrumentation that enriches HTTP spans with route information
* `HTTP_ROUTE`: Instrumentation that enriches HTTP spans with route information (e.g., `/users/{id}`). Sets both the span name and the `http.route` attribute.
* `SERVER_SPAN_NAME`: Instrumentation that enriches the HTTP server span name with controller, view, or operation information. This feature applies to instrumentations that update the server span name based on framework-specific information (like JSF view IDs or JAX-WS operation names) without setting the `http.route` attribute. The key distinction from `HTTP_ROUTE` is that `SERVER_SPAN_NAME` only updates the span name, while `HTTP_ROUTE` updates both the span name and the `http.route` attribute.
Copy link
Contributor

@laurit laurit Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the main question here is whether we should always set the route, even when the set route does not match the requested url. If that is ok we could change these instrumentations to set the route. If it is not ok we'll probably have to change some other instrumentations to update only the span name. Hoping to get some guidance from @trask on this.

Copy link
Member

@trask trask Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If that is ok we could change these instrumentations to set the route.

Yeah, I like that our route matches the url wherever possible (i.e. instead of using the controller class / method name as the route).

But I think when this isn't possible, we should still capture http.route even if it doesn't match the url.

Copy link
Contributor

@laurit laurit Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But I think when this isn't possible, we should still capture http.route even if it doesn't match the url.

Does the spec allow it? https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#http-route says

MUST NOT be populated when this is not supported by the HTTP server framework

And also mentions static and dynamic path segments which leaves an impression that it is intended for rest style paths. I believe that we have instrumentations where we set route to something that should identify the viewed page or invoked action but isn't necessarily what is in the request path. If this liberal usage of route is fine then we might not need SERVER_SPAN_NAME at all and could just update route to whatever we see fit and get the span name changed through that. If it is not fine then we might need to change a couple of instrumentations.

* `CONTEXT_PROPAGATION`: Instrumentation that propagates OpenTelemetry context across application or thread boundaries. This applies to:
* Inter-process/application context propagation: Passing context through headers between applications (HTTP, gRPC, messaging, etc.)
* Inter-thread context propagation: Passing context from one thread to another (executors, actors, reactive streams, etc.)
Expand Down
24 changes: 14 additions & 10 deletions docs/instrumentation-list.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5681,10 +5681,10 @@ libraries:
- name: jaxws-2.0-axis2-1.6
display_name: Apache Axis2 1.6 JAX-WS 2.x
description: |
This instrumentation enriches HTTP server spans with route information, and enables controller spans for Apache Axis2 JAX-WS web services (controller spans are disabled by default).
This instrumentation enriches server span names with web service operation information, and enables controller spans for Apache Axis2 JAX-WS web services (controller spans are disabled by default).
library_link: https://axis.apache.org/axis2/java/core/
features:
- HTTP_ROUTE
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
source_path: instrumentation/jaxws/jaxws-2.0-axis2-1.6
scope:
Expand All @@ -5705,10 +5705,10 @@ libraries:
- name: jaxws-cxf-3.0
display_name: Apache CXF 3.x JAX-WS
description: |
This instrumentation enriches HTTP server spans with route information, and enables controller spans for Apache CXF JAX-WS web services (controller spans are disabled by default).
This instrumentation enriches server span names with web service operation information, and enables controller spans for Apache CXF JAX-WS web services (controller spans are disabled by default).
library_link: https://cxf.apache.org/
features:
- HTTP_ROUTE
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
source_path: instrumentation/jaxws/jaxws-cxf-3.0
scope:
Expand Down Expand Up @@ -5757,10 +5757,10 @@ libraries:
- name: jaxws-metro-2.2
display_name: Metro JAX-WS
description: |
This instrumentation enriches HTTP server spans with route information, and enables controller spans for Metro JAX-WS web services (controller spans are disabled by default).
This instrumentation enriches server span names with web service operation information, and enables controller spans for Metro JAX-WS web services (controller spans are disabled by default).
library_link: https://javaee.github.io/metro/
features:
- HTTP_ROUTE
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
source_path: instrumentation/jaxws/jaxws-metro-2.2
scope:
Expand Down Expand Up @@ -6659,9 +6659,10 @@ libraries:
- name: jsf-mojarra-1.2
display_name: JSF
description: |
This instrumentation enables controller spans for Mojarra JSF action listeners (controller spans are disabled by default).
This instrumentation enriches server span names with JSF view information, and enables controller spans for Mojarra JSF action listeners (controller spans are disabled by default).
library_link: https://github.com/eclipse-ee4j/mojarra
features:
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
source_path: instrumentation/jsf/jsf-mojarra-1.2
scope:
Expand All @@ -6686,9 +6687,10 @@ libraries:
- name: jsf-mojarra-3.0
display_name: JSF
description: |
This instrumentation enables controller spans for Mojarra JSF action listeners (controller spans are disabled by default).
This instrumentation enriches server span names with JSF view information, and enables controller spans for Mojarra JSF action listeners (controller spans are disabled by default).
library_link: https://github.com/eclipse-ee4j/mojarra
features:
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
source_path: instrumentation/jsf/jsf-mojarra-3.0
minimum_java_version: 11
Expand All @@ -6710,9 +6712,10 @@ libraries:
- name: jsf-myfaces-1.2
display_name: JSF
description: |
This instrumentation enables controller spans for Apache MyFaces action listeners (controller spans are disabled by default).
This instrumentation enriches server span names with JSF view information, and enables controller spans for Apache MyFaces action listeners (controller spans are disabled by default).
library_link: https://myfaces.apache.org/
features:
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
source_path: instrumentation/jsf/jsf-myfaces-1.2
scope:
Expand All @@ -6733,9 +6736,10 @@ libraries:
- name: jsf-myfaces-3.0
display_name: JSF
description: |
This instrumentation enables controller spans for Apache MyFaces action listeners (controller spans are disabled by default).
This instrumentation enriches server span names with JSF view information, and enables controller spans for Apache MyFaces action listeners (controller spans are disabled by default).
library_link: https://myfaces.apache.org/
features:
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
source_path: instrumentation/jsf/jsf-myfaces-3.0
minimum_java_version: 11
Expand Down
1 change: 1 addition & 0 deletions instrumentation-docs/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,7 @@ public class SpringWebInstrumentationModule extends InstrumentationModule
* The specific functionality that the instrumentation provides
* Options are:
* HTTP_ROUTE
* SERVER_SPAN_NAME
* CONTEXT_PROPAGATION
* AUTO_INSTRUMENTATION_SHIM
* CONTROLLER_SPANS
Expand Down
1 change: 1 addition & 0 deletions .../src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationFeature.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
*/
public enum InstrumentationFeature {
HTTP_ROUTE,
SERVER_SPAN_NAME,
CONTEXT_PROPAGATION,
AUTO_INSTRUMENTATION_SHIM,
CONTROLLER_SPANS,
Expand Down
7 changes: 4 additions & 3 deletions instrumentation/jaxws/jaxws-2.0-axis2-1.6/metadata.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
display_name: Apache Axis2 1.6 JAX-WS 2.x
description: >
This instrumentation enriches HTTP server spans with route information, and enables controller
spans for Apache Axis2 JAX-WS web services (controller spans are disabled by default).
This instrumentation enriches server span names with web service operation information, and
enables controller spans for Apache Axis2 JAX-WS web services (controller spans are disabled by
default).
library_link: https://axis.apache.org/axis2/java/core/
features:
- HTTP_ROUTE
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
configurations:
- name: otel.instrumentation.common.experimental.controller-telemetry.enabled
Expand Down
7 changes: 4 additions & 3 deletions instrumentation/jaxws/jaxws-cxf-3.0/metadata.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
display_name: Apache CXF 3.x JAX-WS
description: >
This instrumentation enriches HTTP server spans with route information, and enables controller
spans for Apache CXF JAX-WS web services (controller spans are disabled by default).
This instrumentation enriches server span names with web service operation information, and
enables controller spans for Apache CXF JAX-WS web services (controller spans are disabled by
default).
library_link: https://cxf.apache.org/
features:
- HTTP_ROUTE
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
configurations:
- name: otel.instrumentation.common.experimental.controller-telemetry.enabled
Expand Down
6 changes: 3 additions & 3 deletions instrumentation/jaxws/jaxws-metro-2.2/metadata.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
display_name: Metro JAX-WS
description: >
This instrumentation enriches HTTP server spans with route information, and enables controller
spans for Metro JAX-WS web services (controller spans are disabled by default).
This instrumentation enriches server span names with web service operation information, and
enables controller spans for Metro JAX-WS web services (controller spans are disabled by default).
library_link: https://javaee.github.io/metro/
features:
- HTTP_ROUTE
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
configurations:
- name: otel.instrumentation.common.experimental.controller-telemetry.enabled
Expand Down
5 changes: 3 additions & 2 deletions instrumentation/jsf/jsf-mojarra-1.2/metadata.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
display_name: JSF
description: >
This instrumentation enables controller spans for Mojarra JSF action listeners (controller spans
are disabled by default).
This instrumentation enriches server span names with JSF view information, and enables controller
spans for Mojarra JSF action listeners (controller spans are disabled by default).
features:
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
library_link: https://github.com/eclipse-ee4j/mojarra
configurations:
Expand Down
5 changes: 3 additions & 2 deletions instrumentation/jsf/jsf-mojarra-3.0/metadata.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
display_name: JSF
description: >
This instrumentation enables controller spans for Mojarra JSF action listeners (controller spans
are disabled by default).
This instrumentation enriches server span names with JSF view information, and enables controller
spans for Mojarra JSF action listeners (controller spans are disabled by default).
features:
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
library_link: https://github.com/eclipse-ee4j/mojarra
configurations:
Expand Down
5 changes: 3 additions & 2 deletions instrumentation/jsf/jsf-myfaces-1.2/metadata.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
display_name: JSF
description: >
This instrumentation enables controller spans for Apache MyFaces action listeners (controller
spans are disabled by default).
This instrumentation enriches server span names with JSF view information, and enables controller
spans for Apache MyFaces action listeners (controller spans are disabled by default).
features:
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
library_link: https://myfaces.apache.org/
configurations:
Expand Down
5 changes: 3 additions & 2 deletions instrumentation/jsf/jsf-myfaces-3.0/metadata.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
display_name: JSF
description: >
This instrumentation enables controller spans for Apache MyFaces action listeners (controller
spans are disabled by default).
This instrumentation enriches server span names with JSF view information, and enables controller
spans for Apache MyFaces action listeners (controller spans are disabled by default).
features:
- SERVER_SPAN_NAME
- CONTROLLER_SPANS
library_link: https://myfaces.apache.org/
configurations:
Expand Down
Loading