steffan-westcott.clj-otel.api.trace.http — com.github.steffan-westcott/clj-otel-api 0.1.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
                                {:keys [context]
                                 :or {context (context/current)}})

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: current context).

add-route-data! clj

(add-route-data! route)

(add-route-data! route
                 {:keys [context app-root] :or {context (context/current)}})

Adds data about the matched HTTP route to a server span, for example "/users/:user-id". May take an options map as follows:

key	description
:context	Context containing server span (default: 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-name! clj

(add-server-name! server-name)

(add-server-name! server-name {:keys [context] :or {context (context/current)}})

Adds server name server-name (if not nil) to server span data. May take an options map as follows:

key	description
:context	Context containing span to add server name to (default: current context).

add-server-span-response-data! clj

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

(add-server-span-response-data! response
                                {:keys [context]
                                 :or {context (context/current)}})

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: current context).

client-span-opts clj

(client-span-opts request)

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

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

server-span-interceptors clj

(server-span-interceptors)

(server-span-interceptors {:keys [create-span? set-current-context? server-name
                                  app-root captured-request-headers]
                           :or {set-current-context? true}})

Returns a vector of Pedestal interceptors that add HTTP server span support to subsequent execution of the interceptor chain for an HTTP service. Returned vector has metadata {:interceptors true} attached for convenient use in route specification. 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).

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.

No matter how the server span is created, the context containing the server span is set as 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).
:server-name	Primary server name of virtual host of this web application e.g. "app.market.com" (default: no server name).
: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 captured-request-headers]})

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).
:captured-request-headers	Down-cased names of request headers to be captured as span attributes (default: no headers captured).

wrap-server-span clj

(wrap-server-span handler)

(wrap-server-span handler
                  {:keys [create-span? server-name app-root
                          captured-request-headers]})

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.

No matter how the server span is created, for an asynchronous handler the context containing the server span is set as the value of :io.opentelemetry/server-span-context in the request map.

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).
:server-name	Primary server name of virtual host of this web application e.g. "app.market.com" (default: no server name).
: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).