Crosswake.Threadline.Telemetry (crosswake v0.1.2)

View Source

Telemetry contract for Crosswake Threadline correlation diagnostics.

This module defines the low-cardinality :telemetry event-name allowlist and metadata allowlist guard for request-span events emitted by the Crosswake.Plug.Threadline Plug (Phase 92).

Diagnostic-only. Threadline telemetry is PII-free correlation evidence: it propagates a session-spanning thread_id above the per-command correlation_id for operator observability. It is NOT an APM replacement, NOT a distributed tracing framework, and NOT a generic event bus. It coexists with any host-side telemetry or tracing pipeline without interfering with them.

All metadata passes through metadata/1 before emission, which:

  • Keeps only the four PROP-02 allowlisted keys (@metadata_keys)
  • Drops any key in @forbidden_metadata_keys (PII denylist) silently
  • Drops allowlisted keys whose values are unsafe (nil, oversized binaries, etc.)
  • Drops all other unknown keys

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

Summary

Functions

event_names()
execute(name, measurements \\ %{}, metadata \\ %{})
forbidden_metadata_keys()
metadata(event)
metadata_keys()
new_event(attrs)
to_map(event)
valid_event_name?(name)

Functions

event_names()

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

execute(name, measurements \\ %{}, metadata \\ %{})

@spec execute([atom()], map(), map() | keyword()) :: :ok

forbidden_metadata_keys()

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

metadata(event)

@spec metadata(Crosswake.Threadline.Telemetry.Event.t() | map() | keyword()) :: map()

metadata_keys()

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

new_event(attrs)

@spec new_event(keyword()) :: Crosswake.Threadline.Telemetry.Event.t()

to_map(event)

@spec to_map(Crosswake.Threadline.Telemetry.Event.t()) :: map()

valid_event_name?(name)

@spec valid_event_name?(term()) :: boolean()