# Observability

## Logging

- Structured JSON logs.
- Request correlation via `X-Request-ID`.
- Security events and policy denials are audit logged.

### Structured event helpers

`logging_utils` exposes reusable helpers so endpoints emit consistent,
secret-safe structured events instead of ad-hoc inline logging:

- `log_event(logger, level, event, **context)` — emit a named event with a
  `context` mapping; keys in `SENSITIVE_CONTEXT_KEYS` (e.g. `token`,
  `authorization`, `password`) are masked as `***`.
- `log_nullable_field(logger, event, field, value)` — record whether a parsed
  response field is `None` and its runtime type, without dumping its contents.
- `sanitize_context(context)` — the masking primitive used by the above.

The `context` mapping is serialized into the JSON log payload under a `context`
key. These run at `DEBUG`, so they are silent unless `LOG_LEVEL=DEBUG`.

`get_issue` is instrumented with these helpers (`get_issue.start`,
`get_issue.payload_shape`, `get_issue.field_check`) to make nullable-field
parsing failures diagnosable. The same pattern can be reused for other
parsing-heavy endpoints (`get_pull_request`, `list_issues`, `get_commit_diff`).

## Metrics

Prometheus-compatible endpoint: `GET /metrics`.

Current metrics:
- `aegis_http_requests_total{method,path,status}`
- `aegis_tool_calls_total{tool,status}`
- `aegis_tool_duration_seconds_sum{tool}`
- `aegis_tool_duration_seconds_count{tool}`

## Tracing and Correlation

- Request IDs propagate in response header (`X-Request-ID`).
- Tool-level correlation IDs included in MCP responses.

## Operational Guidance

- Alert on spikes in 401/403/429 rates.
- Alert on repeated `access_denied` and auth-rate-limit events.
- Track tool latency trends for incident triage.