Skip to main content

Set Logs Configuration Operation

  • Logging settings are loaded from configuration sources (environment variables, settings.json, or command-line arguments) when the server starts. Command-line arguments override settings.json, and settings.json overrides environment variables.

  • After the server is up and running,
    you can override the logging minimum level and configure logging filters at runtime:

    • From the Client API - use SetLogsConfigurationOperation, as explained below.
    • From the Studio - see: Admin Logs view.

  • Learn more about RavenDB's logging system in the Logging article.

  • In this article:

Set logs configuration​

  • The default minimum log level for server logs is LogLevel.Info.
    You can override this level and apply filters to control which log entries are written.

  • Setting persist to true in the operation will persist only the minimum level to the settings.json file.
    The value will be written under the Logs.MinLevel configuration key.
    Filter rules are currently Not persisted and must be reapplied after a server restart.

// Define the logs configuration:
var configuration = new SetLogsConfigurationOperation.LogsConfiguration
{
    // Override the default minimum log level.
    // Only messages at 'Warn' level or higher will be written.
    MinLevel = LogLevel.Warn,

    // Apply filters:
    Filters = new List<LogFilter>
    {
        // Log entries for database "DB1" that include an exception:
        new LogFilter(
            minLevel: LogLevel.Error,
            maxLevel: LogLevel.Fatal,
            condition:
                "contains('${event-properties:item=Resource}', 'DB1') and exception != null",
            action: LogFilterAction.LogFinal
        ),

        // Log entries that exceed 200 characters in length.
        // Note: Although this filter starts at 'Debug',
        //       entries must still pass the global 'Warn' level to be logged.
        new LogFilter(
            minLevel: LogLevel.Debug,
            maxLevel: LogLevel.Fatal,
            condition: "length(message) > 200",
            action: LogFilterAction.LogFinal
        )
    },
    
    // The default action to take if no filter matches.
    LogFilterDefaultAction = LogFilterAction.IgnoreFinal 
};

// Define the set logs configuration operation:
// Setting 'persist' to true will persist only the min level to settings.json    
var setLogsOp = new SetLogsConfigurationOperation(configuration, persist: true)    

// Execute the operation by passing it to 'Maintenance.Server.Send'
store.Maintenance.Server.Send(setLogsOp);

If you're using an external NLog.config file,
you can define the logging level and filters directly in the XML file using <logger> and <rules>.

  • To learn how to use NLog for log filtering and routing, see: Configuring and using NLog.

  • Note: When an external NLog config file is used, its settings override any values set via SetLogsConfigurationOperation.

Set Microsoft logs configuration​

  • The default minimum log level for Microsoft logs is LogLevel.Error.
    You can override this level to control which log entries are written.

  • To persist this minimum level to the settings.json file, set persist to true.
    The value will be written under the Logs.Microsoft.MinLevel configuration key.
    If set to false, the change will take effect immediately but will Not be saved across server restarts.

  • To configure Microsoft logs,
    you must first enable them by setting "Logs.Microsoft.Enabled": "true" in the settings.json file.
  • This change requires a server restart to take effect.
// Define Microsoft logs configuration:    
var configuration = new SetLogsConfigurationOperation.MicrosoftLogsConfiguration()
{
   MinLevel = LogLevel.Debug 
};
    
// Define the set logs configuration operation.
// Setting 'persist' to true will persist the min level to settings.json
var setLogsOp = new SetLogsConfigurationOperation(configuration, persist: true);

// Execute the operation by passing it to 'Maintenance.Server.Send'
store.Maintenance.Server.Send(setLogsOp);

Set admin logs configuration​

  • The admin logs are displayed in the Admin Logs view in the Studio, under the Logs on this view section.
    This is a live stream of recent log activity shown only in the UI.

  • These logs are configured separately from the logs that are written to disk. Any settings you apply here, such as the minimum level or filters, apply only to the admin logs displayed in the Studio and do not affect the server logs saved on disk. These changes are applied immediately and will affect all open Studio sessions that are displaying the Admin Logs view.

  • While these logs can be exported, their settings are Not persisted (even if you set persist to true in the operation).

  • The default minimum log level for admin logs is LogLevel.Trace.

