View Source Wayfarer.Telemetry (wayfarer v0.6.0)

Wayfarer emits a number of telemetry events and spans on top of the excellent telemetry events emitted by Bandit.Telemetry.

Summary

Types

The time passed since the beginning of the span, in :native time units.

A convenience type for describing telemetry events

The [:wayfarer, :health_check, :connect] event.

The [:wayfarer, :health_check, :fail] event.

The [:wayfarer, :health_check, :pass] event.

The [:wayfarer, :health_check, :request] event.

All the event types that make up the [:wayfarer, :health_check, :*] span.

The [:wayfarer, :health_check, :start] event.

Information about the listener that received the request.

The time that the event was emitted, in :native time units.

The [:wayfarer, :request, :client_frame] event.

The [:wayfarer, :request, :exception] event.

The [:wayfarer, :request, :received_status] event.

The [:wayfarer, :request, :req_body_chunk] event.

The [:wayfarer, :request, :resp_body_chunk] event.

The [:wayfarer, :request, :resp_started] event.

The [:wayfarer, :request, :routed] event.

The [:wayfarer, :request, :server_frame] event.

All the event types that make up the [:wayfarer, :request, :*] span.

The [:wayfarer, :request, :start] event.

The [:wayfarer, :request, :stop] event.

The [:wayfarer, :request, :upgraded] event.

All the spans that can be emitted by Wayfarer.

Information about the target a request has been routed to.

A unique identifier for the span

The HTTP protocol version of the request

Types

@type duration() :: integer()

The time passed since the beginning of the span, in :native time units.

The difference between the current monotonic_time and the first monotonic_time at the start of the span.

Link to this opaque

event(measurements, metadata)

View Source
@opaque event(measurements, metadata)

A convenience type for describing telemetry events

Link to this type

health_check_connect()

View Source
@type health_check_connect() ::
  event(
    %{
      monotonic_time: monotonic_time(),
      wallclock_time: DateTime.t(),
      duration: duration()
    },
    %{
      telemetry_span_context: telemetry_span_context(),
      hostname: String.t(),
      uri: URI.t(),
      target: target(),
      method: String.t(),
      transport: transport()
    }
  )

The [:wayfarer, :health_check, :connect] event.

This event signals that the outgoing TCP connection has been made to the target.

@type health_check_fail() ::
  event(
    %{
      monotonic_time: monotonic_time(),
      wallclock_time: DateTime.t(),
      duration: duration(),
      reason: any()
    },
    %{
      telemetry_span_context: telemetry_span_context(),
      hostname: String.t(),
      uri: URI.t(),
      target: target(),
      method: String.t(),
      transport: transport()
    }
  )

The [:wayfarer, :health_check, :fail] event.

This event signals that the HTTP status code returned by the target did not match any of the configured success codes.

It also signals the end of the span.

@type health_check_pass() ::
  event(
    %{
      monotonic_time: monotonic_time(),
      wallclock_time: DateTime.t(),
      duration: duration(),
      status: 100..599
    },
    %{
      telemetry_span_context: telemetry_span_context(),
      hostname: String.t(),
      uri: URI.t(),
      target: target(),
      method: String.t(),
      transport: transport()
    }
  )

The [:wayfarer, :health_check, :pass] event.

This event signals that the HTTP status code returned by the target matches one of the configured success codes.

It also signals the end of the span.

Link to this type

health_check_request()

View Source
@type health_check_request() ::
  event(
    %{
      monotonic_time: monotonic_time(),
      wallclock_time: DateTime.t(),
      duration: duration()
    },
    %{
      telemetry_span_context: telemetry_span_context(),
      hostname: String.t(),
      uri: URI.t(),
      target: target(),
      method: String.t(),
      transport: transport()
    }
  )

The [:wayfarer, :health_check, :request] event.

This event signals that the HTTP or WebSocket request has been sent.

@type health_check_span() ::
  health_check_start()
  | health_check_request()
  | health_check_pass()
  | health_check_fail()

All the event types that make up the [:wayfarer, :health_check, :*] span.

@type health_check_start() ::
  event(
    %{monotonic_time: monotonic_time(), wallclock_time: DateTime.t()},
    %{
      telemetry_span_context: telemetry_span_context(),
      hostname: String.t(),
      uri: URI.t(),
      target: target(),
      method: String.t()
    }
  )

The [:wayfarer, :health_check, :start] event.

This event signals the start of a health check span.

You can use the telemetry_span_context metadata value to correlate subsequent events within the same span.

@type listener() :: %{
  scheme: :http | :https,
  module: module(),
  port: :socket.port_number(),
  address: :inet.ip_address()
}

Information about the listener that received the request.

@type monotonic_time() :: integer()

The time that the event was emitted, in :native time units.

