Diagnostics and Observability

Forge is a local desktop tool, so the first goal is diagnosability, not a hosted telemetry platform.

Structured core logs

Use Go log/slog with stable fields where useful:

• operation_id;
• task_id;
• run_id;
• turn_id;
• project_id;
• subsystem;
• error category.

Do not log raw prompts, credentials, environment variables, or huge provider payloads by default.

Diagnostic records

The database/raw logs already provide strong local evidence. UI diagnostics should make it possible to answer:

• which Operation failed?
• what Run/Strategy/Environment was used?
• where is the raw log?
• what was the external session ID?
• what was the stop reason vs delivery error?
• is client state stale?

Later diagnostic bundle

A user-initiated export may include sanitized logs, schema/app version, Operation/Run metadata, and selected raw references. Design redaction before adding upload/report automation.

Metrics

Do not build a metrics subsystem at the start. When real use begins, local counters/timers can answer product/performance questions such as:

• time from StartTask to active provider;
• open Decision latency;
• review rounds;
• how often raw logs are opened;
• activity history sizes;
• replay/snapshot frequency;
• failed/retried Operations.