Skip to main content

System Logs

System logs are the operational record of startup, requests, background jobs, worker connectivity, and failures. The API has a built-in viewer; every process also writes structured log files to disk.

Where to find the viewer​

The Logs page is under Management → Logs in the sidebar and is available to administrators.

The viewer reads only the API's own log files ({StoragePath}/logs/). Session Worker and Deployment Worker logs stay on each worker machine — collect them separately when troubleshooting distributed execution. Hook output and per-session activity are shown in each session's Hook Logs tab rather than here.

Filters narrow the viewer to the entries relevant to an incident.

FilterBehavior
LevelSelect one or more exact levels: Verbose, Debug, Information, Warning, Error, Fatal.
TimeLast Hour (default), Last 5 Hours, Today (since midnight in your browser's time zone), Last 5 Days, All.
SearchFree text matched against the message, source, and exception text.

Results are paginated. Combine a level, a time range, and a search term to find an entry quickly.

Log levels​

Polygent uses these levels, from most to least detailed.

LevelUse
VerboseTrace-level diagnostics; extremely chatty — use only during an investigation.
DebugDetailed diagnostics for reproducing a problem.
InformationNormal operational events (default).
WarningRecoverable issues, rejected requests, and non-fatal failures.
ErrorOperations that failed and need attention.
FatalProcess-stopping errors.

File layout​

Each process writes JSON-lines files that roll daily.

ProcessMain logErrors only
API{StoragePath}/logs/polygent-YYYYMMDD.jsonl{StoragePath}/logs/errors/polygent-errors-YYYYMMDD.jsonl
Session Worker{StoragePath}/logs/session-worker-YYYYMMDD.jsonl—
Deployment Worker<install folder>/logs/deploy-worker-YYYYMMDD.jsonl—

The error-only file holds Error and Fatal entries for fast triage; the viewer does not read it separately because the main file contains the same entries. Every process also writes to its console. When a process fails before logging starts, it writes crash.log in its install folder (the Session Worker writes it when StoragePath is missing).

Configuring log levels​

The minimum level is set by Logging:LogLevel:Default (default Information) in each process's appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Or with an environment variable:

Logging__LogLevel__Default=Debug

Restart the process to apply the change. Accepted values are Verbose (or Trace), Debug, Information, Warning, Error, and Fatal; any other value, including Critical and None, is treated as Information.

note

Only the Default level is applied. Category-specific entries are ignored, and framework components stay at Warning regardless of the configured level.

The shipped Deployment Worker configuration uses Debug; set it to Information for production.

Retention​

Each log stream keeps its 30 most recent files; older files are deleted automatically. A file that reaches 100 MB rolls over to a new file for the same day, so a very busy installation keeps fewer than 30 days of history. Retention is not configurable. For longer retention or compliance archival, ship the logs/ folders to your own log store (for example a SIEM or object storage).

Polygent does not write credential values to its logs, but log entries can contain repository names, file paths, user emails, and error text. Protect log folders and exports accordingly.

See also​