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

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.

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).

add-route-data! clj

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

(add-route-data! request-method
                 route
                 {:keys [context app-root] :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).
:app-root	Web application root, a URL prefix for all HTTP routes served by this application e.g. "/webshop" (default: nil).

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).

add-span-response-data! clj

(add-span-response-data! response
                         {:keys [context span-kind]
                          :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).

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

(exception-event-interceptor)

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?]
                           :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).

The interceptors 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.

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

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).
:app-root	Web application root, a URL prefix for all HTTP routes served by this application e.g. "/webshop" (default: no app root).
:captured-request-headers	Collection of down-cased names of request headers that are captured as attributes of manually created server spans (default: no headers captured).

server-span-opts clj

(server-span-opts request)

(server-span-opts request {:keys [app-root]})

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. May take an options map as follows:

key	description
:app-root	Web application root, a URL prefix for all HTTP routes served by this application e.g. "/webshop" (default: no app root).

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

(wrap-exception-event handler)

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.

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, for an asynchronous handler the bound context and key :io.opentelemetry/server-span-context in the request map 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 an existing server span created by OpenTelemetry instrumentation agent (default: false).
:app-root	Web application root, a URL prefix for all HTTP routes served by this application e.g. "/webshop" (default: no app root).
:captured-request-headers	Collection of down-cased names of request headers that are captured as attributes of manually created server spans (default: no headers captured).