# `PgFlow.Telemetry`
[🔗](https://github.com/agoodway/pgflow/blob/v0.1.0/lib/pgflow/telemetry.ex#L1)

Telemetry events emitted by PgFlow.

PgFlow uses `:telemetry` to emit events at key points in the workflow lifecycle.
These events can be used for monitoring, logging, and metrics collection.

## Events

### Worker Lifecycle

- `[:pgflow, :worker, :start]` — Worker process started
- `[:pgflow, :worker, :stop]` — Worker process stopped

### Poll Cycles

- `[:pgflow, :worker, :poll, :start]` — Poll cycle started
- `[:pgflow, :worker, :poll, :stop]` — Poll cycle completed

### Task Execution

- `[:pgflow, :worker, :task, :start]` — Task execution started
- `[:pgflow, :worker, :task, :stop]` — Task execution completed successfully
- `[:pgflow, :worker, :task, :exception]` — Task execution failed

### Run Lifecycle

- `[:pgflow, :run, :started]` — Flow run created (emitted by `PgFlow.Client`)
- `[:pgflow, :run, :completed]` — Flow run completed (emitted by worker after task cascades)
- `[:pgflow, :run, :failed]` — Flow run failed (emitted by worker after task cascades)

## Attaching Handlers

    :telemetry.attach_many(
      "my-handler",
      [
        [:pgflow, :worker, :task, :stop],
        [:pgflow, :run, :completed],
        [:pgflow, :run, :failed]
      ],
      &MyModule.handle_event/4,
      nil
    )

## Default Logger

PgFlow includes a default logger handler that can be attached by setting
`attach_default_logger: true` in the configuration.

Note: The default logger is disabled by default since `PgFlow.Logger` provides
structured logging directly in the worker. Enable this if you need telemetry-based
logging for specific use cases like metrics collection or external log aggregation.

# `attach_default_logger`

```elixir
@spec attach_default_logger() :: :ok | {:error, :already_exists}
```

Attaches the default telemetry handlers for logging.

This is called automatically on application start if `attach_default_logger: true`
is set in the configuration.

# `detach_default_logger`

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

Detaches the default telemetry handlers.

---

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