View Source opentelemetry_cowboy (opentelemetry_cowboy v1.0.0)

OpenTelemetry instrumentation for cowboy.

Semantic Conventions

All required and recommended Server HTTP Span semantic conventions are implemented. Supported opt-in attributes can be configured using the opt_in_attrs option.

Options

Opt-in Semantic Convention Attributes

Otel SemConv requires users to explicitly opt in for any attribute with a requirement level of opt-in. To ensure compatability, always use the SemConv attribute.

Example:

OptInAttrs = [{?HTTP_REQUEST_BODY_SIZE, true}]`
opentelemetry_cowboy:setup(#{opt_in_attrs => OptInAttrs)

Request and Response Headers as Opt-in Attributes

Request and response header attributes are opt-in and can be set with the request_headers and response_headers options. Values should be lower-case.

opentelemetry_cowboy:setup(#{request_headers => ["x-customer-id"]})

Public Endpoint

Setting an endpoint as public will result in any propagated trace to be added as a link, rather than a continuation of an existing trace. The public_endpoint option should be set to true if an endpoint only accepts public traffic to prevent missing root spans. By default, the endpoint is handled as non-public, resulting in traces being continued rather than linked.

In a mixed traffic environment, an MFA can be supplied to determine whether to treat a request as public. This function is executed on every request, so refrain from expensive operations such as lookups to external systems. The function must be a predicate function of arity-2, accepting the Req from the request as the first argument and user-supplied options as the second. Any dynamic information used in comparisons should be supplied at setup time for efficiency.

Example:

-module(public_endpoint).

is_public_request(Req, Opts) ->
    # return true if request was public

opentelemetry_cowboy:setup(#{public_endpoint_fn => {public_endpoint, fun is_public_request/2, []}}).

Summary

Functions

Initializes and configures the telemetry handlers.

Functions

Link to this function

default_public_endpoint_fn/2

View Source
-spec setup() -> ok.

Initializes and configures the telemetry handlers.

Supported options:

  • client_address_headers - Headers to use for extracting original client request address info. Default: [<<"forwarded">>, <<"x-forwarded-for">>]
  • client_headers_sort_fn - Custom client header sort fn. See otel_http for more info. Default: undefined
  • handler_id - Only set when running multiple instances on different endpoints. Default: otel_cowboy
  • opt_in_attrs - Use semantic conventions library to ensure compatability, e.g. [{?HTTP_REQUEST_BODY_SIZE, true}]. Default: []
  • public_endpoint - Endpoint is public. Propagated traces will be added as a link. Default: false
  • public_endpoint_fn - Default function returns false. See docs for more info.
  • request_headers - List of request headers to add as attributes. (lowercase). Default: []
  • response_headers - List of response headers to add as attributes. (lowercase). Default: []
  • scheme_headers - Headers to use for extracting original client request scheme. Default: [<<"forwarded">>, <<"x-forwarded-proto">>]
  • scheme_headers_sort_fn - Custom scheme header sort fn. See otel_http for more info. Default: undefined
  • server_address_headers - Headers to use for extracting original server address info. Default: [<<"forwarded">>, <<"x-forwarded-host">>, <<"host">>]
  • server_address_headers_sort_fn - Custom server header sort fn. See otel_http for more info. Default: undefined
-spec setup([] | map()) -> ok.