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):

Orchestrator logsBashCopy
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:

BashCopy
dc 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:

PowerShellCopy
wevtutil 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:

  1. The correlation id and time of the failing request, if there is one.
  2. The Orchestrator api log around that time (dc logs --since 30m api > api.log).
  3. From the Robot machine: status output, the service log for the day, the Event Log extract above, and the attempt journal entry for the failing job.
  4. 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