Logging

Customizing logging level after Migration:

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 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.
  

  • settings.json

  ...
  "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.
  

  • nlog.config

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

1. Configure RavenDB to use an external 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",
...

2. Load and run NLog plugins Nuget packages

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" },
...

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 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" />