tutti/docs/conventions/logging.md

Logging

This document defines the current logging conventions for tutti.

The repository-owned default values for log file names and rotation budgets now live in:

• config/tutti.defaults.json

Go and desktop code should consume generated defaults from that source instead of carrying duplicate literal values.

Purpose

tuttid is a long-running local daemon.

Its normal operational logs should be durable and reviewable even when the desktop shell is the process supervisor.

apps/desktop main process should also keep a durable local log for Electron-shell concerns.

tuttid Default Behavior

tuttid defaults to file-based logging.

Current default:

• log output mode: file
• log path: <state-dir>/logs/tuttid.log
• log format: structured slog text output
• default level: info
• active file name stays stable for tailing
• rotated history uses date-indexed names such as tuttid.2026-05-21.log

This means normal development and product runs should treat the daemon log file as the primary source for runtime analysis.

Desktop Main Logging

Desktop main-process logging also defaults to file output.

Current default:

• log output mode: file
• log path: <state-dir>/logs/tutti-desktop.log
• default level: info
• active file name stays stable for tailing
• rotated history uses date-indexed names such as tutti-desktop.2026-05-21.log

Desktop logging is intended for:

• app bootstrap failures
• daemon supervision events
• shell-level errors
• Electron lifecycle issues

It is not a replacement for tuttid business and runtime logs.

Correlation Fields

Desktop and daemon logs should be easy to align during one local run.

Current shared correlation behavior:

• desktop generates or adopts TUTTI_SESSION_ID at startup
• when desktop manages tuttid, it passes the same TUTTI_SESSION_ID into the daemon process
• both tutti-desktop.log and tuttid.log now include session_id in each structured line when available

This is intentionally lightweight:

• it is not a distributed tracing system
• it is a stable per-launch correlation key for local debugging and log analysis

Desktop Diagnostic Exports

Desktop diagnostic exports use an explicit time range and an explicit Session record choice. The supported combinations are:

• the last 10 minutes of logs
• the last 10 minutes of logs plus Agent Session records
• the last 3 days of logs
• the last 3 days of logs plus Agent Session records

The selected time range applies to structured log timestamps, file modification time when a source has no parseable timestamps, and Agent Session update time. Choosing logs only must not query or write Agent Session records. Runtime context, the export summary, and other non-Session diagnostic snapshots remain part of the log bundle so exported evidence stays interpretable.

Runtime-context transport diagnostics are allowlisted. Exports may include the bound/requested address and listener/PID paths, but must never serialize the transport access token or newly added transport snapshot fields by default.

Error Codes

Startup, transport, and supervision failures should carry a stable error_code in addition to the human-readable message.

Current desktop-focused codes include:

• logger_file_unavailable
• daemon_unavailable
• transport_timeout
• transport_connect_failed
• transport_request_failed
• managed_process_stderr
• managed_process_exited
• workspace_not_found

Current daemon runtime codes include:

• server_serve_failed
• server_shutdown_failed

Protocol-layer codes belong to daemon API contracts rather than desktop-local runtime diagnostics.

Examples:

• workspace_not_found
• workspace_path_exists
• workspace_operation_failed
• invalid_request
• service_unavailable
• method_not_allowed

Rules:

• prefer a stable machine-readable code over parsing log messages later
• keep the code small and responsibility-oriented
• let the message continue to carry specific context for humans
• keep protocol-facing codes separate from desktop-local supervision codes such as managed_process_exited

Output Modes

tuttid currently supports:

• TUTTID_LOG_OUTPUT=file
• TUTTID_LOG_OUTPUT=stdout
• TUTTID_LOG_OUTPUT=tee

Desktop main currently supports:

• TUTTI_DESKTOP_LOG_OUTPUT=file
• TUTTI_DESKTOP_LOG_OUTPUT=stdout
• TUTTI_DESKTOP_LOG_OUTPUT=tee

Rules:

• file writes only to the daemon log file
• stdout writes only to standard output
• tee writes to both the daemon log file and standard output

Default:

• TUTTID_LOG_OUTPUT unset behaves as file

Log Levels

tuttid supports:

• TUTTID_LOG_LEVEL=debug
• TUTTID_LOG_LEVEL=info
• TUTTID_LOG_LEVEL=warn
• TUTTID_LOG_LEVEL=error

