steffan-westcott.clj-otel.api.trace.http — com.github.steffan-westcott/clj-otel-api 0.2.11-SNAPSHOT

Support for creating and populating HTTP client and server spans.

This namespace includes Ring middleware and Pedestal interceptors for working with HTTP server spans. Support is provided for working either with or without the OpenTelemetry instrumentation agent, and for synchronous or asynchronous HTTP request handlers.

wrap-server-span must be used before any other Ring middleware in this namespace.

server-span-interceptors must be used before any other Pedestal interceptors in this namespace.

add-client-span-response-data! clj

(add-client-span-response-data! response)

(add-client-span-response-data! response opts)

Adds data about the HTTP response to a manually created client span. May take an options map as follows:

key	description
:context	Context containing span to add response data to (default: bound or current context).
:response-header-attr?	Predicate for names of HTTP headers to add as attributes, or default nil where no attributes are added.

add-route-data! clj

(add-route-data! request-method route)

(add-route-data! request-method
                 route
                 {:keys [context] :or {context (context/dyn)}})

Adds data about the matched HTTP request-method and route to a server span, for example "GET /users/:user-id". request-method is a keyword corresponding to an HTTP request method; route is a string that may contain path parameters in any format. See also wrap-route and route-interceptor.

May take an options map as follows:

key	description
:context	Context containing server span (default: bound or current context).

add-server-span-response-data! clj

(add-server-span-response-data! response)

(add-server-span-response-data! response opts)

Adds data about the HTTP response to a manually created server span. May take an options map as follows:

key	description
:context	Context containing span to add response data to (default: bound or current context).
:response-header-attr?	Predicate for names of HTTP headers to add as attributes, or default nil where no attributes are added.

add-span-response-data! clj

(add-span-response-data! response
                         {:keys [context span-kind response-header-attr?]
                          :or {context (context/dyn)}})

Adds data about the HTTP response to a manually created client or server span. Takes an options map as follows:

key	description
:context	Context containing span to add response data to (default: bound or current context).
:span-kind	One of :client or :server (required).
:response-header-attr?	Predicate for names of HTTP headers to add as attributes, or default nil where no attributes are added.

as-error-type clj

(as-error-type e)

client-span-opts clj

(client-span-opts request)

(client-span-opts request {:keys [parent] :or {parent (context/dyn)}})

Returns a span options map (a parameter for steffan-westcott.clj-otel.api.trace.span/new-span!) for a manually created HTTP client span, where an HTTP request specified by Ring-style request map request is issued in the span scope. Only :method is used in request to populate the span. May take an options map as follows:

key	description
:parent	Context used to take parent span. If nil or no span is available in the context, the root context is used instead (default: use bound or current context).

exception-event-interceptor clj deprecated

(exception-event-interceptor)

DEPRECATED - OpenTelemetry no longer recommends to record exceptions that are handled and do not escape the scope of a span. exception-event-interceptor currently still records the exception, but will be stubbed out and later removed entirely in future clj-otel releases. See https://opentelemetry.io/docs/specs/semconv/attributes-registry/exception/#exception-escaped Returns an interceptor which adds an exception event to the server span. This is intended for use by applications which transform the exception to an HTTP response in a subsequent interceptor.

route-interceptor clj

(route-interceptor)

Returns a Pedestal interceptor that adds a matched route to the server span data and request map.

server-span-interceptors clj

(server-span-interceptors)

(server-span-interceptors {:keys [create-span? set-current-context?
                                  set-bound-context?]
                           :or {set-current-context? true}
                           :as create-span-opts})

Returns a vector of Pedestal interceptor maps that add HTTP server span support to subsequent execution of the interceptor chain for an HTTP service. These interceptors can be configured to either use existing server spans created by the OpenTelemetry instrumentation agent or manually create new server spans (when not using the agent).

server-span-interceptors must precede any other interceptors in this namespace. Also, they should prepend any others in the service map to ensure all HTTP requests are traced, including those without a matching route.

When :create-span? is false, for each request it is assumed the current context contains a server span created by the OpenTelemetry instrumentation agent. :set-current-context? is ignored in this case.

When :create-span? is true, for each request a new context containing a new server span is created, with parent context extracted from the HTTP request headers. In addition, if :set-current-context? is true the current context is set to the new context on interceptor entry and its original value is restored on exit; this is only appropriate if all requests are to be processed synchronously. Finally, if the HTTP response status code is 5xx then the span status error description is set to the value of :io.opentelemetry.api.trace.span.status/description in the response map and semantic attribute err.type is set to the string (or class name of Throwable) value of :io.opentelemetry.api.trace.span.attrs/error-type.

