README.md (2925B)
1 cowboy_telemetry 2 ===== 3 4 [](https://hex.pm/packages/cowboy_telemetry) 5 [](https://github.com/beam-telemetry/cowboy_telemetry/actions) 6 7 [Telemetry](https://github.com/beam-telemetry/telemetry) instrumentation for the [Cowboy](https://github.com/ninenines/cowboy) HTTP server. 8 9 This package contains a [`cowboy_stream`](https://ninenines.eu/docs/en/cowboy/2.8/manual/cowboy_stream/) handler that will instrument each request and emit `telemetry` events. 10 11 ## Usage 12 13 Configure your cowboy server with the `cowboy_telemetry_h` stream handler first. 14 15 ```erlang 16 cowboy:start_clear(http, [{port, Port}], #{ 17 env => #{dispatch => Dispatch}, 18 stream_handlers => [cowboy_telemetry_h, cowboy_stream_h] 19 }. 20 ``` 21 22 ## Telemetry Events 23 24 #### `[cowboy, request, start]` 25 26 A span event emitted at the beginning of a request. 27 28 * `measurements`: `#{system_time => erlang:system_time()}` 29 * `metadata`: `#{stream_id => cowboy_stream:streamid(), req => cowboy_req:req()}` 30 31 #### `[cowboy, request, stop]` 32 33 A span event emitted at the end of a request. 34 35 * `measurements`: `measurements()` 36 * `metadata`: `metadata()` 37 38 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`: 39 40 * `metadata`: `metadata()` + `#{error => cowboy_stream:reason()}` 41 42 #### `[cowboy, request, exception]` 43 44 A span event emitted if the request process exits. 45 46 * `measurements`: `measurements()` 47 * `metadata`: `metadata()` + `#{kind => exit, stacktrace => list()}` 48 49 #### `[cowboy, request, early_error]` 50 51 A single event emitted when Cowboy itself returns an `early_error` response before executing any handlers. 52 53 * `measurements`: `#{system_time => erlang:system_time(), resp_body_length => non_neg_integer()}` 54 * `metadata`: `metadata()` without `procs` or `informational` 55 56 ### Types 57 58 * `measurements()`: 59 * `duration :: req_start - req_end` see [`cowboy_metrics_h`](https://github.com/ninenines/cowboy/blob/master/src/cowboy_metrics_h.erl#L75) 60 * `req_body_duration :: req_body_start - req_body_end` see [`cowboy_metrics_h`](https://github.com/ninenines/cowboy/blob/master/src/cowboy_metrics_h.erl#L80) 61 * `resp_duration :: resp_start - resp_end` see [`cowboy_metrics_h`](https://github.com/ninenines/cowboy/blob/master/src/cowboy_metrics_h.erl#L87) 62 * `req_body_length :: non_neg_integer()` 63 * `resp_body_length :: non_neg_integer()` 64 * `metadata()`: 65 * `pid`, `streamid`, `req`, `resp_headers`, `resp_status`, and `ref` from `cowboy_metrics_h:metrics()` 66 * `cowboy_metrics_h:metrics()`: Defined in [`cowboy_metrics_h`](https://github.com/ninenines/cowboy/blob/master/src/cowboy_metrics_h.erl#L46) 67 68 Note: 69 70 * The `telemetry` handlers are executed from the cowboy connection process, not from the request process.