Logging

Configuring Serilog sinks

Softadmin logs to the database by default, and this behavior cannot be configured. To additionally log information to the Windows Event Log or to a log file, you must create a serilog.json configuration file.

The serilog.json file must be configured separately for each application. This means that Softadmin® and Publish can use different logging configurations if required.

As the serilog.json file is project specific, the file should be placed inside the folder of the specified project. For a publish app this would be: \publish\serilog.json while for the Softadmin® project it would be placed in the project root.

Supported sinks

The following sinks are supported:

• SoftadminEventLog
  Logs to the Windows Event Log and comes preconfigured with the same logging information that is stored in ADMINLog. This sink preserve the output format that was used for the Event Log before Serilog was used.
• EventLog
  Also logs to the WinodwsEvent Log, but does not include the custom formatting and data enrichment provided by SoftadminEventLog.
• File
  Logs to files. This sink does not include data from ADMINLog, but it supports custom ouput formatting.

Creating an Event Source

If you want to log to the Windows Event Log, you must first create an Event Source. This can be done by using the following command in PowerShell:

New-EventLog -LogName Application -Source #EventSourceName#

Replace #EventSourceName# with a unique event source name on the system.
Administrative privileges are required to perform this action.

Examples

Softadmin­®

The following example shows a configuration that combines WindowsEvent Log logging with file logging:

{
  "Serilog": {
    "Using": [ "Softadmin", "Serilog.Sinks.File" ],
    "MinimumLevel": {
      "Default": "Information"
    },
    "WriteTo": [
      {
        "Name": "SoftadminEventLog",
        "Args": {
          "source": "#EventSourceName#",
          "manageEventSource": false,
          "eventId": 1
        }
      },
      {
        "Name": "File",
        "Args": {
          "MinimumLevel": "Error",
          "path": "C:\\Logs\\softadmin-.txt",
          "rollingInterval": "Day",
          "outputTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}"
        }
      }
    ]
  }
}

Publish

The following example shows a possible logging configuration for Publish:

{
  "Serilog": {
    "Using": [ "Softadmin.Publish", "Serilog.Sinks.File" ],
    "MinimumLevel": {
      "Default": "Information"
    },
    "WriteTo": [
      {
        "Name": "SoftadminEventLog",
        "Args": {
          "source": "#PublishEventSourceName#",
          "manageEventSource": false,
          "eventId": 1
        }
      },
      {
        "Name": "File",
        "Args": {
          "MinimumLevel": "Error",
          "path": "C:\\Logs\\publish-.txt",
          "rollingInterval": "Day"
        }
      }
    ]
  }
}

Log Levels

Each log event has a log level, indicating its severity.

• Critical
• Error
• Warning
• Information
• Debug
• Trace

Critical

Indicates a severe issue. Part or all of the system may be unusable.

Critical logs are generated only by the platform itself and cannot be created manually.

Note that in a critical system state, the platform may be unable to write to the log at all. As a result, some critical failures may not be recorded.

Error

Indicates that the current operation failed and could not be completed.

You can typically create error logs using THROW or RAISERROR in your stored procedures.

You can also create error logs by calling SoftadminApi.Log_LogError.

Warning

Indicates something unexpected during operation. A warning may point to a condition that could lead to a problem if not addressed.

You can create warning logs by calling SoftadminApi.Log_LogWarning.

Information

Indicates a normal event. These logs should have some long-term informational value.

Note that informational events are not always logged to the standard log. For example, user logins are informational, but are recorded in the login log instead. Similarly, you may choose to log certain events in system-specific log tables, or—if the data is important to business logic—use the Transaction Table design pattern instead.

You can create information logs by calling SoftadminApi.Log_LogInformation.

Debug

Indicates a diagnostic event. Debug logs are useful during development or while investigating a specific issue.

By default, the platform does not generate debug logs.

You can create debug logs by calling SoftadminApi.Log_LogDebug.

Trace

Indicates a highly detailed diagnostic event. Trace logs may include sensitive data or verbose internal state information.

By default, the platform does not generate trace logs.

You can create trace logs by calling SoftadminApi.Log_LogTrace, but the procedure will discard all messages in stage and production systems.

SourceContext

The Source Context is optional extra information about which module created the log event, and can be used to filter logs. They are hierarchical, with namespaces separated by periods.

For example Economy.Order or Member.Newsletter.Subscription.

MessageTemplate

Log events are normally grouped on the log message. However, you may wish to use variables in the log message, and this often prevents grouping. By passing the message template to the log, you enable grouping on the template instead of the substituted string.

DECLARE @Count int = RAND() * 50;
IF @Count > 10
BEGIN
  DECLARE @MessageTemplate nvarchar(1000) = 'There are %d unprocessed invoices in the queue.';
  DECLARE @WarningMessage nvarchar(1000) = formatmessage(@MessageTemplate, @Count);

  EXEC SoftadminApi.Log_LogWarning
    @LogMessage      = @WarningMessage,
    @MessageTemplate = @MessageTemplate,
    @SourceContext   = 'Database.Invoice.Incomming';
END;