Intercept B3 headers and join a sampled trace, or run a sampler to determine whether to start a new trace.

If starting a trace, a 'server receive' (sr) annotation will be added to the root span, as well as details about the request. A call-back is installed to finish the trace at the end of the request, adding additional http.status_code and a 'server send' (ss) annotations.

plug Tapper.Plug.Trace, sampler: Tapper.Plug.Sampler.Simple, percent: 25

or e.g.

plug Tapper.Plug.Trace, sampler: fn(conn, _config) -> String.starts_with?(conn.request_path, ["/foo", "/bar"]) end

Options

• sampler - name of module with sample?/2, or a fun with arity 2, to call to determine whether to sample a request; see Tapper.Plug.Sampler.
• debug - if set to true all requests, joined or started, will be sampled.
• tapper - keyword list passed on to Tapper.start/1 or Tapper.join/6 (useful for testing/debugging, but use with caution since overrides options set by this module).
• path_redactor - an {M, F, A} that will be used to redact the request_path when used in annotations.
• contextual - if set to true, propagates the Tapper.Id via Tapper.Ctx.put_context/1; defaults to false.

All options, including custom ones, will be passed to the sampler function (as a map), which means it can be configured here too.

Alternative Configuration

The debug flag can also be set via Application config using a :tapper_plug, :debug property, i.e. as returned from Application.get_env(:tapper_plug, :debug). This makes it easier to, for example, force traces in development, but not in production.

Annotations

Tapper.Plug sets the following annotations:

• sr - server receive on starting or joining a trace.
• ca - client address, from conn.remote_ip.
• http.host, http.method, http.path - from corresponding Plug.Conn fields.
• ss - server send when finishing a trace.

Redacting

The http.path annotation, and the name of the root span when starting a new trace, contain the Plug.Conn.request_path which may contain sensitive information. For this reason, the path can be passed through a redacting function, using the path_redactor option. The function is specfified using an {M, F, A}; the request_path is passed as the first argument, with other arguments appended.

plug Tapper.Plug.Trace, path_redactor: {MyUUIDRedactor, :path_redactor, []}

defmodule MyUUIDRedactor do
  def path_redactor(path) do
    Regex.replace(~r/[a-zA-Z]{8}-(([A-Za-z]{4}-){3})[a-zA-Z]{12}/, path, "**UUID**")
  end
end