# `SquidMesh.Observability`
[🔗](https://github.com/ccarvalho-eng/squid_mesh/blob/main/lib/squid_mesh/observability.ex#L1)

Internal helpers for runtime telemetry and structured logs.

The external observability contract is documented in `docs/observability.md`.
This module keeps event naming and logger metadata consistent across the
runtime.

# `duration_since`

```elixir
@spec duration_since(DateTime.t()) :: non_neg_integer()
```

Converts a persisted UTC timestamp into a native-unit duration up to now.

# `emit_run_created`

```elixir
@spec emit_run_created(SquidMesh.Run.t()) :: :ok
```

Emits a telemetry event when a run is created.

# `emit_run_dispatched`

```elixir
@spec emit_run_dispatched(SquidMesh.Run.t(), map()) :: :ok
```

Emits a telemetry event when a run is dispatched to the configured executor.

# `emit_run_replayed`

```elixir
@spec emit_run_replayed(SquidMesh.Run.t()) :: :ok
```

Emits a telemetry event when a run is replayed.

# `emit_run_transition`

```elixir
@spec emit_run_transition(
  SquidMesh.Run.t(),
  SquidMesh.Run.status(),
  SquidMesh.Run.status()
) :: :ok
```

Emits a telemetry event for a run state transition.

# `emit_step_completed`

```elixir
@spec emit_step_completed(SquidMesh.Run.t(), atom(), pos_integer(), non_neg_integer()) ::
  :ok
```

Emits a telemetry event when a workflow step completes.

# `emit_step_failed`

```elixir
@spec emit_step_failed(
  SquidMesh.Run.t(),
  atom(),
  pos_integer(),
  non_neg_integer(),
  map()
) :: :ok
```

Emits a telemetry event when a workflow step fails.

# `emit_step_retry_scheduled`

```elixir
@spec emit_step_retry_scheduled(
  SquidMesh.Run.t(),
  atom(),
  pos_integer(),
  non_neg_integer()
) :: :ok
```

Emits a telemetry event when a retry is scheduled for a workflow step.

# `emit_step_skipped`

```elixir
@spec emit_step_skipped(SquidMesh.Run.t(), atom(), String.t()) :: :ok
```

Emits a telemetry event when a stale or duplicate step delivery is skipped.

# `emit_step_started`

```elixir
@spec emit_step_started(SquidMesh.Run.t(), atom(), pos_integer()) :: :ok
```

Emits a telemetry event when a workflow step starts.

# `with_run_metadata`

```elixir
@spec with_run_metadata(SquidMesh.Run.t(), (-> result)) :: result when result: var
```

Runs a function with run-scoped logger metadata attached.

# `with_step_metadata`

```elixir
@spec with_step_metadata(SquidMesh.Run.t(), atom(), pos_integer() | nil, (-> result)) ::
  result
when result: var
```

Runs a function with step-scoped logger metadata attached.

---

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