# wallet_observability

**OTP app:** `:wallet_observability`
**Module namespace:** `WalletObservability.*`
**Owner:** Platform Team / SRE

## Responsibilities
Central metrics, tracing helpers, audit event emission, and health check aggregation.

Per **ADR 0007**: all apps must propagate `request_id` and `correlation_id`, emit structured
audit events for compliance-relevant operations, and report telemetry with consistent labels.

## Public API

### `WalletObservability.AuditEvent`
Build structured audit event maps for compliance traceability.

```elixir
WalletObservability.AuditEvent.build(
  :financial,
  "post_journal_entry",
  "ledger_entry",
  "led_abc123",
  :success,
  actor_id: "usr_xyz",
  correlation_id: "corr_abc",
  metadata: %{amount: 1000, currency: "INR"}
)
```

Audit categories: `:auth | :financial | :account | :admin | :compliance`

### `WalletObservability.Telemetry`
Telemetry emission helpers with standard metadata enrichment.

```elixir
WalletObservability.Telemetry.execute(
  [:wallet_ledger, :posting, :stop],
  %{duration: 42},
  %{correlation_id: "corr_abc", status: :ok}
)
```

## Metric Naming Convention (ADR 0007)
`<app>.<subsystem>.<measurement>`

Examples:
- `wallet_web.endpoint.stop.duration`
- `wallet_ledger.repo.query.total_time`
- `wallet_transfers.command.execute.duration`

## Required Labels on All Domain Metrics
- `app` - OTP app atom
- `status_code` - HTTP status or outcome code
- `error_code` - ADR 0005 error code (for error metrics)
- `retryable` - boolean retry guidance (for error metrics)

## Audit Event Obligations (ADR 0007)
Every app must emit audit events for:
- Authentication decisions (success and failure)
- Financial operations (post, reverse, debit, credit)
- Account lifecycle changes (open, freeze, unfreeze)
- Admin overrides and configuration changes
- Compliance case actions (KYC/KYB/AML)

## Allowed Dependencies
- `wallet_shared_kernel` - typed IDs and correlation helpers
- `telemetry_metrics` - metrics definitions
- `telemetry_poller` - periodic VM measurements