View Source OpentelemetryBandit (opentelemetry_bandit v0.2.0)

OpenTelemetry instrumentation for Bandit.

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:

opt_ins = [SemConv.HTTPAttributes.http_request_body_size()]`
OpentelemetryBandit.setup(opt_in_attrs: opt_ins)

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.

OpentelemetryBandit.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 conn 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:

defmodule PublicEndpoint do
  def is_public_request?(conn, opts) do
    # return true if request was public
  end
end

OpentelemetryBandit.setup(public_endpoint_fn: {PublicEndpoint, :is_public_request?, []})

Summary

Types

Use semantic conventions library to ensure compatability, e.g. HTTPAttributes.http_request_body_size()

Functions

Initializes and configures the telemetry handlers.

Types

@type opt_in_attr() ::
  :"client.port"
  | :"http.request.body.size"
  | :"http.response.body.size"
  | :"network.local.address"
  | :"network.local.port"
  | :"network.transport"

Use semantic conventions library to ensure compatability, e.g. HTTPAttributes.http_request_body_size()

@type opt_in_attrs() :: [opt_in_attr()]
@type options() :: [
  opt_in_attrs: opt_in_attrs(),
  handler_id: atom(),
  client_address_headers: [binary()],
  client_headers_sort_fn: (term(), term() -> term()),
  public_endpoint: boolean(),
  public_endpoint_fn: {module(), atom(), [term()]},
  request_headers: [binary()],
  response_headers: [binary()],
  scheme_headers: [binary()],
  scheme_headers_sort_fn: (term(), term() -> term()),
  server_address_headers: [binary()],
  server_headers_sort_fn: (term(), term() -> term())
]

Functions

@spec setup(any()) :: :ok

Initializes and configures the telemetry handlers.

Supported options:

  • :opt_in_attrs - Use semantic conventions library to ensure compatability, e.g. [HTTPAttributes.http_request_body_size()]

    • :"client.port"

    • :"http.request.body.size"

    • :"http.response.body.size"

    • :"network.local.address"

    • :"network.local.port"

    • :"network.transport"

    The default value is [].

  • :handler_id (atom/0) - Only set when running multiple instances on different endpoints The default value is :otel_bandit.

  • :client_address_headers (list of String.t/0) - Headers to use for extracting original client request address info The default value is ["forwarded", "x-forwarded-for"].

  • :client_headers_sort_fn (function of arity 2) - Custom client header sort fn. See otel_http for more info

  • :public_endpoint (boolean/0) - Endpoint is public. Propagated traces will be added as a link. The default value is false.

  • :public_endpoint_fn - Default function returns false. See docs for more info The default value is {OpentelemetryBandit, :default_public_endpoint_fn, []}.

  • :request_headers (list of String.t/0) - List of request headers to add as attributes. (lowercase) The default value is [].

  • :response_headers (list of String.t/0) - List of response headers to add as attributes. (lowercase) The default value is [].

  • :scheme_headers (list of String.t/0) - Headers to use for extracting original client request scheme The default value is ["forwarded", "x-forwarded-proto"].

  • :scheme_headers_sort_fn (function of arity 2) - Custom scheme header sort fn. See otel_http for more info

  • :server_address_headers (list of String.t/0) - Headers to use for extracting original server address info The default value is ["forwarded", "x-forwarded-host", "host"].

  • :server_headers_sort_fn (function of arity 2) - Custom server header sort fn. See otel_http for more info