SquidMesh.Observability (squid_mesh v0.1.0-alpha.3)

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.

Summary

Functions

duration_since(started_at)

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

emit_run_created(run)

Emits a telemetry event when a run is created.

emit_run_dispatched(run, job, queue, schedule_in)

Emits a telemetry event when a run is dispatched to Oban.

emit_run_replayed(run)

Emits a telemetry event when a run is replayed.

emit_run_transition(run, from_status, to_status)

Emits a telemetry event for a run state transition.

emit_step_completed(run, step, attempt, duration_native)

Emits a telemetry event when a workflow step completes.

emit_step_failed(run, step, attempt, duration_native, error)

Emits a telemetry event when a workflow step fails.

emit_step_retry_scheduled(run, step, attempt, delay_ms)

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

emit_step_skipped(run, step, reason)

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

emit_step_started(run, step, attempt)

Emits a telemetry event when a workflow step starts.

with_run_metadata(run, fun)

Runs a function with run-scoped logger metadata attached.

with_step_metadata(run, step, attempt, fun)

Runs a function with step-scoped logger metadata attached.

Functions

duration_since(started_at)

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

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

emit_run_created(run)

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

Emits a telemetry event when a run is created.

emit_run_dispatched(run, job, queue, schedule_in)

@spec emit_run_dispatched(
  SquidMesh.Run.t(),
  Oban.Job.t(),
  atom(),
  pos_integer() | nil
) :: :ok

Emits a telemetry event when a run is dispatched to Oban.

emit_run_replayed(run)

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

Emits a telemetry event when a run is replayed.

emit_run_transition(run, from_status, to_status)

@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(run, step, attempt, duration_native)

@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(run, step, attempt, duration_native, error)

@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(run, step, attempt, delay_ms)

@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(run, step, reason)

@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(run, step, attempt)

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

Emits a telemetry event when a workflow step starts.

with_run_metadata(run, fun)

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

Runs a function with run-scoped logger metadata attached.

with_step_metadata(run, step, attempt, fun)

@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.