Default:

• TUTTID_LOG_LEVEL unset behaves as info

Desktop main supports:

• TUTTI_DESKTOP_LOG_LEVEL=debug
• TUTTI_DESKTOP_LOG_LEVEL=info
• TUTTI_DESKTOP_LOG_LEVEL=warn
• TUTTI_DESKTOP_LOG_LEVEL=error

Default:

• TUTTI_DESKTOP_LOG_LEVEL unset behaves as info

Hot-Path Diagnostics

Streaming events, polling loops, renderer snapshots, and transport frames are hot paths. Their successful per-event diagnostics belong at debug; the default info level should contain a bounded summary per turn, short time window, or semantic state transition.

Rules:

• aggregate repeated success events and retain counts plus stable correlation fields in the summary
• keep failures, dropped data, and rare lifecycle transitions visible at warn or error
• exclude cursors, timestamps, token/message versions, and elapsed time from change-detection signatures unless that value is the state being diagnosed
• log a periodic poll at info or warn only when its semantic result changes; unchanged results belong at debug
• desktop file writes must stay ordered without performing one synchronous filesystem write on the Electron main thread per line

Rotation

Both daemon and desktop main now follow the same rotation convention:

• active file keeps a stable name
• rotation happens on calendar day change or when size budget is exceeded
• rotated files are date-indexed and optionally numbered for same-day rollover

Shared rotation controls:

• TUTTI_LOG_DIR
• TUTTI_LOG_MAX_SIZE_MB
• TUTTI_LOG_MAX_BACKUPS
• TUTTI_LOG_MAX_AGE_DAYS
• TUTTI_LOG_MAX_TOTAL_MB

Default budgets:

• max size: 50MB
• max backups: 10
• max age: 14 days
• max total managed log directory size: 300MB

Desktop Supervision Rules

When desktop manages tuttid:

• daemon logs still default to file output
• desktop does not forward daemon stdout by default
• desktop still surfaces daemon stderr for startup and failure visibility

This keeps normal daemon logs in the file while still allowing focused debugging when stdout is explicitly requested.

Desktop-side debug options:

• set TUTTID_LOG_OUTPUT=stdout or tee
• or set TUTTID_FORWARD_STDIO=1 when you want desktop to forward daemon stdout explicitly
• set TUTTI_DESKTOP_LOG_OUTPUT=stdout or tee when you want desktop shell logs on standard output

These environment variables are override and diagnostics controls, not the primary source of default logging policy.

Allowed Override Surface

Current supported logging override surface:

• TUTTI_LOG_DIR
• TUTTI_LOG_MAX_SIZE_MB
• TUTTI_LOG_MAX_BACKUPS
• TUTTI_LOG_MAX_AGE_DAYS
• TUTTI_LOG_MAX_TOTAL_MB
• TUTTID_LOG_PATH
• TUTTID_LOG_OUTPUT
• TUTTID_LOG_LEVEL
• TUTTI_DESKTOP_LOG_PATH
• TUTTI_DESKTOP_LOG_OUTPUT
• TUTTI_DESKTOP_LOG_LEVEL
• TUTTID_FORWARD_STDIO
• TUTTI_SESSION_ID

Rules:

• these variables exist for local debugging, tests, packaging, and diagnostics
• do not introduce a new logging environment variable unless existing shared defaults or existing override hooks are insufficient
• prefer shared controls such as TUTTI_LOG_DIR and the rotation budget variables over component-specific one-off flags
• if a new logging override is added, update this document and config/tutti.defaults.json if the change also affects the repository-owned defaults

Failure Visibility

Fatal startup failures should still be visible through stderr.

Examples:

• invalid log configuration
• logger file open failure
• listener startup failure
• fatal daemon exit

This avoids a failure mode where the daemon dies before usable file logging is available.

Current Recommendation

Use:

• file for normal product runs and joint development analysis
• tee when debugging startup, transport, or daemon behavior while still preserving a durable file log
• stdout only for narrow, deliberate debugging flows

Use the same rule for desktop shell logs unless a local debugging task specifically benefits from terminal output.

Related Docs

• Local State Storage
• Desktop Layering