Monitoring your OpenProject installation

OpenProject provides different means of monitoring and auditing your application.

Logging information

In production, OpenProject uses Lograge formatter key_value logger by default. Every request will result in the following info log level:

I, [2023-11-14T09:21:15.136914 #56791]  INFO -- : [87a5dceb-0560-4e17-8577-2822106dfc00] method=GET path=/ format=html controller=HomescreenController action=index status=200 allocations=133182 duration=237.82 view=107.45 db=116.50 user=85742

This formatter makes it easy to parse and analyze logs. Let's take a look at the values:

Displaying and filtering log files

Packaged installation

In a package-based installation, the openproject command line tool can be used to see the log information. The most typically use case is to show/follow all current log entries. This can be accomplished using the the –tail flag. See example below:

sudo openproject logs --tail

You can abort this using Ctrl + C.

systemd / journalctl

On most distributions, OpenProject does not maintain its own log files, but sends logs directly to journalctl. On older distributions that use either sysvinit or upstart, all the logs are stored in /var/log/openproject/.

You can get all logs of the web processes like this:

journalctl -u openproject-web-1

Likewise, to get all logs of the background worker processes:

journalctl -u openproject-worker-1

journalctl has flexible filtering options to search for logs. For example, add --since "1 hour ago" to show logs printed in the past hour.

Docker-compose

In a docker-based installation, all logs are redirected to STDOUT so you can use the normal docker tools to manage your logs.

For instance for the Compose-based installation:

docker-compose logs -f --tail 1000

All-in-one / Slim docker container

docker logs -f --tail 1000 openproject

Raising the log level

OpenProject can log at different service levels, the default being info. You can set the environment variable OPENPROJECT_LOG__LEVEL to any of the following values:

• debug: All activity, resulting in the highest amount of logging
• info: Common activities such as user logins (when enabled) and information about requests, including warnings and errors
• warn: Operational warnings that might need resolution as well as error messages
• error Caught or uncaught application errors, as well as fatal errors.

For example, to set this in the packaged installation, use the following command:

openproject config:set OPENPROJECT_LOG__LEVEL="debug"
service openproject restart

For Docker-based installations, add the ENV variable to your env file and restart the containers.

Prometheus metrics

OpenProject can give metrics suitable to use with Prometheus.

To enable this option the environment variable OPENPROJECT_PROMETHEUS_EXPORT has to be set to true. Yabeda Prometheus gem is used with ActiveRecord, Rails and Puma plugins.

Listening address is configured via PROMETHEUS_EXPORTER_BIND env variable with default 0.0.0.0. Port is configured by PROMETHEUS_EXPORTER_PORT variable with default 9394. Both provided by Prometheus gem.

Health checks

OpenProject uses the okcomputer gem to provide built-in health checks on database, web, and background workers.

We provide the following health checks:

• https://your-hostname.example.tld/health_checks/default - An application level check to ensure the web workers are running.
• https://your-hostname.example.tld/health_checks/database - A database liveliness check.
• https://your-hostname.example.tld/health_checks/mail - SMTP configuration check.
• https://your-hostname.example.tld/health_checks/puma - A check on Puma web server.
• https://your-hostname.example.tld/health_checks/worker - A check to ensure background jobs are being processed.
• https://your-hostname.example.tld/health_checks/worker_backed_up - A check to determine whether background workers are at capacity and might need to be scaled up to provide timely processing of mails and other background work.
• https://your-hostname.example.tld/health_checks/all - All of the above checks and additional checks combined as one. Not recommended as the liveliness check of a pod/container.

Optional authentication

You can optionally provide a setting health_checks_authentication_password (OPENPROJECT_HEALTH__CHECKS__AUTHENTICATION__PASSWORD) that will add a basic auth challenge to the /health_checks endpoint. Please be aware that this might break existing container health services in place in the docker-compose and k8s based deployments, so use with care or prefer to use a network based separation instead on your proxy level.

Logging concept

This section describes how OpenProject supports common security logging requirements such as those defined by the BSI IT-Grundschutz module OPS.1.1.5 (A1 & A3), which require a range of security-relevant events to be logged in accordance with a logging concept.

OpenProject covers application-level logging, including request logs, authentication-related events, application errors and security-relevant application behavior. Whether an event is logged depends on the configured log level, which defaults to info and includes these events by default.

OpenProject does not itself cover operating system, network, host, file-integrity or infrastructure audit events. Regardless of how OpenProject is deployed (packaged installation, Docker Compose, all-in-one Docker image, Kubernetes/Helm or Terraform), logging responsibility is distributed across several layers:

• OpenProject application logs: request logs, authentication events, application errors and security-relevant application behavior.
• Deployment platform logs: events from the platform running OpenProject, for example systemd/journalctl on packaged installs, container logs on Docker/Compose, or workload lifecycle, secrets/configuration changes and RBAC on Kubernetes.
• Infrastructure / provider logs: operated by the platform operator or infrastructure provider (OS, container runtime, storage, network, host-level), including resources managed through infrastructure-as-code such as Terraform.

Application logs are available through the standard logging sinks described above (journalctl, docker logs, STDOUT) and can be forwarded to a central logging system or through OpenTelemetry integrations.

Coverage of security logging requirements

The following table maps common security logging requirements to the layer that covers them and OpenProject's scope for each.

References

• Every request is logged with the acting user, HTTP method, route and performed action. See Logging information above and the ApplicationController request logging.
• All request logs, including status, routes and performed action, are part of the Ruby on Rails framework standards.