# `Foundation.Telemetry`
[🔗](https://github.com/nshkrdotcom/foundation/blob/v0.2.1/lib/foundation/telemetry.ex#L1)

Lightweight telemetry helpers with optional TelemetryReporter integration.

This module is intentionally thin: it emits `:telemetry` events and provides
convenience wrappers for timing code. If the optional `telemetry_reporter`
dependency is available, it can also start a reporter and attach handlers
that forward events.

# `event_name`
[🔗](https://github.com/nshkrdotcom/foundation/blob/v0.2.1/lib/foundation/telemetry.ex#L11)

```elixir
@type event_name() :: [atom()]
```

# `measurements`
[🔗](https://github.com/nshkrdotcom/foundation/blob/v0.2.1/lib/foundation/telemetry.ex#L12)

```elixir
@type measurements() :: map()
```

# `metadata`
[🔗](https://github.com/nshkrdotcom/foundation/blob/v0.2.1/lib/foundation/telemetry.ex#L13)

```elixir
@type metadata() :: map()
```

# `reporter`
[🔗](https://github.com/nshkrdotcom/foundation/blob/v0.2.1/lib/foundation/telemetry.ex#L14)

```elixir
@type reporter() :: GenServer.server()
```

# `attach_reporter`
[🔗](https://github.com/nshkrdotcom/foundation/blob/v0.2.1/lib/foundation/telemetry.ex#L83)

```elixir
@spec attach_reporter(keyword()) :: {:ok, term()} | {:error, :missing_dependency}
```

Attach TelemetryReporter handlers for forwarding `:telemetry` events.

Returns the handler id.

# `detach_reporter`
[🔗](https://github.com/nshkrdotcom/foundation/blob/v0.2.1/lib/foundation/telemetry.ex#L93)

```elixir
@spec detach_reporter(term()) ::
  :ok | {:error, :not_found} | {:error, :missing_dependency}
```

Detach a TelemetryReporter handler.

# `execute`
[🔗](https://github.com/nshkrdotcom/foundation/blob/v0.2.1/lib/foundation/telemetry.ex#L20)

```elixir
@spec execute(event_name(), measurements(), metadata()) :: :ok
```

Emit a telemetry event.

# `log`
[🔗](https://github.com/nshkrdotcom/foundation/blob/v0.2.1/lib/foundation/telemetry.ex#L71)

```elixir
@spec log(reporter(), String.t() | [atom()], map(), atom()) ::
  :ok
  | {:error, :overloaded}
  | {:error, :not_running}
  | {:error, :missing_dependency}
```

Log a telemetry event via TelemetryReporter if available.

# `measure`
[🔗](https://github.com/nshkrdotcom/foundation/blob/v0.2.1/lib/foundation/telemetry.ex#L32)

```elixir
@spec measure(event_name(), metadata(), (-> result), keyword()) :: result
when result: term()
```

Measure execution time and emit `:stop` or `:exception` events.

Options:
  * `:time_unit` - unit for duration (default: `:microsecond`)

# `start_reporter`
[🔗](https://github.com/nshkrdotcom/foundation/blob/v0.2.1/lib/foundation/telemetry.ex#L60)

```elixir
@spec start_reporter(keyword()) ::
  GenServer.on_start() | {:error, :missing_dependency}
```

Start a TelemetryReporter instance if the dependency is available.

---

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