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.

AegisGitea-MCP

Start

Operating

Internals

Security

Reference

Generated from the docs/ directory. Edit the docs, not the wiki, then re-run the wiki sync.