# `ThousandIsland.Telemetry` [🔗](https://github.com/mtrudel/thousand_island/blob/main/lib/thousand_island/telemetry.ex#L1) The following telemetry spans are emitted by thousand_island ## `[:thousand_island, :listener, *]` Represents a Thousand Island server listening to a port This span is started by the following event: * `[:thousand_island, :listener, :start]` Represents the start of the span This event contains the following measurements: * `monotonic_time`: The time of this event, in `:native` units * `system_time`: The system time of this event, in `:native` units This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `local_address`: The IP address that the listener is bound to * `local_port`: The port that the listener is bound to * `transport_module`: The transport module in use * `transport_options`: Options passed to the transport module at startup This span is ended by the following event: * `[:thousand_island, :listener, :stop]` Represents the end of the span This event contains the following measurements: * `monotonic_time`: The time of this event, in `:native` units * `duration`: The span duration, in `:native` units This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `local_address`: The IP address that the listener is bound to * `local_port`: The port that the listener is bound to * `transport_module`: The transport module in use * `transport_options`: Options passed to the transport module at startup ## `[:thousand_island, :acceptor, *]` Represents a Thousand Island acceptor process listening for connections This span is started by the following event: * `[:thousand_island, :acceptor, :start]` Represents the start of the span This event contains the following measurements: * `monotonic_time`: The time of this event, in `:native` units * `system_time`: The system time of this event, in `:native` units This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `parent_telemetry_span_context`: The span context of the `:listener` which created this acceptor This span is ended by the following event: * `[:thousand_island, :acceptor, :stop]` Represents the end of the span This event contains the following measurements: * `monotonic_time`: The time of this event, in `:native` units * `duration`: The span duration, in `:native` units * `connections`: The number of client requests that the acceptor handled This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `parent_telemetry_span_context`: The span context of the `:listener` which created this acceptor * `error`: The error that caused the span to end, if it ended in error The following events may be emitted within this span: * `[:thousand_island, :acceptor, :spawn_error]` Thousand Island was unable to spawn a process to handle a connection. This occurs when too many connections are in progress (in which case you may want to look at increasing the `num_connections` configuration parameter), or when the configured handler failed to start (for example if its `init/1` returned `{:stop, reason}` or `:ignore`) This event contains the following measurements: * `monotonic_time`: The time of this event, in `:native` units * `error`: Present when a handler process failed to start; the reason the start failed. Not present when the connection limit was reached This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `[:thousand_island, :acceptor, :econnaborted]` Thousand Island was unable to spawn a process to handle a connection since the remote end closed before we could accept it. This usually occurs when it takes too long for your server to start processing a connection; you may want to look at tuning OS-level TCP parameters or adding more server capacity. This event contains the following measurements: * `monotonic_time`: The time of this event, in `:native` units This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `[:thousand_island, :acceptor, :accept_error]` Thousand Island encountered a transient network error while accepting a connection, of the kind that `accept(2)` documents as retryable (an error already pending on the incoming connection, such as `:ehostunreach` or `:enetdown`). These reflect a condition on one incoming connection rather than a problem with the listener, so the acceptor retries and keeps running rather than crashing. This event contains the following measurements: * `monotonic_time`: The time of this event, in `:native` units * `error`: The transient error reason that was retried This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `[:thousand_island, :acceptor, :emfile]` Thousand Island was unable to accept a connection because the system is out of file descriptors (`:emfile` or `:enfile`). The acceptor backs off briefly and keeps running rather than crashing. Persistent occurrences indicate that the OS file descriptor limit (`ulimit -n`) is too low, or that file descriptors are being leaked elsewhere in the node. This event contains the following measurements: * `monotonic_time`: The time of this event, in `:native` units * `error`: The specific error returned by accept: `:emfile` if the per-process descriptor limit was reached, or `:enfile` if the system-wide limit was reached This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span ## `[:thousand_island, :connection, *]` Represents Thousand Island handling a specific client request This span is started by the following event: * `[:thousand_island, :connection, :start]` Represents the start of the span This event contains the following measurements: * `monotonic_time`: The time of this event, in `:native` units * `system_time`: The system time of this event, in `:native` units This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `parent_telemetry_span_context`: The span context of the `:acceptor` span which accepted this connection * `remote_address`: The IP address of the connected client * `remote_port`: The port of the connected client This span is normally ended by the following event: * `[:thousand_island, :connection, :stop]` Represents the end of the span This event contains the following measurements: * `monotonic_time`: The time of this event, in `:native` units * `duration`: The span duration, in `:native` units * `send_oct`: The number of octets sent on the connection * `send_cnt`: The number of packets sent on the connection * `recv_oct`: The number of octets received on the connection * `recv_cnt`: The number of packets received on the connection This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `parent_telemetry_span_context`: The span context of the `:acceptor` span which accepted this connection * `remote_address`: The IP address of the connected client * `remote_port`: The port of the connected client * `error`: The error that caused the span to end, if it ended in error If `handle_connection/2` or `handle_data/3` raises, throws, or exits, the span is instead ended by: * `[:thousand_island, :connection, :exception]` Represents an exception which ended the span This event contains the following measurements: * `monotonic_time`: The time of this event, in `:native` units * `duration`: The span duration, in `:native` units This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `parent_telemetry_span_context`: The span context of the `:acceptor` span which accepted this connection * `remote_address`: The IP address of the connected client * `remote_port`: The port of the connected client * `kind`: The exception class (`:error`, `:throw`, or `:exit`) * `reason`: The exception reason * `stacktrace`: The exception stacktrace The following events may be emitted within this span: * `[:thousand_island, :connection, :ready]` Thousand Island has completed setting up the client connection This event contains the following measurements: * `monotonic_time`: The time of this event, in `:native` units This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `[:thousand_island, :connection, :async_recv]` Thousand Island has asynchronously received data from the client This event contains the following measurements: * `data`: The data received from the client This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `[:thousand_island, :connection, :recv]` Thousand Island has synchronously received data from the client This event contains the following measurements: * `data`: The data received from the client This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `[:thousand_island, :connection, :recv_error]` Thousand Island encountered an error reading data from the client This event contains the following measurements: * `error`: A description of the error This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `[:thousand_island, :connection, :send]` Thousand Island has sent data to the client This event contains the following measurements: * `data`: The data sent to the client This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `[:thousand_island, :connection, :send_error]` Thousand Island encountered an error sending data to the client This event contains the following measurements: * `data`: The data that was being sent to the client * `error`: A description of the error This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `[:thousand_island, :connection, :sendfile]` Thousand Island has sent a file to the client This event contains the following measurements: * `filename`: The filename containing data sent to the client * `offset`: The offset (in bytes) within the file sending started from * `bytes_written`: The number of bytes written This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `[:thousand_island, :connection, :sendfile_error]` Thousand Island encountered an error sending a file to the client This event contains the following measurements: * `filename`: The filename containing data that was being sent to the client * `offset`: The offset (in bytes) within the file where sending started from * `length`: The number of bytes that were attempted to send * `error`: A description of the error This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span * `[:thousand_island, :connection, :socket_shutdown]` Thousand Island has shutdown the client connection This event contains the following measurements: * `monotonic_time`: The time of this event, in `:native` units * `way`: The direction in which the socket was shut down This event contains the following metadata: * `telemetry_span_context`: A unique identifier for this span # `metadata` ```elixir @type metadata() :: :telemetry.event_metadata() ``` # `span_name` ```elixir @type span_name() :: :listener | :acceptor | :connection ``` # `t` ```elixir @type t() :: %ThousandIsland.Telemetry{ handler: module(), span_metadata: metadata(), span_name: span_name(), start_metadata: metadata(), start_time: integer(), telemetry_span_context: reference() } ``` # `monotonic_time` ```elixir @spec monotonic_time() :: integer() ``` --- *Consult [api-reference.md](api-reference.md) for complete listing*