Documentation

Introduction

RESTHeart uses for logging the LogBack implementation of SLF4J.

Default LogBack configuration

restheart.jar embeds the following default logback.xml configuration.

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <withJansi>true</withJansi>
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %highlight(%-5level) %logger{36} - %msg%n %throwable{short}</pattern>
        </encoder>
    </appender>

    <root level="ERROR">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>

Important

the default configuration logs messages only from the packages org.restheart and com.restheart. If you are developing a plugin, you’ll need to modify the configuration to get log messages from your classes.

The following command executes RESTHeart overriding the configuration to enable logging from the classes of the package com.foo.bar and its sub-packages:

$ RHO='/logging/packages -> [ "org.restheart", "com.restheart", "com.foo.bar" ]' java -jar restheart.jar

Logging configuration

The default logging configuration follows:

# Logging
# see https://restheart.org/docs/logging
# Options:
# - log-level: to set the log level. Value can be OFF, ERROR, WARN, INFO, DEBUG, TRACE and ALL. (default value is INFO)
# - log-to-console: true => log messages to the console (default value: true)
# - ansi-console: use Ansi console for logging. Default to 'true' if parameter missing, for backward compatibility
# - log-to-file: true => log messages to a file (default value: false)
# - log-file-path: to specify the log file path (default value: restheart.log in system temporary directory)
# - packages: only messages form these packages are logged, e.g. [ "org.restheart", "com.restheart", "io.undertow", "org.mongodb" ]
# - full-stacktrace: true to log the full stackstrace of exceptions
# - requests-log-mode: 0 => no log, 1 => light log, 2 => detailed dump (use 2 only for development, it can log credentials)
# - tracing-headers (default, empty = no tracing): add tracing HTTP headers (Use with %X{header-name} in logback.xml); see https://restheart.org/docs/auditing

logging:
  log-level: INFO
  log-to-console: true
  ansi-console: true
  log-to-file: false
  log-file-path: restheart.log
  packages: [ "org.restheart", "com.restheart" ]
  full-stacktrace: false
  requests-log-mode: 1
  tracing-headers:
  #  - x-b3-traceid      # vv Zipkin headers, see https://github.com/openzipkin/b3-propagation
  #  - x-b3-spanid
  #  - x-b3-parentspanid
  #  - x-b3-sampled      # ^^
  #  - uber-trace-id     # jaeger header, see https://www.jaegertracing.io/docs/client-libraries/#trace-span-identity
  #  - traceparent       # vv opencensus.io headers, see https://github.com/w3c/distributed-tracing/blob/master/trace_context/HTTP_HEADER_FORMAT.md
  #  - tracestate        # ^^

Specify a custom LogBack configuration

To define a different LogBack configuration, set the property logback.configurationFile, as follows:

$ java -Dlogback.configurationFile=./logback.xml -jar restheart.jar

Custom LogBack with docker compose

To use a custom LogBack configuration when running RESTHeart with docker compose:

override the entrypoint to specify the logback.configurationFile JVM property
mount the custom logback.xml configuration file into the docker image using volume

Replace the restheart service definition in the docker-compose.yml with the following:

    restheart:
        image: softinstigate/restheart:latest
        container_name: restheart
        # override the entrypoint to specify the logback.configurationFile JVM property
        entrypoint: [ "java", "-Dfile.encoding=UTF-8", "-Dlogback.configurationFile=etc/logback.xml", "-server", "-jar", "restheart.jar", "etc/restheart.yml"]
        # mount the custom `logback.xml` configuration file
        volumes:
            - ./etc/logback.xml:/opt/restheart/etc/logback.xml:ro
        command: ["--envFile", "/opt/restheart/etc/default.properties"]
        environment:
        RHO: >
            /mclient/connection-string->"mongodb://mongodb";
            /http-listener/host->"0.0.0.0";
        depends_on:
        - mongodb
        - mongodb-init
        ports:
        - "8080:8080"

Example: print the full stack trace

The following command sets the configuration option /logging/full-stacktrace to true to configure the logback appender to log the full stack trace of exceptions

$ RHO='/logging/full-stacktrace->true' java -jar restheart.jar

Note	`/logging/full-stacktrace` is available from RESTHeart 7.2.0. For previous releases you need to specify a custom `logback.xml` configuration file.

Example: enable logging from the MongoDB driver

To enable logging from the MongoDB driver, override the configuration option /logging/packages as follows:

$ RHO='/logging/packages -> [ "org.restheart", "com.restheart", "org.mongodb" ]' java -jar restheart.jar

Example: log trace headers

Trace headers allow to trace a request context propagation across service boundaries. See for reference b3-propagation

Too enable log trace headers first override the /logging/equests-log-trace-headers configuration options

Then a custom logback.xml with the following pattern (note that it includes %X{x-b3-traceid}) must be used:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <withJansi>true</withJansi>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread / %X{x-b3-traceid}] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="ERROR">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>

$ RHO='/logging/requests-log-trace-headers -> [ "x-b3-traceid", "uber-trace-id", "traceparent" ]' java -Dlogback.configurationFile=./logback.xml -jar restheart.jar

Note	Watch Logging