cat-bookmarker/deps/cowboy_telemetry/README.md

cowboy_telemetry

Telemetry instrumentation for the Cowboy HTTP server.

This package contains a cowboy_stream handler that will instrument each request and emit telemetry events.

Usage

Configure your cowboy server with the cowboy_telemetry_h stream handler first.

cowboy:start_clear(http, [{port, Port}], #{
    env => #{dispatch => Dispatch},
    stream_handlers => [cowboy_telemetry_h, cowboy_stream_h]
}.

Telemetry Events

[cowboy, request, start]

A span event emitted at the beginning of a request.

• measurements: #{system_time => erlang:system_time()}
• metadata: #{stream_id => cowboy_stream:streamid(), req => cowboy_req:req()}

[cowboy, request, stop]

A span event emitted at the end of a request.

• measurements: measurements()
• metadata: metadata()

If the request is terminated early - by the client or by the server - before a response is sent, the metadata will also contain an error:

• metadata: metadata() + #{error => cowboy_stream:reason()}

[cowboy, request, exception]

A span event emitted if the request process exits.

• measurements: measurements()
• metadata: metadata() + #{kind => exit, stacktrace => list()}

[cowboy, request, early_error]

A single event emitted when Cowboy itself returns an early_error response before executing any handlers.

• measurements: #{system_time => erlang:system_time(), resp_body_length => non_neg_integer()}
• metadata: metadata() without procs or informational

Types

• measurements():
  • duration :: req_start - req_end see cowboy_metrics_h
  • req_body_duration :: req_body_start - req_body_end see cowboy_metrics_h
  • resp_duration :: resp_start - resp_end see cowboy_metrics_h
  • req_body_length :: non_neg_integer()
  • resp_body_length :: non_neg_integer()
• metadata():
  • pid, streamid, req, resp_headers, resp_status, and ref from cowboy_metrics_h:metrics()
• cowboy_metrics_h:metrics(): Defined in cowboy_metrics_h

Note:

• The telemetry handlers are executed from the cowboy connection process, not from the request process.