Explaining and changing logging levels in Document Server

Resources Hub
1

ONLYOFFICE Docs (Document Server) allows controlling how much information to print to logs — for example, to troubleshoot performance issues, inspect logs, or collect information for support. In this guide we will cover all information about the levels that Document Server offers under the hood and how to change them.

Let’s start with basic info:

Locations of logs

The logs are stored in the following locations (depending on the installation type):

  • For Windows - C:\Program Files\ONLYOFFICE\DocumentServer\Log;
  • For Linux - /var/log/onlyoffice/documentserver;
  • For Docker - /var/log/onlyoffice/documentserver (within the Docker container) and /app/onlyoffice/DocumentServer/logs/documentserver (on the host if you mount the volume).

Note: these are default paths, if changed, please refer to set up location.

In all of these paths you can find /docservice and /converter folders that contain out.log files with actual logs. Everything related to opening and conversion processes is located under /converter folder, obviously; /docservice bears the rest of information.

Logging levels you may find

Document Server prints following levels to logs:

  • WARN – Normal workflow, sometimes shows when something is off.
  • DEBUG/TRACE – Internal behavior. These explain how the application operates, including occurred errors. They’re usually off in production.
  • INFO – Business-as-usual. If everything is healthy, most of your logs live here.
  • ERROR – A failure occurred. This should be actionable and measurable.
  • FATAL – Your application is about to terminate due to an unrecoverable error.

Basically, all of these levels display the state of an operation and/or the application itself. However, depending on the level used, not every level gets printed, please refer to the table below:

Configured level What gets emitted
TRACE TRACE, DEBUG, INFO, WARN, ERROR, FATAL
DEBUG DEBUG, INFO, WARN, ERROR, FATAL
INFO INFO, WARN, ERROR, FATAL
WARN (default) WARN, ERROR, FATAL
ERROR ERROR, FATAL
FATAL FATAL only

You can set up necessary level from the table above to make Document Server include specific levels to the logging flow for your information.

Changing logging level in Document Server

You can change the logging level to any of those we’ve described earlier, however, in most cases you need either default WARN or DEBUG levels. We’ll demonstrate how to set everything up to print all logs in debug mode.

Using Docker

If you are using Docker as the installation type for your instance, you can set up logging level beforehand with environment variable DS_LOG_LEVEL.

For instance, running a Docker container with docker run:

docker run -i -t -d -p 8080:80 \
  -e DS_LOG_LEVEL=DEBUG \
  onlyoffice/documentserver:latest

Or using Docker Compose:

  1. Set the environment variable in docker-compose.yml when running the container:
services:
    documentserver:
      image: onlyoffice/documentserver:latest
      container_name: documentserver
      restart: always
      environment:
        - DS_LOG_LEVEL=DEBUG
      ports:
        - "8080:80"
  1. Start Docker Compose:
docker-compose up -d

Using the log4js configuration file

  1. Open the log4js configuration file. The path to the file depends on the operating system you use:
  • For Windows - C:\Program Files\ONLYOFFICE\DocumentServer\config\log4js\production.json
  • For Linux - /etc/onlyoffice/documentserver/log4js/production.json
  • For Docker - /etc/onlyoffice/documentserver/log4js/production.json (within the Docker container)
  1. Refer to the following code block:
{
  "categories": {
    "default": {
      "appenders": [
        "default"
      ],
      "level": "WARN"
    }
  }
}
  1. Change the level value from "WARN" to "DEBUG";
  2. Save the changes in the production.json configuration file;
  3. Apply the changes executing the following command:
  • Linuxsystemctl restart ds-*;
  • Dockersupervisorctl restart all;
  • Or restart the ONLYOFFICE DocumentServer Proxy service for Windows:
net stop DsProxySvc
net start DsProxySvc
net stop DsConverterSvc
net start DsConverterSvc
net stop DsDocServiceSvc
net start DsDocServiceSvc

What is that for?

Changing the logging level controls how much information Document Server records. Use a lower level such as TRACE or DEBUG when investigating a problem and you need more detail; use WARN or ERROR when you mainly want to see potential or actual problems. In short, the logging level lets you balance useful diagnostic information against log volume and noise.

Note: DEBUG and TRACE are much more verbose than WARN. Enable them only while investigating, then switch back to WARN.

1 Like