Logging Configuration

You have an ability to set up the logging process for collecting and recording access to the Web Service, requests and results of execution, etc.

There are three types of logs available in the scope of the Document Reader Web Service:

Access Logs — logs of accessing the Document Reader Web Service via HTTP
Application Logs — logs of operations during the application execution
Processed Results Logs — logs of requests and results in JSON format

Access Logs

Access logs represent the logs of the accessing the Document Reader Web Service via HTTP.

To set up the access logs during the Web Service startup, use:

config.yaml

service:
  webServer:
    logging:
      level: "INFO"
      formatter: "text"

      access:
        enabled: false
        console: true
        path: "logs/docreader-access.log"

Parameter	Type	Default	Description
`level`	string	`"INFO"`	Logging level (severity). Defines the events that are recorded by their urgency. Available values: `"ERROR"` — to log only the issues, preventing the service from proper functioning `"WARN"` — to log errors and issues that may disturb the execution process, but not necessarily represent the failure `"INFO"` — to log errors, warnings, and any events that are crucial from the features standpoint `"DEBUG"` — to log errors, warnings, info, and additional verbose diagnostic data
`formatter`	string	`"text"`	Logs format. Possible values: `"text"` or `"json"`. (Some log collectors require logs in JSON format.)
`enabled`	boolean	`false`	Whether to save access logs to a file. Writing logs into a file, instead of stdout, may consume a significant amount of space (up to several dozen of Mbs). Consider enabling them wisely. For the access and applications log files, a day-based rotation occurs every midnight UTC. The service keeps the last 30 days of log files.
`console`	boolean	`true`	Whether to print access logs to a console.
`path`	string	`"logs/access/docreader-access.log"`	If `logging` → `access` → `enabled`, specifies the custom file path to save access logs.

Administration instructions for managing the logging process:

DockerLinux

The Access logs are effectively the gunicorn server Access log file.

To enable the Document Reader Access logs, set the YAML parameter service → webServer → logging → access → enabled to true.

You can customize the access log file location via the service → webServer → logging → access → path YAML parameter.

To get access to the Access log file from the host machine:

Create a folder for logs and ensure the group is root and group members have the write & execute permissions over the created folder.
Mount the host folder to the application log folder inside the container:

mkdir ~/docreader-logs
chmod g+wx ~/docreader-logs
sudo chgrp root ~/docreader-logs

docker run -p host_port:8080 -v host_path_to_license_folder/regula.license:/app/extBin/unix/regula.license -v ~/docreader-logs:/app/logs -e regulaforensics/docreader

The Access logs are effectively the gunicorn server Access log file.

To enable the Document Reader Access logs, set the environment variable service → webServer → logging → access → enabled to true at the /opt/regula/document-reader-webapi/config.yaml file.

You сan customize the access log file location via the service → webServer → logging → access → path YAML parameter.

Note that the application should have the write permission on the folder where logs will be stored.

Application Logs

Application Logs are the logs of application execution, including errors and debug messages.

To set up the application logs during the Web Service startup, use:

config.yaml

service:
  webServer:
    logging:
      level: "INFO"
      formatter: "text"

      app:
        enabled: false
        console: true
        path: "logs/docreader-app.log"

Parameter	Type	Default	Description
`level`	string	`"INFO"`	Logging level (severity). Defines the events that are recorded by their urgency. Available values: `"ERROR"` — to log only the issues, preventing the service from proper functioning `"WARN"` — to log errors and issues that may disturb the execution process, but not necessarily represent the failure `"INFO"` — to log errors, warnings, and any events that are crucial from the features standpoint `"DEBUG"` — to log errors, warnings, info, and additional verbose diagnostic data
`formatter`	string	`"text"`	Logs format. Possible values: `"text"` or `"json"`. (Some log collectors require logs in JSON format.)
`enabled`	boolean	`false`	Whether to save application logs to a file. Writing logs into a file, instead of stdout, may consume a significant amount of space (up to several dozen of Mbs). Consider enabling them wisely. For the access and applications log files, a day-based rotation occurs every midnight UTC. The service keeps the last 30 days of log files.
`console`	boolean	`true`	Whether to print application logs to a console.
`path`	string	`"logs/app/docreader-app.log"`	If `logging.app.enabled`, specifies the custom file path to save access logs.

Administration instructions for managing the logging process:

DockerLinux

The Application logs are effectively the gunicorn server Application log file.

To enable the Document Reader Application logs, set the YAML parameter variable service → webServer → logging → app → enabled to true.

You can customize the application log file location via the service → webServer → logging → app → path YAML parameter.

To get access to the Application log file from the host machine:

Create a folder for logs and ensure the group is root and group members have the write & execute permissions over the created folder.
Mount the host folder to the application log folder inside the container:

mkdir ~/docreader-logs
chmod g+wx ~/docreader-logs
sudo chgrp root ~/docreader-logs

docker run -p host_port:8080 -v host_path_to_license_folder/regula.license:/app/extBin/unix/regula.license -v ~/docreader-logs:/app/logs -e regulaforensics/docreader

The Application logs are effectively the gunicorn server Application log file.

To enable the Document Reader Application logs, set the YAML parameter service → webServer → logging → app → enabled to true at the /opt/regula/document-reader-webapi/config.yaml file.

You can customize the application log file location via the service → webServer → logging → app → path YAML parameter.

Note that the application should have the write permission on the folder where logs will be stored.

Processed Results Logs

The Document Processed Results Logs keep the input requests and the execution results in JSON format.

To set up the processed results logs during the Web Service startup, use:

config.yaml

service:
  processing:
      results:
        saveResult: true
        location:
          bucket: "docreader-processing"
          container: "docreader-processing"
          folder: "output"
          prefix: "processing"

Parameter	Type	Default	Description
`saveResult`	boolean	`false`	Whether to save the results of the requests processing.
`bucket`	string	`docreader-processing`	Location (bucket) where to save processing results in the case of the Google Cloud Storage or Amazon S3.
`container`	string	`docreader-processing`	Location (container) where to save processing results in the case of the Microsoft Azure.
`folder`	string	`output`	Location (folder) where to save processing results in the case of the local file system. May represent an absolute path.
`prefix`	string	—	Single prefix line for all defined locations. When set, gives ability to keep the stored processing results in a more organized way regardless of the selected storage type.

Administration instructions for managing the logging process:

DockerLinux

The Document Reader Processed results logs are the artifacts of the processed request.

To enable the processed results logs, use any parameter of the processing section.

To enable the recording of both requests and results, set the YAML parameter service → processing → results → saveResult → enabled to true.

You can customize the processed results log folder path via the service → processing → results → location YAML parameter.

To get access to the processed results logs from the host machine:

Create a folder for logs and ensure the group is root and group members have the write & execute permissions over the created folder.
Mount the host folder to the application log folder inside the container:

mkdir ~/docreader-logs
chmod g+wx ~/docreader-logs
sudo chgrp root ~/docreader-logs

docker run -p host_port:8080 -v host_path_to_license_folder/regula.license:/app/extBin/unix/regula.license -v ~/docreader-logs:/app/logs -e regulaforensics/docreader

The Document Reader Processed results logs are the artifacts of the processed request.

To enable the processed results logs, use any parameter of the processing section.

To enable the recording of both requests and results, set the YAML parameter service → processing → results → saveResult → enabled to true.

You can customize the processed results log folder path via the service → processing → results → location YAML parameter.

Note that the application should have write permision on the folder where logs will be stored.