Logging

Log Sinks

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.

MessageTemplate

Log events are grouped on the log message. However, you may wish to use variable numbers in the log message, which prevents grouping. Therefore, the message template, that is, the template string that was used to form the final message, can also be logged.

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;