Centralized telemetry contract for Bourse.
Single source of truth for all telemetry events emitted by the library.
Both Bourse.HTTP and Bourse.CircuitBreaker delegate event names here.
Contract Version
Bumped on breaking changes to event names, measurements, or metadata shapes. Consumers can assert compatibility at startup.
Request Events
Emitted by Bourse.HTTP during HTTP request lifecycle.
[:bourse, :request, :start]
- Measurements:
%{system_time: integer()} - Metadata:
%{exchange: String.t(), method: atom(), path: String.t()}
[:bourse, :request, :stop]
- Measurements:
%{duration: integer()}(native time units) - Metadata:
%{exchange: String.t(), method: atom(), path: String.t(), status: integer()}
[:bourse, :request, :exception]
- Measurements:
%{duration: integer()}(native time units) - Metadata:
%{exchange: String.t(), method: atom(), path: String.t(), kind: atom(), reason: term()}
Circuit Breaker Events
Emitted by Bourse.CircuitBreaker on state transitions.
[:bourse, :circuit_breaker, :open]
- Measurements:
%{system_time: integer()} - Metadata:
%{exchange: String.t()}
[:bourse, :circuit_breaker, :closed]
- Measurements:
%{system_time: integer()} - Metadata:
%{exchange: String.t()}
[:bourse, :circuit_breaker, :rejected]
- Measurements:
%{system_time: integer()} - Metadata:
%{exchange: String.t()}
Rate Limiter Events
Emitted by Bourse.HTTP when rate limiting is triggered.
[:bourse, :rate_limiter, :throttled]
- Measurements:
%{delay_ms: integer(), cost: number()} - Metadata:
%{exchange: String.t()}
Signing Events
Emitted by Bourse.Signing.sign/4 (single event carrying duration; signing is a fast synchronous operation).
[:bourse, :signing, :sign]
- Measurements:
%{duration: integer()}(native time units) Metadata:
%{exchange: String.t() | nil, pattern: atom()}
WS Message Events
Emitted by Bourse.WS (outbound) and Bourse.WS.Adapter (inbound frames).
[:bourse, :ws, :send]
- Measurements:
%{system_time: integer()} Metadata:
%{exchange: String.t(), section: :public | :private}
[:bourse, :ws, :message]
- Measurements:
%{system_time: integer()} Metadata:
%{exchange: String.t(), section: :public | :private, kind: :routed | :system | :raw}
Summary
Functions
Attaches a handler to all Bourse telemetry events.
Event name for circuit breaker closed: [:bourse, :circuit_breaker, :closed].
Returns the 3 circuit breaker event names.
Event name for circuit breaker open: [:bourse, :circuit_breaker, :open].
Event name for circuit breaker rejected: [:bourse, :circuit_breaker, :rejected].
Returns the telemetry contract version.
Detaches a previously attached handler by ID.
Returns all telemetry event names.
Returns the rate limiter event names.
Event name for rate limiter throttled: [:bourse, :rate_limiter, :throttled].
Returns the 3 HTTP request event names.
Event name for request exception: [:bourse, :request, :exception].
Event name for request start: [:bourse, :request, :start].
Event name for request stop: [:bourse, :request, :stop].
Returns the signing event names (1 event).
Event name for signing (with duration): [:bourse, :signing, :sign].
Returns the 2 WS message event names.
Event name for WS message (inbound): [:bourse, :ws, :message].
Event name for WS send: [:bourse, :ws, :send].
Functions
@spec attach(String.t(), (list(), map(), map(), term() -> any()), term()) :: :ok | {:error, :already_exists}
Attaches a handler to all Bourse telemetry events.
Wraps :telemetry.attach_many/4 with events/0 as the event list.
Parameters
handler_id- Unique string identifying this handlerhandler_fn- Function of arity 4:(event, measurements, metadata, config)config- Optional handler config (default:nil)
@spec circuit_breaker_closed() :: [atom()]
Event name for circuit breaker closed: [:bourse, :circuit_breaker, :closed].
@spec circuit_breaker_events() :: [[atom()]]
Returns the 3 circuit breaker event names.
@spec circuit_breaker_open() :: [atom()]
Event name for circuit breaker open: [:bourse, :circuit_breaker, :open].
@spec circuit_breaker_rejected() :: [atom()]
Event name for circuit breaker rejected: [:bourse, :circuit_breaker, :rejected].
@spec contract_version() :: pos_integer()
Returns the telemetry contract version.
Bumped on breaking changes to event names, measurements, or metadata shapes.
if Bourse.Telemetry.contract_version() != 2 do
raise "Incompatible Bourse telemetry contract"
end@spec detach(String.t()) :: :ok | {:error, :not_found}
Detaches a previously attached handler by ID.
@spec events() :: [[atom()]]
Returns all telemetry event names.
@spec rate_limiter_events() :: [[atom()]]
Returns the rate limiter event names.
@spec rate_limiter_throttled() :: [atom()]
Event name for rate limiter throttled: [:bourse, :rate_limiter, :throttled].
@spec request_events() :: [[atom()]]
Returns the 3 HTTP request event names.
@spec request_exception() :: [atom()]
Event name for request exception: [:bourse, :request, :exception].
@spec request_start() :: [atom()]
Event name for request start: [:bourse, :request, :start].
@spec request_stop() :: [atom()]
Event name for request stop: [:bourse, :request, :stop].
@spec signing_events() :: [[atom()]]
Returns the signing event names (1 event).
@spec signing_sign() :: [atom()]
Event name for signing (with duration): [:bourse, :signing, :sign].
@spec ws_events() :: [[atom()]]
Returns the 2 WS message event names.
@spec ws_message() :: [atom()]
Event name for WS message (inbound): [:bourse, :ws, :message].
@spec ws_send() :: [atom()]
Event name for WS send: [:bourse, :ws, :send].