Log locations
Where every VeloPhex component writes its logs and diagnostics, and how to read them.
When something goes wrong, the fastest route to the cause is the right log. This page lists where each component writes its logs, what else it keeps on disk for diagnosis, and how to search it.
Orchestrator#
The Orchestrator writes structured JSON to standard output, so Docker captures it. Every line carries Category, Level and TraceId. Each request has a correlation id, returned in the X-Correlation-ID response header and as correlationId in error responses.
Run these from the deployment directory (for example /srv/velophex):
alias dc='docker compose -f docker-compose.core.yml'
dc logs -f --since 10m api # follow the api
dc logs api | head -40 # what happened at start
dc logs --since 1h api | grep '"Level":"Error"' # errors in the last hour
dc logs --since 1h api | grep '<correlation id>' # one request
dc logs --since 5m postgres # database
dc logs --since 5m caddy # TLS and proxy (JSON access log)
The first lines after a start tell you the environment, which VeloPhex package signer the build carries, whether the bootstrap administrator was created, and which hosted services started.
To follow a background worker, search for its category, for example:
BashCopydc logs --since 24h api | grep '"Category":"VeloPhex.Orchestrator.Infrastructure.Operations.RetentionWorker"'
Traces and metrics#
If you set VELOPHEX_OTLP_ENDPOINT, the Orchestrator also exports OpenTelemetry traces and metrics over OTLP to your collector. See Observability.
In the web app#
- Jobs: each job has its execution logs, including the Robot's preparation steps and the automation's own log lines.
- Audit: who did what, when and from which address. See Audit log.
- Webhooks: the deliveries view shows each failed delivery's status code and response.
Robot#
| What | Where | Notes |
|---|---|---|
| Service log | %ProgramData%\VeloPhex\Robot\logs\robot-<date>.log |
One file a day, rolled at 20 MB, 30 kept. Every line passes a secret redactor |
| Windows Event Log | Application log, source VeloPhex Robot | Warnings, errors and lifecycle events, including start failures that happen before the file log exists |
| Status | VeloPhex.Robot.Service.exe status |
Connectivity, enrollment, active attempts and each runtime's health in one screen |
| Attempt journal | %ProgramData%\VeloPhex\Robot\state\attempts\ |
One JSON file per attempt with phases, timestamps and the workspace path |
| Outbox | %ProgramData%\VeloPhex\Robot\state\outbox\ |
Results not yet accepted by the Orchestrator, with each delivery error |
| Attempt workspaces | %ProgramData%\VeloPhex\Robot\work\ |
Kept for Execution:WorkspaceRetentionDays (7 by default) |
| Machine overlay | %ProgramFiles%\VeloPhex\Robot\appsettings.Production.json |
Which feed and signers the machine was given |
| Connection profile | %ProgramData%\VeloPhex\Robot\config\connection.json |
Enrollment and machine ids; no secrets |
| User Host log | %LOCALAPPDATA%\VeloPhex\Robot\UserHost of the signed-in user |
The per-session host that starts executors on a desktop |
| Assistant crash log | %LOCALAPPDATA%\VeloPhex\Assistant\crash.log |
Written if the Assistant fails unexpectedly |
| Installer log | %TEMP% by default, or wherever you pointed /log (Setup) or /l*v (MSI) |
Install and upgrade failures |
To collect these files in one zip, run from an elevated prompt:
PowerShellCopy& "$env:ProgramFiles\VeloPhex\Robot\VeloPhex.Robot.Service.exe" support-bundle --out robot-support.zip
An administrator can also select Collect diagnostics on the machine's Health panel in the Orchestrator. The Robot uploads a support bundle, which you download from the panel.
Read the Event Log from an elevated prompt:
PowerShellCopywevtutil qe Application /q:"*[System[Provider[@Name='VeloPhex Robot']]]" /f:text /c:200 /rd:true
No secrets in these files
None of the files above holds the enrollment key, the Robot's credential or an execution token. Those live only in the protected store under state\secrets\, which support never needs.
Studio#
| What | Where |
|---|---|
| Diagnostic log | %LOCALAPPDATA%\Velophex\Studio\Logs (14 days, 16 MB per file) |
| Crash dumps | %LOCALAPPDATA%\Velophex\Studio\Dumps (the newest five minidumps) |
| Package trust decisions | %USERPROFILE%\.velophex\logs\package-audit.jsonl |
| Package cache | %USERPROFILE%\.velophex\packages |
| Settings and sources | %APPDATA%\Velophex\Studio |
Inside Studio, the Output panel has channels. The Packages channel lists every package diagnostic once, and the same entries go to the diagnostic log as key=value fields (stage=… package=… version=… status=…). Help > Open logs folder opens the log folder directly.
Python automations#
A Python automation's logging records are forwarded to the Orchestrator and appear in the job's execution logs. Standard output is redirected to standard error so it cannot corrupt the executor protocol, so use logging rather than print(). When you run locally with velophex run, log lines appear in the terminal; --verbose adds the traceback to an input error.
Collecting logs for support#
When you ask for help, collect:
- The correlation id and time of the failing request, if there is one.
- The Orchestrator api log around that time (
dc logs --since 30m api > api.log). - From the Robot machine:
statusoutput, the service log for the day, the Event Log extract above, and the attempt journal entry for the failing job. - From Studio: the diagnostic log and, after a crash, the newest dump.
Review files before you share them. Remove host names or data you are not allowed to share. See Getting help.
Next steps#
Orchestrator
Traces and metrics
In the web app
Robot
Studio
Python automations
Collecting logs for support
Next steps