Skip to main content

Logging

Available logging destinations​

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

From version 7.0 on, RavenDB incorporates 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.
    • Using an external configuration file

  • 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 in the logging configuration, through either configuration keys or an external configuration file, are applied by restarting the server.

  • It is also possible to apply temporary changes without restarting the server, using the CLI.

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

Available logging levels​

The logging levels offered by RavenDB have changed from versions prior to 7.0 to newer versions.

Logging Modes​

RavenDB versions up to 6.2 support proprietary logging modes.

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

Logging Levels​

From version 7.0 on, RavenDB's logging levels are NLog-compliant.

Available 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

When migrating from an older version to 7.0 or higher, RavenDB is capable of understanding the old version's 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 modify these settings, however, if you want to use NLog features.

  • To use an NLog logging level like Warn, for example, you will need to modify settings.json accordingly.
...
"Logs.MinLevel": "Warn",
...
  • And to output log data to a destination like a log aggragation tool through an NLog plugin, you will need to start using an NLog configuration file, and subsequently modify any NLog settings you want to change, including the logging level, in this 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.
  • 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}..."

CLI customization: immediate temporary changes​

Logging settings can also be customized via CLI, using the log command.
Unlike the permanent customization methods described above (via internal configuration keys or an external NLog file), that require a server restart to take effect, changes made using CLI commands will take immediate effect. However, they will also be overridden when the server is restarted and the permanent configuration is reloaded from settings.json or the NLog configuration file.

Use this syntax to customize logging via CLI:

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

Example:​

To temporarily change the logging level to debug, issue this 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. Install NLog plugins that RavenDB would log data through
  3. Set your NLog configuration file

NLog options are customized using an NLog configuration file.
Direct RavenDB to the location of your configuration file using the Logs.ConfigPath configuration key with the file's path as a value.

Example:​

To use a configuration file named NLog.config that resides in the RavenDB server folder, add settings.json this line:

...
"Logs.ConfigPath": "NLog.config",
...
  • Learn to set configuration keys here.
  • Learn how to create and modify a configuration file below.
  • Be aware that once a configuration file is used, the logging settings included in it will override all internal configuration keys settings.

NLog's biggest advantage lies in its plugins library, through which applications like RavenDB can stream log data to a variety of destinations.
NLog plugins are available as Nuget packages, that we can easily instruct RavenDB to load and run during startup.
We do this by defining the plugin Nuget package URL as a property of the Logs.NuGet.AdditionalPackages configuration key, with the plugin version we want to use as a value.

Example​

To load a Grafana Loki plugin, for example, add RavenDB's Logs.NuGet.AdditionalPackages configuration key an NLog.Targets.Loki property, with the plugin's version you want to use as a value.

settings.json:

...
"Logs.NuGet.AdditionalPackages": { "NLog.Targets.Loki": "3.3.0" },
...

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 by your needs, or use your own configuration file, as you prefer.

Mandatory logger definitions:​

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

<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 records to Raven_Default_Target.
Looking at the Raven_Default_Target definition (also included in the template file) we can see that this target outputs log data to log 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 (rather than into log files) you can either leave the default logger as is and modify its target, or add your own logger and target.

To utilize a pre-installed Loki plugin, for example, 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, that specifies the logging properties 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" />

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

Studio: Admin Logs​

Another way to view debug (or any other level) logs without having to restart the server, is Studio's Admin Logs view.