var configuration = new SetLogsConfigurationOperation.AdminLogsConfiguration()
{
   MinLevel = LogLevel.Info,
    
   Filters = new List<LogFilter>
   {
       // Log entries associated with index "MyIndex":
       new LogFilter(
           minLevel: LogLevel.Info, 
           maxLevel: LogLevel.Fatal,
           condition: "contains('${event-properties:item=Component}', 'MyIndex')",
           action: LogFilterAction.LogFinal),
   },
    
   LogFilterDefaultAction = LogFilterAction.IgnoreFinal 
};
    
// Define the set logs configuration operation.
var setLogsOp = new SetLogsConfigurationOperation(configuration);

// Execute the operation by passing it to 'Maintenance.Server.Send'.
// The changes apply immediately to all open Studio sessions.
store.Maintenance.Server.Send(setLogsOp);

Syntax​

// Available overloads:
public SetLogsConfigurationOperation(LogsConfiguration configuration, bool persist = false)
public SetLogsConfigurationOperation(MicrosoftLogsConfiguration configuration, bool persist = false) 
public SetLogsConfigurationOperation(AdminLogsConfiguration configuration, bool persist = false)

SetLogsConfigurationOperation.LogsConfiguration​

public class LogsConfiguration
{
    // The minimum log level that will be written to the server log.
    // Will be persisted to the 'settings.json' file if 'persist' is true.
    public LogLevel MinLevel { get; set; }
    
    // A list of active log filters that determine whether specific log entries 
    // should be included or excluded.
    public List<LogFilter> Filters { get; set; } = new();
    
    // This action does Not apply when no filters are defined.
    // This action applies only in the following cases:
    // * When a log entry does Not match any defined filter.
    // * When a log entry matches a filter with a 'Neutral' action, 
    //   provided that no subsequent filters apply.
    public LogFilterAction LogFilterDefaultAction { get; set; }
}

SetLogsConfigurationOperation.MicrosoftLogsConfiguration​

public class MicrosoftLogsConfiguration
{
    // The minimum log level that will be written to Microsoft logs.
    // Will be persisted to the 'settings.json' file if 'persist' is true.
    public LogLevel MinLevel { get; set; }
}

SetLogsConfigurationOperation.AdminLogsConfiguration​

public class AdminLogsConfiguration
{
    // The minimum log level that will be written to the Admin Logs visible in the Studio.
    // This value is Not persisted to the 'settings.json' file. (even if persist is true).
    public LogLevel MinLevel { get; set; }
    
    public List<LogFilter> Filters { get; set; } = new();
    
    public LogFilterAction LogFilterDefaultAction { get; set; }
}
public class LogFilter
{
    // A log entry matches the filter if:
    // - its log level is between MinLevel and MaxLevel (inclusive),
    // - it passes the global minimum level ('CurrentMinLevel'), and
    // - it satisfies the condition.
    
    // The minimum log level this filter applies to. 
    public LogLevel MinLevel { get; internal set; }
    
    // The maximum log level this filter applies to.
    public LogLevel MaxLevel { get; internal set; }

    // An NLog expression evaluated against the log entry; must return true for the filter to match.    
    public string Condition { get; internal set; }
    
    // The action to take when a log entry matches this filter.
    // Determines whether the entry is logged, ignored, or passed to the next filter.
    public LogFilterAction Action { get; internal set; }
}
public enum LogLevel
{
    Trace = 0,
    Debug = 1,
    Info = 2,
    Warn = 3,
    Error = 4,
    Fatal = 5,
    Off = 6
}
     
public enum LogFilterAction
{
    // The action to take is deferred to the next filter that matches the log entry. 
    // If no other filter matches, the "Default Filter Action" will be applied.
    Neutral,
     
    // The log entry will be logged.
    Log,
     
    // The log entry will Not be logged.
    Ignore,
     
    // The log entry will be logged.
    // Any subsequent filters with the same logging-rules as this filter will be ignored. 
    LogFinal,
     
    // The log entry will Not be logged.
    // Any subsequent filters with the same logging-rules as this filter will be ignored.
    IgnoreFinal
In this article