Crosswake.Telemetry (crosswake v0.2.0)

Canonical public API for Crosswake telemetry events.

events/0 returns the runtime-aggregated catalog of every :telemetry event Crosswake emits across companion spans, doctor, threadline, sigra, and chimeway subsystems. Call it at runtime — not at compile time.

Telemetry events are public API: additions are non-breaking minors; removals or renames are breaking majors requiring a semver major bump.

Diagnostic-only. This module is NOT an APM replacement, NOT a distributed tracing framework, and NOT a generic event bus. It augments host observability by exposing a typed, low-cardinality, PII-free event catalog. It coexists with any host-side observability pipeline.

Zero new dependencies — only :telemetry, already a project dependency.

Summary

Types

event_doc()

A self-describing telemetry event catalog entry.

Functions

attach_default_logger(level_or_opts \\ [])

Attaches a structured default logger to all :active Crosswake telemetry events.

baseline_forbidden_metadata_keys()

Returns the 11-atom baseline PII forbidden-metadata-key denylist owned by core.

detach_default_logger()

Detaches the default Crosswake telemetry logger handler.

events()

Returns the runtime-aggregated catalog of all Crosswake telemetry events.

Types

event_doc()

@type event_doc() :: %{
  event: [atom()],
  tier: :active | :reserved,
  description: String.t(),
  measurements: [atom()],
  metadata: [atom()]
}

A self-describing telemetry event catalog entry.

event — the event name prefix as an atom list (without :start/:stop/:exception suffix)
tier — :active means the event is emitted; :reserved means declared but not yet emitted
description — a calm, specific description of what the event signals
measurements — list of measurement key atoms emitted in the measurement map
metadata — list of metadata key atoms emitted in the metadata map (key names only, no PII values)

Functions

attach_default_logger(level_or_opts \\ [])

@spec attach_default_logger(Logger.level() | keyword()) ::
  :ok | {:error, :already_exists}

Attaches a structured default logger to all :active Crosswake telemetry events.

Accepts a Logger.level() atom or a keyword list of options:

:level — log level for non-exception events (default: :info)
:encode — when true, JSON-encodes the event map into the log message; when false (default, D-14), places the structured map in Logger metadata so host formatters can handle JSON encoding (D-14).

Attaches under handler id "crosswake-default-logger". Returns :ok on success; returns {:error, :already_exists} if the handler is already attached (D-13: relies on :telemetry's built-in guard — no custom double-attach guard added here).

Core never calls this function automatically. Attachment is always the host's explicit decision (TELEM-03 / D-13).

Examples

# Attach with default opts (level: :info, encode: false)
Crosswake.Telemetry.attach_default_logger()

# Attach with a specific log level
Crosswake.Telemetry.attach_default_logger(:debug)

# Attach with keyword options
Crosswake.Telemetry.attach_default_logger(level: :info, encode: false)

baseline_forbidden_metadata_keys()

@spec baseline_forbidden_metadata_keys() :: [atom()]

Returns the 11-atom baseline PII forbidden-metadata-key denylist owned by core.

These keys are always scrubbed from telemetry metadata regardless of whether any companion is registered. Companions may declare additional forbidden keys via their forbidden_metadata_keys/0 callback; those are unioned with this baseline at attach time.

Phase 139 added :actor_ref as the curated universal-floor delta (D-5): the HMAC-anonymized audit identity anchor that must be scrubbed even with zero companions registered.

Semver contract: adding a key is a non-breaking minor (stricter safety); removing a key is a breaking major (weaker safety).

detach_default_logger()

@spec detach_default_logger() :: :ok | {:error, :not_found}

Detaches the default Crosswake telemetry logger handler.

Returns :ok if the handler was attached and is now removed. Returns {:error, :not_found} if no handler with id "crosswake-default-logger" exists.

events()

@spec events() :: [event_doc()]

Returns the runtime-aggregated catalog of all Crosswake telemetry events.

Builds the catalog at call time by concatenating:

Core :active span docs for the 5 confirmed emitting prefixes
:reserved docs aggregated at runtime from each registered companion's telemetry_events/0 callback (guarded by function_exported?/3) — zero static companion references (DECOUPLE-01)
Additional companion docs from Application.get_env(:crosswake, :companions, []) merged via function_exported?(mod, :telemetry_events, 0) (D-07, TELEM-04)

The result is de-duplicated by event prefix and sorted (D-06).

Fail-closed (D-10): with no companions configured, returns core events only and never raises. The :reserved tier will be empty — that is correct and expected.