Skip to main content
OCat includes a built-in LoggerService that collects log messages during program execution. In project mode, all collected logs are written to .ocat/logs.txt when the process exits. You can control which log levels are active and how messages are transformed by creating a logcfg.json file.

​
Log levels

The LogLevel enum defines four levels:
LevelValue
Debug"DEBUG"
Info"INFO"
Warning"WARNING"
Error"ERROR"
By default, the logger enables DEBUG and INFO. Messages at other levels are collected but not enabled unless you override the configuration.

​
Log persistence

Log persistence depends on whether code is running inside a project:
  • Project mode (ocm run): on process exit, all collected logs are written to .ocat/logs.txt in the format [LEVEL] message.
  • Single-file mode (ocat run): logs are printed to the console but are not persisted to disk.
The log file is written at process exit, not line by line. If the process is killed abruptly, partial logs may not be saved.

​
LoggerConfig

The logger is configured through a LoggerConfig object. When running in project mode, this is loaded from .ocat/logcfg.json if that file exists. Otherwise the default configuration is used.
​
logs
LogLevel[]
default:"[\"DEBUG\", \"INFO\"]"
Array of log level string values that are enabled. Messages at levels not listed here are still collected internally but excluded from output.Valid values: "DEBUG", "INFO", "WARNING", "ERROR".
​
interceptors
object[]
default:"[]"
Array of interceptor objects. Each interceptor transforms log messages at a specific level before they are processed.Each interceptor object has:
  • level (string) — the LogLevel value this interceptor applies to
  • onLog (function) — a function that receives the original message string and returns a transformed message string
Interceptor functions cannot be expressed in JSON. The interceptors field is intended for programmatic use. In logcfg.json, set interceptors to an empty array.

​
logcfg.json

Place a logcfg.json file at .ocat/logcfg.json to override the default logger configuration. OCM reads this file before executing your program. The file must be valid JSON and match the LoggerConfig shape.

​
Enable all log levels

.ocat/logcfg.json
{
    "logs": ["DEBUG", "INFO", "WARNING", "ERROR"],
    "interceptors": []
}

​
Enable only warnings and errors

.ocat/logcfg.json
{
    "logs": ["WARNING", "ERROR"],
    "interceptors": []
}
If .ocat/logcfg.json does not exist, the logger falls back to the default configuration: logs: ["DEBUG", "INFO"] with no interceptors.

​
Log file format

Each line in .ocat/logs.txt follows this format: 
[LEVEL] message
For example: 
[DEBUG] starting up
[INFO] loaded config
[WARNING] deprecated call used
[ERROR] could not open file

Projects overview

Understand project types, directory structure, and the project lifecycle.

Project configuration

Full reference for .ocat/config.json and the optional logcfg.json field.

Build docs developers (and LLMs) love

Get started for freeTalk to us