Skip to main content

Logging and Error Reporting

Each Procivis One service writes logs to standard output. This page covers how to control what the services log and in which format, and how Core reports errors to API clients and to Sentry.

Settings on this page are given as environment variables. For other ways to configure the services, see Configuration Mechanics.

warning

Do not use trace logging in production. At this level Core logs sensitive data, including secrets.

Core​

Log format​

ONE_app__traceJson sets the format of Core's log output:

ValueOutput
falsePlaintext, one line per event. Readable in a terminal.
trueJSON, one object per event, with event fields at the top level. For log collectors that parse structured logs.
ONE_app__traceJson="true"

Log level​

ONE_app__traceLevel sets which events Core logs. Levels, from most to least verbose:

LevelLogs
traceAll technical detail, including sensitive data
debugDebugging information
infoNormal operation: startup, completed requests, database activity
warnPotential problems that do not need immediate action
errorFailures that need intervention

Each level includes all less verbose levels. For example, info also logs warn and error events.

A single level applies to all of Core:

ONE_app__traceLevel="info"

To set a different level for one component, add the crate name, or a module within a crate with ::, after the global level. More specific entries override broader ones:

ONE_app__traceLevel="info,hyper=error,sqlx::query=error"

Here most events are logged at info, and only errors are logged from the hyper crate and the sqlx::query module. Do not put spaces between entries.

If the RUST_LOG environment variable is set, Core uses it instead of ONE_app__traceLevel. It takes the same syntax.

Error responses​

By default, Core's API error responses include a cause field with internal details of the error. To remove it, set:

ONE_app__hideErrorResponseCause=true

Keep the field while you debug an installation, and remove it before you expose Core to clients you do not control.

Sentry​

Core can send error data to Sentry. Set both values; if either is missing or the DSN is empty, Sentry is off:

ONE_app__sentryDsn="https://<key>@<host>/<project>"
ONE_app__sentryEnvironment="production"

sentryEnvironment labels events in Sentry, for example production or staging. Events are also labelled with Core's version.

Core sends info, warn, and error log events to Sentry as breadcrumbs: context attached to a Sentry event. Only events that pass ONE_app__traceLevel are sent.

BFF, Bridge, and WRPR​

The Java services use Spring Boot logging. Each service reads its own settings, so set them for each service you want to change. Within a service, logging.level.root sets the level for all packages, and logging.level.<package> sets it for a single package:

logging.level.root=INFO
logging.level.org.springframework.security=DEBUG

Levels, from most to least verbose: TRACE, DEBUG, INFO, WARN, ERROR. For details, see the Spring Boot logging documentation.