Skip to main content

Logging

Available logging destinations​

RavenDB versions up to 6.2 write log data to files on the server machine and can optionally stream it to the server console.

Starting with version 7.0, RavenDB integrates the NLog logging framework.
The logging process has hardly changed, but the integration with NLog now allows RavenDB to log more versatile data to many additional destinations via NLog plugins. Available logging destinations include, among others, log aggregators like Grafana Loki and Splunk, filtering and error handling tools, and a long list of applications that NLog is integrated with.

Logging configuration​

  • By default, RavenDB uses internal configuration keys to adjust logging.
    Using this method, you can only output data to log files and to your console.

  • If you want to utilize NLog plugins so you can output log data to additional destinations,
    you must use an external NLog configuration file.

    • Changing logging settings using an external configuration file is possible from version 7.0 on,
      as part of NLog's integration with RavenDB.
    • Once an external configuration file is applied, its settings override all the values set by internal configuration keys.
    • To set an external configuration file, see Configuring and using NLog.

  • To determine whether to use an NLog configuration file or internal configuration keys,
    set the Logs.ConfigPath configuration key with -

    • a path to the configuration file you want to apply
    • or null to continue using internal configuration keys.

  • Permanent changes to the logging configuration, whether defined via configuration keys or an external configuration file, take effect only after restarting the server.

  • Temporary changes can be applied at runtime, without requiring a server restart, using:

  • The scope of all logging settings is server-wide, applying to all databases.

Available logging levels​

Starting with version 7.0, RavenDB uses a new set of logging levels that differ from those in previous versions.

Logging modes (used in versions prior to 7.0)​

RavenDB versions up to 6.2 use a proprietary set of logging modes.

Logging ModeDescription
OperationsHigh-level info for operational use
InformationLow-level debug info
NoneLogging is disabled

NLog-compliant logging levels (version 7.0 and Above)​

Starting with version 7.0, RavenDB uses NLog-compliant logging levels.

Logging LevelDescription
TraceA highly informative level that's mostly used only during development
DebugDebug information reported by internal application processes
InfoInformation related to application progress, events lifespan, etc.
WarnWarnings returned by failed validations, mild, recoverable failures, etc.
ErrorError reports of functionality failures, caught exceptions, etc.
FatalFatal failures
OffLogging is disabled

Customizing logging level after Migration​

When migrating from an older version to 7.0 or higher, RavenDB can interpret the old logging mode configuration and translate it to the equivalent NLog level.

Logging mode (RavenDB ≤ 6.2)Equivalent NLog level (RavenDB ≥ 7.0)
OperationsInfo
InformationDebug

Logging will therefore continue uninterrupted, there's no rush to modify the logging level right after migration.

You will need to update the logging settings if you want to take advantage of NLog features.

  • For example, to use an NLog logging level such as Warn, you will need to update the settings.json file:

    ...
    "Logs.MinLevel": "Warn",
    ...

  • To output log data to a destination such as a log aggragation tool using an NLog plugin, you will need to start using an NLog configuration file, and then configure any NLog-specific settings, including the logging level, in that file:

    <rules>
    ...
    <logger ruleName="log_aggregator_1" 
            name="*" minlevel="Warn" writeTo="agg" />
    ...
    </rules>

Default values​

  • Default logging level
    The default minimal logging level is LogLevel.Info.
    To use a different level, set the Logs.MinLevel configuration key.

  • Default destination
    Log entries are written by default to log files in the Logs folder on the server machine.
    To store log files in a different path, set the Logs.Path configuration key.
    Learn how to log to additional destinations in Configuring and using NLog.

  • Default time standard
    The default time standard used for log entries is UTC.
    Changing this configuration is now available only using the NLog configuration file.

    layout="${longdate:universalTime=true}..."

  • NLog configuration file defaults
    The default values provided for settings in the NLog configuration file template are identical to those used by RavenDB's internal configuration keys. See the full list in: Logging configuration keys and their default values.

CLI customization: immediate temporary changes​

Logging settings can also be customized via the CLI, using the log command.
Unlike the permanent customization methods described above (via internal configuration keys or an external NLog file),
which require a server restart to take effect, changes made using the CLI will take effect immediately.

However, these changes are temporary: they will be overridden when the server restarts and reloads the persistent configuration from settings.json or the NLog configuration file.

Use the following syntax to customize logging via the CLI:

log [on|off] [http-]<on|off> [info|debug] [no-console]

Example:​

To temporarily change the logging level to debug, issue the following command in the server console:

ravendb> log debug

Configuring and using NLog​

To use NLog you need to:

  1. Configure RavenDB to use an external NLog configuration file
  2. Configure RavenDB to use NLog plugins for streaming log data
  3. Set your NLog configuration file

1. Configure RavenDB to use an external NLog configuration file​

NLog options are customized using an NLog configuration file. To use a custom file, set the Logs.ConfigPath configuration key to the full path of your NLog configuration file.

Example:​