This is sources from System.monotonic_time/0 which has some caveats but in general is better for calculating durations as it should never go backwards.

Link to this type

request_client_frame()

View Source
@type request_client_frame() ::
  event(
    %{
      :monotonic_time => monotonic_time(),
      :duration => duration(),
      :wallclock_time => DateTime.t(),
      :frame_size => non_neg_integer(),
      :client_frame_bytes => non_neg_integer(),
      :client_frame_count => non_neg_integer(),
      optional(:server_frame_bytes) => non_neg_integer(),
      optional(:server_frame_count) => non_neg_integer()
    },
    %{
      conn: Plug.Conn.t(),
      listener: listener(),
      transport: transport(),
      telemetry_span_context: telemetry_span_context(),
      target: target(),
      algorithm: Wayfarer.Target.Selector.algorithm(),
      status: nil | 100..599,
      opcode: :text | :binary | :ping | :pong | :close
    }
  )

The [:wayfarer, :request, :client_frame] event.

This event is emitted any time a WebSocket frame is received from the client for transmission to the target.

@type request_exception() ::
  event(
    %{
      monotonic_time: monotonic_time(),
      duration: duration(),
      wallclock_time: DateTime.t()
    },
    %{
      :conn => Plug.Conn.t(),
      :listener => listener(),
      :transport => transport(),
      :telemetry_span_context => telemetry_span_context(),
      optional(:target) => target(),
      optional(:algorithm) => Wayfarer.Target.Selector.algorithm(),
      kind: :throw | :exit | :error | :exception,
      reason: any(),
      stacktrace: Exception.stacktrace()
    }
  )

The [:wayfarer, :request, :exception] event.

This event signals that something went wrong while processing the event. You will likely still receive other events (eg :stop) for this span however.

Link to this type

request_received_status()

View Source
@type request_received_status() ::
  event(
    %{
      :monotonic_time => monotonic_time(),
      :duration => duration(),
      :wallclock_time => DateTime.t(),
      :status => nil | 100..599,
      optional(:req_body_bytes) => non_neg_integer()
    },
    %{
      conn: Plug.Conn.t(),
      listener: listener(),
      transport: transport(),
      telemetry_span_context: telemetry_span_context(),
      target: target(),
      algorithm: Wayfarer.Target.Selector.algorithm(),
      status: nil | 100..599
    }
  )

The [:wayfarer, :request, :received_status] event.

This event signals that an HTTP status code has been received from the upstream target.

Link to this type

request_req_body_chunk()

View Source
@type request_req_body_chunk() ::
  event(
    %{
      monotonic_time: monotonic_time(),
      duration: duration(),
      wallclock_time: DateTime.t(),
      status: nil | 100..599,
      req_body_bytes: non_neg_integer(),
      req_body_chunks: non_neg_integer(),
      chunk_bytes: non_neg_integer()
    },
    %{
      conn: Plug.Conn.t(),
      listener: listener(),
      transport: transport(),
      telemetry_span_context: telemetry_span_context(),
      target: target(),
      algorithm: Wayfarer.Target.Selector.algorithm(),
      status: nil | 100..599
    }
  )

The [:wayfarer, :request, :req_body_chunk] event.

This event is emitted while streaming the request body from the client to the target. Under the hood Plug.Conn.read_body/2 is being called with the default options, meaning that each chunk is likely to be up to 8MB in size.

If there is no request body then this event will not be emitted and the req_body_bytes and req_body_chunks counters will both be set to zero for this request.

Link to this type

request_resp_body_chunk()

View Source
@type request_resp_body_chunk() ::
  event(
    %{
      :monotonic_time => monotonic_time(),
      :duration => duration(),
      :wallclock_time => DateTime.t(),
      optional(:req_body_bytes) => non_neg_integer(),
      optional(:req_body_chunks) => non_neg_integer(),
      resp_body_bytes: non_neg_integer(),
      resp_body_chunks: non_neg_integer(),
      chunk_bytes: non_neg_integer()
    },
    %{
      conn: Plug.Conn.t(),
      listener: listener(),
      transport: transport(),
      telemetry_span_context: telemetry_span_context(),
      target: target(),
      algorithm: Wayfarer.Target.Selector.algorithm(),
      status: nil | 100..599
    }
  )

The [:wayfarer, :request, :resp_body_chunk] event.

This event is emitted every time a chunk of response body is received from the target for streaming to the client. Under the hood, these are emitted every time Mint.HTTP.stream/2 returns a data frame.

Link to this type

request_resp_started()