When :set-bound-context? is true, the bound context is set to the context containing the server span.

No matter how the server span is created, :io.opentelemetry/server-span-context in both the interceptor context and request maps are set to the context containing the server span.

May take an option map as follows:

key	description
:create-span?	When true, manually creates a new server span. Otherwise, assumes current context contains a server span created by OpenTelemetry instrumentation agent (default: false).
:set-current-context?	When true and :create-span? is also true, sets the current context to the context containing the created server span. Should only be set to true if all requests handled by this interceptor will be processed synchronously (default: true).
:set-bound-context?	When true, sets the bound context to the context containing the server span (default: false).
:request-header-attr?	Predicate that returns true for downcased keys of HTTP request headers to be captured as attributes of manually created server spans (default: no headers captured).
:response-header-attr?	Predicate that returns true for downcased keys of HTTP response headers to be captured as attributes of manually created server spans (default: no headers captured).
:captured-request-headers	Deprecated, use :request-header-attr? instead. Collection of down-cased HTTP request header keys to be captured.

server-span-opts clj

(server-span-opts request)

(server-span-opts request _opts)

Returns a span options map (a parameter for steffan-westcott.clj-otel.api.trace.span/new-span!) for a manually created HTTP server span, initiated by processing an HTTP request specified by Ring-style request map request.

wrap-compojure-route clj

(wrap-compojure-route handler)

Ring middleware to add matched Compojure route to the server span data and Ring request map. Use compojure.core/wrap-routes to apply this middleware to all route handlers.

wrap-exception-event clj deprecated

(wrap-exception-event handler')

DEPRECATED - OpenTelemetry no longer recommends to record exceptions that are handled and do not escape the scope of a span. wrap-exception-event currently still records the exception, but will be stubbed out and later removed entirely in future clj-otel releases. See https://opentelemetry.io/docs/specs/semconv/attributes-registry/exception/#exception-escaped Consider using steffan-westcott.clj-otel.api.trace.span/wrap-span or steffan-westcott.clj-otel.api.trace.span/wrap-bound-span instead to record uncaught exceptions before they are transformed.

Ring middleware to add an exception event to the server span. This is intended for use by applications which transform the exception to an HTTP response in a subsequent middleware.

wrap-reitit-route clj

(wrap-reitit-route handler)

Ring middleware to add matched Reitit route to the server span data and Ring request map. This assumes reitit.ring/ring-handler is used with option :inject-match? set to true (which is the default).

wrap-route clj

(wrap-route handler' route-fn)

Ring middleware to add a matched route to the server span data and Ring request map. route-fn is a function which given a request returns the matched route as a string, or nil if no match.

wrap-server-span clj

(wrap-server-span handler)

(wrap-server-span handler {:keys [create-span?] :as create-span-opts})

Ring middleware to add HTTP server span support. This middleware can be configured to either use existing server spans created by the OpenTelemetry instrumentation agent or manually create new server spans (when not using the agent). Both synchronous (1-arity) and asynchronous (3-arity) Ring handlers are supported.

wrap-server-span must be used before any other Ring middleware in this namespace. Also, placing this before any routing middleware ensures all HTTP requests are traced, including those without a matching route.

When :create-span? is false, for each request it is assumed the current context contains a server span created by the OpenTelemetry instrumentation agent.

When :create-span? is true, for each request a new context containing a new server span is created, with parent context extracted from the HTTP request headers. For a synchronous handler, the current context is set to the new context during request processing and restored to its original value on completion. Finally, if the HTTP response status code is 5xx then the span status error description is set to the value of :io.opentelemetry.api.trace.span.status/description in the response map and semantic attribute err.type is set to the string (or class name of Throwable) value of :io.opentelemetry.api.trace.span.attrs/error-type.

No matter how the server span is created, key :io.opentelemetry/server-span-context in the request map is set to the context containing the server span. For asynchronous handlers, the bound context is also set.

May take an option map as follows:

key	description
:create-span?	When true, manually creates a new server span. Otherwise, assumes current context contains an existing server span created by OpenTelemetry instrumentation agent (default: false).
:request-header-attr?	Predicate that returns true for downcased keys of HTTP request headers to be captured as attributes of manually created server spans (default: no headers captured).
:response-header-attr?	Predicate that returns true for downcased keys of HTTP response headers to be captured as attributes of manually created server spans (default: no headers captured).
:captured-request-headers	Deprecated, use :request-header-attr? instead. Collection of down-cased HTTP request header keys to be captured.