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

Interface Scope

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
NoOpTracerHook.NoOpScope
public interface Scope extends AutoCloseable
Handle to one in-flight TracerHook-managed span.

Returned by TracerHook.startSpan(org.apache.juneau.rest.server.RestRequest). The framework drives the setStatusCode / setError / close transitions inside a finally block so the span always closes — including on exception paths.

Bridge implementations typically wrap the downstream tracer's native span / scope. The OpenTelemetry bridge in juneau-rest-server-tracing-otel, for example, wraps an io.opentelemetry.api.trace.Span plus its io.opentelemetry.context.Scope: setters translate to span attribute / status writes; close() ends the span and closes the OTel scope.

Since:
10.0.0

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes the span.
    default void
    recordRpcError(int code, String message)
    Records a JSON-RPC-level error outcome on this span.
    void
    setError(Throwable error)
    Records the exception (if any) the @RestOp handler threw on the span.
    void
    setStatusCode(int statusCode)
    Records the HTTP response status code on the span.

  • Method Details

    • setStatusCode

      void setStatusCode(int statusCode)
      Records the HTTP response status code on the span.

      Called by the framework after the @RestOp handler completes — before close(), and before setError(Throwable) if the handler also threw. Bridges typically translate the status into both a numeric attribute (e.g. OpenTelemetry's http.response.status_code) and an overall span status (HTTP 5xx maps to span-status ERROR; other codes map to UNSET per the OTel HTTP semantic conventions).

      Parameters:
      statusCode - The HTTP status code (e.g. 200, 404, 500).

    • setError

      void setError(Throwable error)
      Records the exception (if any) the @RestOp handler threw on the span.

      Called by the framework only when the handler threw — immediately before close(). Bridges typically record the throwable as a span event with the stack trace, set the span status to ERROR, and add an exception.type attribute carrying the exception's simple-name.

      Parameters:
      error - The exception thrown by the handler. Never null when this method is called.

    • close

      void close()
      Closes the span.

      Always called by the framework — via the standard finally-block contract on AutoCloseable — whether the handler returned normally or threw. Implementations must not throw checked exceptions; the close path runs in a finally where masking the original handler exception is unsafe. Implementations that need to surface bridge-level errors should log + swallow instead.

      Specified by:
      close in interface AutoCloseable

    • recordRpcError

      default void recordRpcError(int code, String message)
      Records a JSON-RPC-level error outcome on this span.

      A dated MCP adapter dispatches every request over HTTP 200, so an application-level JSON-RPC error (for example an unknown tool name) never reaches setStatusCode(int) with anything but 200 and never throws into setError(Throwable). This method gives such a caller a neutral way to observe that outcome on the span — called from the request-scoped tracing observation before a JSON-RPC error response is returned, distinct from both the HTTP status path and the thrown-exception path.

      Added as a source-compatible default so every existing Scope implementation keeps compiling unchanged. The default implementation is a no-op; a bridge that wants to classify JSON-RPC errors on the span (for example the OpenTelemetry bridge in juneau-rest-server-tracing-otel) overrides it.

      Parameters:
      code - The JSON-RPC error code (e.g. -32601).
      message - The JSON-RPC error message. May be null.