plushie/telemetry

Telemetry event emission.

On BEAM, wraps the Erlang telemetry library. Event names, measurements, and metadata are accepted only when their names are known to the SDK. Unknown events are discarded, and unknown measurement or metadata keys are omitted. On JavaScript, all functions are no-ops (events are silently discarded).

Usage

import gleam/dict
import gleam/dynamic
import plushie/telemetry

telemetry.execute(
  ["plushie", "bridge", "send"],
  dict.from_list([#("byte_size", dynamic.from(42))]),
  dict.new(),
)

Values

attach

</>

pub fn attach(
  handler_id: String,
  event_name: List(String),
  handler: fn(
    List(String),
    dict.Dict(String, dynamic.Dynamic),
    dict.Dict(String, dynamic.Dynamic),
  ) -> Nil,
  config: dynamic.Dynamic,
) -> Result(Nil, dynamic.Dynamic)

Attach a handler for a telemetry event.

The handler function receives the event name, measurements, metadata, and the config value passed here.

Returns Ok(Nil) on success, Error(reason) if the handler ID is already in use or the event name is not a known SDK event. Unknown event names return Error(unknown_telemetry_event) on BEAM.

detach

</>

pub fn detach(handler_id: String) -> Nil

Detach a previously attached handler by ID.

execute

</>

pub fn execute(
  event_name: List(String),
  measurements: dict.Dict(String, dynamic.Dynamic),
  metadata: dict.Dict(String, dynamic.Dynamic),
) -> Nil

Emit a telemetry event.

event_name: list of strings identifying a known SDK event, e.g. ["plushie", "bridge", "send"].
measurements: known numeric measurements such as byte_size or duration_ms.
metadata: known contextual information such as reason.

Unknown event names are discarded. Unknown measurement and metadata keys are omitted before the event is sent to the BEAM telemetry library.

span

</>

pub fn span(
  event_name: List(String),
  metadata: dict.Dict(String, dynamic.Dynamic),
  work: fn() -> a,
) -> a

Execute a function and emit telemetry start/stop events with timing.

Emits event_name ++ ["start"] before and event_name ++ ["stop"] after the function runs. The stop event includes a duration_ms measurement (as a Dynamic integer).

Returns the function’s result.