wishforge-ide/docs/observability.md
eust-w b47a07e8d2 chore: baseline snapshot of the Codex-delivered code before review
Imports the previously untracked working tree as-is so that the review
changes that follow (requirements -> design -> implementation) can be
reviewed as diffs and reverted if needed. No content changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 13:18:04 +08:00

1.6 KiB

Observability

The API exposes /health (liveness) and /readyz (database connectivity). These are independent from provider availability, sandbox readiness and deployed application acceptance.

Set WF_METRICS_TOKEN to a random secret and configure Prometheus to scrape /metrics with that Bearer token. Without the setting the route is disabled. Counters and histograms use normalized route templates, methods and status codes; raw resource IDs, query strings, prompts and credentials are excluded. Process metrics use the wishforge_ prefix. Only a protected monitoring network should reach this endpoint in production.

Set OTEL_EXPORTER_OTLP_ENDPOINT only when a collector is available. The Node OpenTelemetry SDK exports manually instrumented request spans to /v1/traces. No exporter runs by default and the application does not send telemetry to a third-party endpoint automatically. Configure transport/TLS and retention for the collector separately. This is API instrumentation; provider, workflow and deployment traces must be joined with persisted run/operation IDs, and no unverified end-to-end trace or alerting SLO is claimed.

Prometheus should alert on sustained 5xx increases and API latency, while Temporal visibility and the control database should be used to investigate queue starvation, expired leases, unknown deployment outcomes and budget waits. Run events and append-only database audit records retain the corresponding artifact and authorization references. Production alert delivery is an operator configuration and has not been acceptance-tested against a live pager.