# `Snakepit.Telemetry.Naming`
[🔗](https://github.com/nshkrdotcom/snakepit/blob/v0.13.0/lib/snakepit/telemetry/naming.ex#L1)

Event catalog and naming validation for Snakepit telemetry.

This module ensures atom safety by maintaining a curated catalog of all
valid telemetry events and measurement keys. Python-originated events
must pass through this module to prevent arbitrary atom creation.

## Python Event Catalog

`python_event_catalog/0` lists the event strings emitted by `snakepit_bridge`
and the measurement keys they are expected to use. When adding a new Python
telemetry event, update that catalog and the allowlist in
`snakepit_bridge.telemetry.stream` together so both languages agree on the
schema.

# `event`

Build an event name from components.

## Examples

    iex> Snakepit.Telemetry.Naming.event(:pool, :worker, :spawned)
    [:snakepit, :pool, :worker, :spawned]

# `from_parts`

Convert Python event parts to a valid Elixir telemetry event name.

Returns `{:ok, event_name}` if the parts map to a known event,
`{:error, reason}` otherwise.

## Examples

    iex> Snakepit.Telemetry.Naming.from_parts(["python", "call", "start"])
    {:ok, [:snakepit, :python, :call, :start]}

    iex> Snakepit.Telemetry.Naming.from_parts(["unknown", "event"])
    {:error, :unknown_event}

# `grpc_event`

Build a gRPC event name.

# `grpc_events`

Get all valid gRPC events.

# `measurement_key`

Validate a measurement key and convert to atom if it's in the allowlist.

## Examples

    iex> Snakepit.Telemetry.Naming.measurement_key("duration")
    {:ok, :duration}

    iex> Snakepit.Telemetry.Naming.measurement_key("unknown_key")
    {:error, :unknown_measurement_key}

# `measurement_keys`

Get all valid measurement keys.

# `pool_event`

Build a pool event name.

# `pool_events`

Get all valid pool events.

# `python_event`

Build a Python event name.

# `python_event_catalog`

Return the catalog describing Python event names, their telemetry atoms, and expected measurements.

# `python_events`

Get all valid Python events.

# `session_event`

Build a session event name.

# `session_events`

Get all valid session events.

---

*Consult [api-reference.md](api-reference.md) for complete listing*