# `SnakeBridge.Telemetry`
[🔗](https://github.com/nshkrdotcom/snakebridge/blob/v0.16.0/lib/snakebridge/telemetry.ex#L1)

Telemetry event definitions for SnakeBridge.

This module provides instrumentation for compile-time operations including:
- Source scanning
- Python introspection
- Code generation
- Lock file verification

## Event List

| Event | Measurements | Metadata |
|-------|-------------|----------|
| `[:snakebridge, :compile, :start]` | `system_time` | `libraries`, `strict` |
| `[:snakebridge, :compile, :stop]` | `duration`, `symbols_generated`, `files_written` | `libraries`, `mode` |
| `[:snakebridge, :compile, :exception]` | `duration` | `reason`, `stacktrace` |
| `[:snakebridge, :compile, :scan, :stop]` | `duration`, `files_scanned`, `symbols_found` | `library`, `phase`, `details` |
| `[:snakebridge, :compile, :introspect, :start]` | `system_time` | `library`, `phase`, `details` |
| `[:snakebridge, :compile, :introspect, :stop]` | `duration`, `symbols_introspected`, `cache_hits` | `library`, `phase`, `details` |
| `[:snakebridge, :compile, :generate, :stop]` | `duration`, `bytes_written`, `functions_generated`, `classes_generated` | `library`, `phase`, `details` |
| `[:snakebridge, :docs, :fetch]` | `duration` | `module`, `function`, `source` |
| `[:snakebridge, :lock, :verify]` | `duration` | `result`, `warnings` |
| `[:snakebridge, :session, :cleanup]` | `system_time` | `session_id`, `source`, `reason` |

## Usage

    # Attach handlers in your application
    SnakeBridge.Telemetry.Handlers.Logger.attach()

    # Compile-time events are automatically emitted during mix compile

# `compile_exception`

```elixir
@spec compile_exception(integer(), term(), list()) :: :ok
```

Emits compile exception event.

## Measurements

- `duration` - Time in native units

## Metadata

- `library` - `:all`
- `phase` - `:compile`
- `details` - `%{reason: term(), stacktrace: list()}`

# `compile_start`

```elixir
@spec compile_start([atom()], boolean()) :: :ok
```

Emits compile start event.

## Measurements

- `system_time` - System time when compilation started

## Metadata

- `library` - `:all`
- `phase` - `:compile`
- `details` - `%{libraries: [...], strict: boolean()}`

# `compile_stop`

```elixir
@spec compile_stop(
  integer(),
  non_neg_integer(),
  non_neg_integer(),
  [atom()],
  :normal | :strict
) :: :ok
```

Emits compile stop event.

## Measurements

- `duration` - Time in native units
- `symbols_generated` - Number of symbols generated
- `files_written` - Number of files written

## Metadata

- `library` - `:all`
- `phase` - `:compile`
- `details` - `%{libraries: [...], mode: :normal | :strict}`

# `docs_fetch`

```elixir
@spec docs_fetch(integer(), module(), atom(), :cache | :python | :metadata) :: :ok
```

Emits docs fetch event.

## Measurements

- `duration` - Time in native units

## Metadata

- `module` - Module fetched
- `function` - Function name
- `source` - `:cache`, `:python`, or `:metadata`

# `event_metadata_schema`

```elixir
@spec event_metadata_schema([atom()]) :: [atom()]
```

Returns the expected metadata fields for an event.

# `generate_stop`

```elixir
@spec generate_stop(
  integer(),
  atom(),
  String.t(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer()
) :: :ok
```

Emits generate stop event.

## Measurements

- `duration` - Time in native units
- `bytes_written` - Number of bytes written
- `functions_generated` - Number of functions generated
- `classes_generated` - Number of classes generated

## Metadata

- `library` - Library atom generated
- `phase` - `:generate`
- `details` - `%{file: String.t()}`

# `introspect_start`

```elixir
@spec introspect_start(atom(), non_neg_integer()) :: :ok
```

Emits introspect start event.

## Measurements

- `system_time` - System time when introspection started

## Metadata

- `library` - Library atom being introspected
- `phase` - `:introspect`
- `details` - `%{batch_size: non_neg_integer()}`

# `introspect_stop`

```elixir
@spec introspect_stop(
  integer(),
  atom(),
  non_neg_integer(),
  non_neg_integer(),
  integer()
) :: :ok
```

Emits introspect stop event.

## Measurements

- `duration` - Time in native units
- `symbols_introspected` - Number of symbols introspected
- `cache_hits` - Number of cache hits

## Metadata

- `library` - Library atom introspected
- `phase` - `:introspect`
- `details` - `%{python_time: integer()}`

# `lock_verify`

```elixir
@spec lock_verify(integer(), :ok | :warning | :error, [String.t()]) :: :ok
```

Emits lock verify event.

## Measurements

- `duration` - Time in native units

## Metadata

- `result` - `:ok`, `:warning`, or `:error`
- `warnings` - List of warning strings

# `scan_stop`

```elixir
@spec scan_stop(integer(), non_neg_integer(), non_neg_integer(), [String.t()]) :: :ok
```

Emits scan stop event.

## Measurements

- `duration` - Time in native units
- `files_scanned` - Number of files scanned
- `symbols_found` - Number of symbols found

## Metadata

- `library` - `:all`
- `phase` - `:scan`
- `details` - `%{paths: [String.t()]}`

# `session_cleanup`

```elixir
@spec session_cleanup(String.t(), :manual | :owner_down, term()) :: :ok
```

Emits session cleanup event.

## Measurements

- `system_time` - System time when cleanup was triggered

## Metadata

- `session_id` - Session identifier
- `source` - `:manual` or `:owner_down`
- `reason` - Exit reason or `:manual`

# `session_cleanup_error`

```elixir
@spec session_cleanup_error(String.t(), :manual | :owner_down, term()) :: :ok
```

Emits session cleanup error event.

## Measurements

- `system_time` - System time when cleanup failure was observed

## Metadata

- `session_id` - Session identifier
- `source` - `:manual` or `:owner_down`
- `reason` - Error or exit reason

---

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