View Source
@type request_resp_started() ::
  event(
    %{
      :monotonic_time => monotonic_time(),
      :duration => duration(),
      :wallclock_time => DateTime.t(),
      :status => nil | 100..599,
      optional(:req_body_bytes) => non_neg_integer(),
      optional(:req_body_chunks) => non_neg_integer()
    },
    %{
      conn: Plug.Conn.t(),
      listener: listener(),
      transport: transport(),
      telemetry_span_context: telemetry_span_context(),
      target: target(),
      algorithm: Wayfarer.Target.Selector.algorithm(),
      status: nil | 100..599
    }
  )

The [:wayfarer, :request, :resp_started] event.

This event indicates that the HTTP status and headers have been received from the target and the response will now start being sent to the target.

@type request_routed() ::
  event(
    %{
      monotonic_time: monotonic_time(),
      duration: duration(),
      wallclock_time: DateTime.t()
    },
    %{
      conn: Plug.Conn.t(),
      listener: listener(),
      transport: transport(),
      telemetry_span_context: telemetry_span_context(),
      target: target(),
      algorithm: Wayfarer.Target.Selector.algorithm()
    }
  )

The [:wayfarer, :request, :routed] event.

This event signals that the routing process has completed and a target has been chosen to serve the request.

Link to this type

request_server_frame()

View Source
@type request_server_frame() ::
  event(
    %{
      :monotonic_time => monotonic_time(),
      :duration => duration(),
      :wallclock_time => DateTime.t(),
      :frame_size => non_neg_integer(),
      :server_frame_bytes => non_neg_integer(),
      :server_frame_count => non_neg_integer(),
      optional(:client_frame_bytes) => non_neg_integer(),
      optional(:client_frame_count) => non_neg_integer()
    },
    %{
      conn: Plug.Conn.t(),
      listener: listener(),
      transport: transport(),
      telemetry_span_context: telemetry_span_context(),
      target: target(),
      algorithm: Wayfarer.Target.Selector.algorithm(),
      status: nil | 100..599
    }
  )

The [:wayfarer, :request, :server_frame] event.

This event is emitted any time a WebSocket frame is received from the target for transmission to the client.

All the event types that make up the [:wayfarer, :request, :*] span.

@type request_start() ::
  event(
    %{monotonic_time: monotonic_time(), wallclock_time: DateTime.t()},
    %{
      conn: Plug.Conn.t(),
      listener: listener(),
      transport: transport(),
      telemetry_span_context: telemetry_span_context()
    }
  )

The [:wayfarer, :request, :start] event.

This event signals the start of a request span tracking a client request to completion.

You can use the telemetry_span_context metadata value to correlate subsequent events within the same span.

@type request_stop() ::
  event(
    %{
      :monotonic_time => monotonic_time(),
      :duration => duration(),
      :wallclock_time => DateTime.t(),
      :status => nil | 100..599,
      optional(:req_body_bytes) => non_neg_integer(),
      optional(:resp_body_bytes) => non_neg_integer(),
      optional(:client_frame_bytes) => non_neg_integer(),
      optional(:client_frame_count) => non_neg_integer(),
      optional(:server_frame_bytes) => non_neg_integer(),
      optional(:server_frame_count) => non_neg_integer()
    },
    %{
      :conn => Plug.Conn.t(),
      :listener => listener(),
      :transport => transport(),
      :telemetry_span_context => telemetry_span_context(),
      optional(:target) => target(),
      optional(:algorithm) => Wayfarer.Target.Selector.algorithm(),
      optional(:status) => nil | 100..599,
      optional(:kind) => :throw | :exit | :error | :exception,
      optional(:reason) => any(),
      optional(:stacktrace) => Exception.stacktrace()
    }
  )

The [:wayfarer, :request, :stop] event.

This event signals that the request has completed.

The measurements will contain any incrementing counters accumulated during the course of the request.

@type request_upgraded() ::
  event(
    %{
      monotonic_time: monotonic_time(),
      duration: duration(),
      wallclock_time: DateTime.t()
    },
    %{
      conn: Plug.Conn.t(),
      listener: listener(),
      transport: transport(),
      telemetry_span_context: telemetry_span_context(),
      target: target(),
      algorithm: Wayfarer.Target.Selector.algorithm(),
      status: nil | 100..599
    }
  )

The [:wayfarer, :request, :upgraded] event.

This event is emitted when a client connection is upgraded to a WebSocket connection.

@type spans() :: request_span() | health_check_span()

All the spans that can be emitted by Wayfarer.

@type target() ::
  %{
    scheme: :http | :https | :ws | :wss,
    address: :inet.ip_address(),
    port: :socket.port_number()
  }
  | %{scheme: :plug, module: module(), options: any()}

Information about the target a request has been routed to.

Link to this type

telemetry_span_context()

View Source
@type telemetry_span_context() :: reference()

A unique identifier for the span

@type transport() :: :http1 | :http2

The HTTP protocol version of the request