Skip to main content

Logging: Client API

C#

Retrieve the logging configuration​

To retrieve the server's current logging configuration, use the GetLogsConfigurationOperation method:

GetLogsConfigurationResult logsConfiguration =
    store.Maintenance.Server.Send(new GetLogsConfigurationOperation());

The returned GetLogsConfigurationResult object reports four groups of settings: the server logs, the audit logs, the Microsoft logs, and the admin logs (the live stream shown in Studio's Admin Logs view).
See the full shape of each group in the Syntax section.

Change the logging configuration at runtime​

Use the SetLogsConfigurationOperation method to change parts of the logging configuration while the server is running, without a restart.

  • The operation accepts a persist flag: set it to true to also write the new minimum log level to the settings.json file, so the change survives a restart.

  • Only the minimum log level is persisted; filters are not, and must be reapplied after a restart.

  • When an external NLog configuration file is applied, its settings override any values set with this operation.

Server logs​

The default minimum level for the server logs is LogLevel.Info.
You can override this level, and optionally apply filters that log or ignore specific entries:

// Define the server 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,

    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 longer than 200 characters.
        // Note: although this filter starts at 'Debug',
        //       an entry 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 when no filter matches:
    LogFilterDefaultAction = LogFilterAction.IgnoreFinal
};

// 'persist: true' writes only the minimum log level to settings.json:
var setLogsOp = new SetLogsConfigurationOperation(configuration, persist: true);
store.Maintenance.Server.Send(setLogsOp);

Microsoft logs​

The default minimum level for the Microsoft logs is LogLevel.Error.
Microsoft logs must first be enabled by setting Logs.Microsoft.Enabled to true, which requires a restart; you can then adjust their level at runtime as follows:

var configuration = new SetLogsConfigurationOperation.MicrosoftLogsConfiguration
{
    MinLevel = LogLevel.Debug
};

// 'persist: true' writes the minimum log level to settings.json:
var setLogsOp = new SetLogsConfigurationOperation(configuration, persist: true);
store.Maintenance.Server.Send(setLogsOp);

Admin logs​

The admin logs are the live stream shown in Studio's Admin Logs view.
Settings you apply to the admin logs affect only this view (not the logs written to disk), take effect immediately for all open Studio sessions, and are never persisted (even with persist: true). The default minimum level 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
};

var setLogsOp = new SetLogsConfigurationOperation(configuration);
store.Maintenance.Server.Send(setLogsOp);

Syntax​

Methods​

Retrieves the server's current logging configuration.

public GetLogsConfigurationOperation()

Usage:

GetLogsConfigurationResult logsConfiguration =
    store.Maintenance.Server.Send(new GetLogsConfigurationOperation());

Return value:

TypeDescription
GetLogsConfigurationResultThe server's logging configuration (see Classes below)

Classes​

The retrieved result​

The result of GetLogsConfigurationOperation, grouping the settings by target.

class GetLogsConfigurationResult
{
    LogsConfiguration Logs
    AuditLogsConfiguration AuditLogs
    MicrosoftLogsConfiguration MicrosoftLogs
    AdminLogsConfiguration AdminLogs
}

PropertyTypeDescription
LogsLogsConfigurationThe server-logs settings
AuditLogsAuditLogsConfigurationThe audit-logs settings
MicrosoftLogsMicrosoftLogsConfigurationThe Microsoft-logs settings
AdminLogsAdminLogsConfigurationThe admin-logs settings shown in Studio

Retrieved server and audit log settings​

The current server-logs settings.

class LogsConfiguration
{
    string Path
    LogLevel MinLevel
    LogLevel CurrentMinLevel
    List<LogFilter> CurrentFilters
    LogFilterAction CurrentLogFilterDefaultAction
    long ArchiveAboveSizeInMb
    int? MaxArchiveDays
    int? MaxArchiveFiles
    bool EnableArchiveFileCompression
}

PropertyTypeDescription
PathstringDirectory where log files are written
MinLevelLogLevelDefault minimum level from Logs.MinLevel in settings.json; fixed at server start
CurrentMinLevelLogLevelMinimum level currently written to disk; changeable at runtime, falls back to MinLevel
CurrentFiltersList<LogFilter>The active log filters
CurrentLogFilterDefaultActionLogFilterActionThe action when an entry matches no filter
ArchiveAboveSizeInMblongSize (MB) a log file reaches before it is archived
MaxArchiveDaysint?Days to retain an archived file
MaxArchiveFilesint?Number of archived files to keep
EnableArchiveFileCompressionboolWhether archived files are compressed

Retrieved Microsoft and admin log settings​

The current Microsoft-logs settings.

class MicrosoftLogsConfiguration
{
    LogLevel CurrentMinLevel
    LogLevel MinLevel
}

PropertyTypeDescription
CurrentMinLevelLogLevelMinimum level currently applied
MinLevelLogLevelDefault minimum level from settings.json

The configuration you set​

These classes are nested in SetLogsConfigurationOperation.

Server-logs settings to apply.

class LogsConfiguration
{
    LogLevel MinLevel
    List<LogFilter> Filters
    LogFilterAction LogFilterDefaultAction
}

PropertyTypeDescription
MinLevelLogLevelThe minimum level for the server logs; written to settings.json when persist is true
FiltersList<LogFilter>The log filters to apply
LogFilterDefaultActionLogFilterActionThe action when an entry matches no filter

Shared types​

A rule that logs or ignores entries matching a level range and condition.

class LogFilter
{
    LogLevel MinLevel
    LogLevel MaxLevel
    string Condition
    LogFilterAction Action
}

PropertyTypeDescription
MinLevelLogLevelLowest level the filter applies to
MaxLevelLogLevelHighest level the filter applies to
ConditionstringAn NLog expression; must return true for the filter to match
ActionLogFilterActionThe action taken when an entry matches

In this article