Hell.Telemetry (Hell v0.1.0)

Copy Markdown View Source

The following telemetry spans are emitted by hell

[:hell, :listener, *]

Represents a Hell server listening to a port

This span is started by the following event:

  • [:hell, :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:

  • [:hell, :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

[:hell, :acceptor, *]

Represents a Hell acceptor process listening for connections

This span is started by the following event:

  • [:hell, :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:

  • [:hell, :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:

  • [:hell, :acceptor, :spawn_error]

    Hell 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

  • [:hell, :acceptor, :econnaborted]

    Hell 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

  • [:hell, :acceptor, :accept_error]

    Hell 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

  • [:hell, :acceptor, :emfile]

    Hell 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

[:hell, :connection, *]

Represents Hell handling a specific client request

This span is started by the following event:

  • [:hell, :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:

  • [:hell, :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:

  • [:hell, :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:

  • [:hell, :connection, :ready]

    Hell 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

  • [:hell, :connection, :async_recv]

    Hell 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

  • [:hell, :connection, :recv]

    Hell 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

  • [:hell, :connection, :recv_error]

    Hell 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

  • [:hell, :connection, :send]

    Hell 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

  • [:hell, :connection, :send_error]

    Hell 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

  • [:hell, :connection, :sendfile]

    Hell 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

  • [:hell, :connection, :sendfile_error]

    Hell 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

  • [:hell, :connection, :socket_shutdown]

    Hell 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

Summary

Types

metadata()
span_name()
t()

Functions

monotonic_time()

See System.monotonic_time/0.

Types

metadata()

@type metadata() :: :telemetry.event_metadata()

span_name()

@type span_name() :: :listener | :acceptor | :connection

t()

@type t() :: %Hell.Telemetry{
  handler: module(),
  span_metadata: metadata(),
  span_name: span_name(),
  start_metadata: metadata(),
  start_time: integer(),
  telemetry_span_context: reference()
}

Functions

monotonic_time()

@spec monotonic_time() :: integer()

See System.monotonic_time/0.