Package org.apache.juneau.rest.server.tracing

Class TraceOperation

java.lang.Object

org.apache.juneau.rest.server.tracing.TraceOperation

public final class TraceOperation
extends Object

Immutable, low-cardinality description of the operation a TracerHook bridge should name a span after, supplied to TracerHook.startSpan(org.apache.juneau.rest.server.RestRequest, TraceContextCarrier, TraceOperation) alongside the extracted TraceContextCarrier.

juneau-rest-server has no notion of MCP, JSON-RPC, or OpenTelemetry — this type exists so a neutral TraceContextExtractor (for example the juneau-rest-server-mcp-v20260728 binding, added in a later task) can hand a bridge (for example the OpenTelemetry bridge in juneau-rest-server-tracing-otel) a low-cardinality span name plus a small set of attributes derived from resolved request arguments, without either side depending on the other's types.

Default operation

DEFAULT carries no span name and no attributes. It is the value TraceContextExtractor.operation(org.apache.juneau.rest.server.RestRequest, java.lang.Object[]) returns when an extractor implementation supplies only extract(...) — a bridge receiving DEFAULT keeps whatever span name / attributes it would otherwise derive from the RestRequest itself (HTTP method, route, etc.); it is not required to name every span after a non-HTTP operation.

Attribute-name constants

The attribute-name constants declared here are the exact, pinned MCP/GenAI span-attribute keys that a later OpenTelemetry-bridge task and MCP-binding task both need to agree on. They are declared on this neutral type — rather than duplicated as private literals in each of those two modules — specifically so juneau-rest-server stays free of any OpenTelemetry or MCP import while still being the single source of truth for the wire-level attribute name. Attribute values are supplied per-operation via getAttributes(); these constants are only the keys.

Pinned to the OpenTelemetry GenAI semantic-conventions snapshot at commit c739977ae690961f36e435504e5c1febaef1f7f3 plus core OpenTelemetry semantic conventions v1.43.0. All of these attributes are experimental/development — names and requirement levels may change in a future semantic-conventions release; this pin must be re-checked before any OpenTelemetry or semantic-conventions dependency upgrade touches MCP tracing.

See Also:

• TraceContextCarrier
• TraceContextExtractor
• TracerHook
• OpenTelemetry GenAI semantic conventions (pinned snapshot)
• Observability — Micrometer + OpenTelemetry

Since:

10.0.0

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ATTR_ERROR_TYPE	Experimental span-attribute key: the JSON-RPC error category or handler exception type.
static final String	ATTR_GEN_AI_OPERATION_NAME	Experimental span-attribute key: the GenAI operation name (e.g.
static final String	ATTR_GEN_AI_PROMPT_NAME	Experimental span-attribute key: the prompts/get target prompt name.
static final String	ATTR_GEN_AI_TOOL_NAME	Experimental span-attribute key: the tools/call target tool name.
static final String	ATTR_JSONRPC_REQUEST_ID	Experimental span-attribute key: the JSON-RPC request id, in string form.
static final String	ATTR_MCP_METHOD_NAME	Experimental span-attribute key: the exact MCP method name (e.g.
static final String	ATTR_MCP_PROTOCOL_VERSION	Experimental span-attribute key: the negotiated MCP protocol version (e.g.
static final String	ATTR_MCP_RESOURCE_URI	Experimental span-attribute key: the resources/read target resource URI.
static final String	ATTR_RPC_RESPONSE_STATUS_CODE	Experimental span-attribute key: the JSON-RPC error response's numeric code, in string form.
static final TraceOperation	DEFAULT	The default operation: no span name override, no attributes.

Method Summary

Modifier and Type	Method	Description
Map<String,String>	getAttributes()	Returns the span attributes.
String	getSpanName()	Returns the low-cardinality span name.
static TraceOperation	of(String spanName)	Creates an operation with a span name and no attributes.
static TraceOperation	of(String spanName, Map<String,String> attributes)	Creates an operation with a span name and attributes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

ATTR_MCP_METHOD_NAME

public static final String ATTR_MCP_METHOD_NAME

Experimental span-attribute key: the exact MCP method name (e.g. "tools/call").

See Also:

• Constant Field Values

ATTR_MCP_PROTOCOL_VERSION

public static final String ATTR_MCP_PROTOCOL_VERSION

Experimental span-attribute key: the negotiated MCP protocol version (e.g. "2026-07-28").

See Also:

• Constant Field Values

ATTR_JSONRPC_REQUEST_ID

public static final String ATTR_JSONRPC_REQUEST_ID

Experimental span-attribute key: the JSON-RPC request id, in string form.

See Also:

• Constant Field Values

ATTR_GEN_AI_TOOL_NAME

public static final String ATTR_GEN_AI_TOOL_NAME

Experimental span-attribute key: the tools/call target tool name.

See Also:

• Constant Field Values

ATTR_GEN_AI_PROMPT_NAME

public static final String ATTR_GEN_AI_PROMPT_NAME

Experimental span-attribute key: the prompts/get target prompt name.

See Also:

• Constant Field Values

ATTR_MCP_RESOURCE_URI

public static final String ATTR_MCP_RESOURCE_URI

Experimental span-attribute key: the resources/read target resource URI.

See Also:

• Constant Field Values

ATTR_GEN_AI_OPERATION_NAME

public static final String ATTR_GEN_AI_OPERATION_NAME

Experimental span-attribute key: the GenAI operation name (e.g. "execute_tool").

See Also:

• Constant Field Values

ATTR_RPC_RESPONSE_STATUS_CODE

public static final String ATTR_RPC_RESPONSE_STATUS_CODE

Experimental span-attribute key: the JSON-RPC error response's numeric code, in string form.

See Also:

• Constant Field Values

ATTR_ERROR_TYPE

public static final String ATTR_ERROR_TYPE

Experimental span-attribute key: the JSON-RPC error category or handler exception type.

See Also:

• Constant Field Values

DEFAULT

public static final TraceOperation DEFAULT

The default operation: no span name override, no attributes.

Returned by TraceContextExtractor.operation(org.apache.juneau.rest.server.RestRequest, java.lang.Object[]) when an extractor supplies no override.

Method Details

of

public static TraceOperation of(String spanName)

Creates an operation with a span name and no attributes.

Parameters:

spanName - The low-cardinality span name (e.g. "tools/call echo"). Must not be null or blank.

Returns:

A new TraceOperation. Never null.

of

public static TraceOperation of(String spanName,
 Map<String,String> attributes)

Creates an operation with a span name and attributes.

Parameters:

spanName - The low-cardinality span name (e.g. "tools/call echo"). Must not be null or blank.

attributes - The span attributes, keyed by attribute name (typically one of the ATTR_* constants declared on this class). Iteration order is preserved. Must not be null; may be empty.

Returns:

A new TraceOperation. Never null.

getSpanName

public String getSpanName()

Returns the low-cardinality span name.

Returns:

The span name, or null for DEFAULT (no override — the bridge keeps its own default naming).

getAttributes

public Map<String,String> getAttributes()

Returns the span attributes.

Returns:

An unmodifiable, insertion-ordered map of span attributes. Never null; empty for DEFAULT.