Skip to Content
AgentLocal Logs

Agent Local Logs

The agent keeps the detail of every failure on the on-prem side. Callers and gateway logs only see a safe error code and message; the database error, the upstream HTTP status, or a module’s own error is in the agent’s local log.

Where to look

The runtime log is written next to the onprest-agent binary (in the Docker image, /app/onprest.log; see Deployment) and rotated by size:

onprest-agent.log
onprest-agent.log.1
onprest-agent.log.2
onprest-agent.log.3

On Windows the file is onprest-agent.exe.log.

It records:

  • startup failures, such as a database that cannot be reached or a statement that fails EXPLAIN
  • execution failures from every executor: database errors, upstream HTTP errors, CSV parse errors, file errors, and module errors
  • messages from Wasm modules: SDK Log calls and anything the module writes to stdout (info) or stderr (warn)
  • RATE_LIMITED rejections, sampled at most once a minute per capability, without params

Failure records carry the same request_id as the error response and the gateway log, so search for that ID.

Passwords, connection strings, keys, certificates, and the configured SQL text are removed from log records. Treat the log as sensitive anyway: keep it on the on-prem side and do not forward it to the gateway or an external log service.

The agent’s stdout carries process events such as agent_ready, and stderr carries a short reason when startup fails. When the agent runs as an OS service, the service manager may redirect those to its own files; they do not replace onprest-agent.log.

Level and rotation

logging:
  level: info
  max_size: 10MB
  max_files: 3
KeyDefaultMeaning
levelinfoLowest level recorded: debug, info, warn, or error. Set debug to see SDK Log("debug", ...) messages
max_size10MBSize at which the runtime log is rotated
max_files3Rotated files to keep

Changing the level does not change results. Output from a single module call has a size budget; anything beyond it is cut off with a warning in the log.

validate and doctor

validate and doctor do not write to the runtime log. When one of them fails for a reason worth recording, such as a database that cannot be reached, it writes a separate file next to the binary and prints its path:

CommandLog file
validateonprest-agent.validate.log
doctoronprest-agent.doctor.log

Each file holds only the latest such failure and is deleted after a successful run. Configuration errors are printed in full and leave no file. Read the file only when the command you just ran printed its path; an older file may describe an earlier run. The command also manages temporary and lock files with the same prefix; leave them alone.

Author commands (code build, code test) print their diagnostics on stderr and do not write log files; see Writing code in Go.

ConfigurationKey Rotation