Telemetry event emission and default logger for Forja.

All events follow the [:forja, resource, action] convention and are emitted via :telemetry.execute/3.

Default Logger

Forja ships with an opt-in default logger that converts telemetry events into structured Logger calls. Activate it in your application.ex:

Forja.Telemetry.attach_default_logger(level: :info)

The :level option controls which categories of events are logged:

Options

• :level - Logger level tier (default: :info)
• :include_payload - Include event payload in logs (default: false)
• :encode - JSON-encode log output (default: false)
• :events - :all (default) or explicit list like [:emitted, :processed]

Example

# Development: see everything including payloads
Forja.Telemetry.attach_default_logger(level: :debug, include_payload: true)

# Production: only problems
Forja.Telemetry.attach_default_logger(level: :warning, encode: true)

All log calls use domain: [:forja], so you can filter them:

# Suppress all Forja logs via Erlang logger filters
:logger.add_primary_filter(:no_forja, {&:logger_filters.domain/2, {:stop, :sub, [:forja]}})

Emitted events

• emit_emitted(name, %{type: type} = attrs) emits [:forja, :event, :emitted]

  • Measurements: %{count: 1}

  • Metadata: %{name: atom, type: string, source: string, payload: map | nil, correlation_id: string | nil}

• emit_processed(name, %{type: type, handler: handler, path: path, duration: duration}) emits [:forja, :event, :processed] when a handler processes successfully

  • Measurements: %{duration: native_time}
  • Metadata: %{name: atom, type: string, handler: module, path: atom()}

• emit_failed(name, %{type: type, handler: handler, path: path, reason: reason}) emits [:forja, :event, :failed] when a handler fails

  • Measurements: %{count: 1}
  • Metadata: %{name: atom, type: string, handler: module, path: atom, reason: term}

• [:forja, :event, :dead_letter] - When Oban discards a job (all attempts exhausted)

  • Measurements: %{count: 1}
  • Metadata: %{name: atom, event_id: binary, reason: term}

• [:forja, :event, :abandoned] - When reconciliation also exhausts its retries

  • Measurements: %{count: 1}
  • Metadata: %{name: atom, event_id: binary, reconciliation_attempts: integer}

• [:forja, :event, :reconciled] - When reconciliation successfully processes an event

  • Measurements: %{count: 1}
  • Metadata: %{name: atom, event_id: binary}

• [:forja, :event, :deduplicated] - When an idempotency key prevents a duplicate emission

  • Measurements: %{count: 1}
  • Metadata: %{name: atom, idempotency_key: string, existing_event_id: binary}

• [:forja, :event, :validation_failed] - When payload validation fails at emit-time

  • Measurements: %{count: 1}

  • Metadata: %{name: atom, type: string | module, errors: term}