To use a configuration file named NLog.config located in the RavenDB server directory, add the following line to the settings.json file:

...
"Logs.ConfigPath": "NLog.config",
...
  • Learn how to set configuration keys here.
  • Learn how to create and modify an Nlog configuration file below.
  • Note: once a configuration file is used, the logging settings defined in it will override all internal configuration keys values.

2. Configure RavenDB to use NLog plugins for streaming log data​

NLog's biggest advantage lies in its plugins library, which allows applications like RavenDB to stream log data to a wide range of destinations.

NLog plugins are distributed as Nuget packages, and you can instruct RavenDB to download and load them during startup. To do this, define the plugin’s NuGet package URL as a property of the Logs.NuGet.AdditionalPackages configuration key, with the plugin version as its value.

Example​

To load a Grafana Loki plugin, add an NLog.Targets.Loki property to RavenDB’s Logs.NuGet.AdditionalPackages configuration key, with the desired plugin version as its value.

...
"Logs.NuGet.AdditionalPackages": { "NLog.Targets.Loki": "3.3.0" },
...
  • Logs.NuGet.PackagesPath
    Use this key to specify the path where NuGet packages required by RavenDB are downloaded.
  • Logs.NuGet.PackageSourceUrl
    Use this key to set the default URL for the NuGet package source.
  • Logs.NuGet.AllowPreReleasePackages
    Use this key to determine whether RavenDB is allowed to install pre-release versions of NuGet packages.
  • Logs.NuGet.AdditionalPackages
    Use this key to specify a dictionary of additional NuGet packages to load during server startup for logging.
    Each key is a package name, and the corresponding value is the desired version.

3. Set your NLog configuration file​

Follow the procedure below to create and modify an NLog configuration file.
When you're done, restart the server to apply the new settings.

An available template:​

We've created an NLog configuration file template for your convenience,
it is available in the RavenDB server folder under the name NLog.template.config.
You can copy the template and modify it to suit your needs, or use your own configuration file if you prefer.

Mandatory logger definitions:​

Whether you base your configuration file on our template or use your own file,
make sure it includes the four logger entries defined in the template's rules section.
These definitions are mandatory, failing to include them will generate an exception at startup.

<rules>
    <!--These loggers are mandatory-->
    <logger ruleName="Raven_System" 
        name="System.*" finalMinLevel="Warn" />
    <logger ruleName="Raven_Microsoft" 
        name="Microsoft.*" finalMinLevel="Warn" />
    <logger ruleName="Raven_Default_Audit" 
        name="Audit" levels="Info" final="true" />
    <logger ruleName="Raven_Default" 
        name="*" levels="Info,Warn,Error,Fatal" writeTo="Raven_Default_Target" />
</rules>

Your own loggers:​

The Raven_Default logger, for example, directs log entries to Raven_Default_Target.
Looking at the Raven_Default_Target definition (also included in the template file)
you'll see that it outputs log data to files in the server’s Logs folder.

<target xsi:type="AsyncWrapper" name="Raven_Default_Target">
  <target
    name="FileTarget"
    xsi:type="File"
    createDirs="true"
    fileName="${basedir}/Logs/${shortdate}.log"
    archiveNumbering="DateAndSequence"
    header="Date|Level|ThreadID|Resource|Component|Logger|Message|Data"
    layout="${longdate:universalTime=true}|${level:uppercase=true}|${threadid}|
            ${event-properties:item=Resource}|${event-properties:item=Component}|
            ${logger}|${message:withexception=true}|${event-properties:item=Data}"
    footer="Date|Level|Resource|Component|Logger|Message|Data"
    concurrentWrites="false"
    writeFooterOnArchivingOnly="true"
    archiveAboveSize="134217728"
    enableArchiveFileCompression="true" />
</target>

To output log data through an NLog plugin (instead of writing to log files), you can either keep the default logger and modify its target, or define your own logger and target for the plugin.

For example, to utilize a pre-installed Loki plugin, you can -

Add a new logger:

<logger ruleName="Grafana_Loki" 
        name="*" levels="Info,Warn,Error,Fatal" writeTo="loki" />

And add a new "loki" target for this logger, specifying the properties required to connect and the log data layout for this destination.

<target 
    name="loki" 
    xsi:type="loki" 
    endpoint="https://your_end_point.net" 
    username="${your_user_name}"
    password="${your_token}"
    layout="${longdate:universalTime=true}|${level:uppercase=true}|${threadid}|
            ${event-properties:item=Resource}|${event-properties:item=Component}|
            ${logger}|${message:withexception=true}|${event-properties:item=Data}">
<label name="app" layout="layout" />
</target>

For a complete guide to integrating RavenDB 7.0 logs with Grafana Cloud using NLog and Loki, see this article.

Studio: the Admin Logs view​

The log messages generated by the server can be viewed in real time from within the Studio's Admin Logs view.
This view provides the following capabilities:

  • Displays a continuous stream of RavenDB log entries in real time.
  • Allows you to define settings that determine which log entries are written to disk.
In this article