Skip to content

Logging Libraries

Application Insights

If you are deploying your application to Azure, you SHOULD use Application Insights for application performance monitoring (APM) and log aggregation. If the client prefers another APM solution, you MAY use that instead.

.NET Core

If you are using .NET Core you SHOULD use the logging infrastructure built into the framework and inject an ILogger<T> where T is the class where the logging takes place into each component. This SHOULD be connected to to your APM solution as well as to other logging sinks as appropriate.

Serilog

Based on it's support for robust logging, integration with .NET Core, and support for writing to structured log storage such as LogStash, you SHOULD use Serilog. You SHOULD used Serilog.Settings.Configuration to allow your logging infrastructure to be configured at runtime.

Log Data

Logs on a per message basis SHOULD contain the following information:

REQUIRED * DateTime in UTC in 24 hour format. (yyyy-MM-dd HH:mm:ss,fff) * Severity / Level * Path (Class/Method) * Message (or JSON if using structured logging)

RECOMMENDED * Thread ID

Additionally, you SHOULD include any other data points for being able to trace specific to a session (session id) or user (user id) for troubleshooting purposes, depending on your application.

For Example:

2016-03-02 08:56:20,133 [StudentRepository, ksykora] Warning (0): Unable to find student by ID 00000000-0000-0000-0000-000000000000

You MUST sanitize log data to not include information that if discovered by an outsider, would allow a user to gain access to yours or another system (i.e. passwords or password hashes, salts, credit card details, etc.)

See this article for ideas on how to scrub sensitive information from telemetry.

Log Severity / Levels

Verbose

Overly chatty messaging that would not add value to logs other than being able to trace exactly what is occurring or dumping entire sets of data.

These statements SHOULD only be enabled temporarily for diagnostic reasons.

Verbose messages SHOULD NOT be persisted to a store during normal operation.

Example

Enter Method GetStudentById()

Debug

Developer oriented information that can assist in troubleshooting or helping to understand how a framework is behaving. For example, you might use debug statements to observe application behavior and use the output to tweak constants or timeouts.

These statements SHOULD only be enabled temporarily for diagnostic reasons.

Debug messages SHOULD NOT be persisted to a store during normal operation.

Example

Response size: {0} bytes
Discovered data characteristics {0}

Informational (Info)

Business or development oriented information marking "interesting" moments in an application. User events, communications like email sending, and other business process info is typical at this level. This level and higher is typically enabled in every environment, local to production.

These messages SHOULD be persisted to a data store (file, database, log storage).

Example

Registered new user {0}
Sent push notification {0} to {1}

Warning

Events that are be brought to attention but do not disrupt a user or business flow. Application states that are unexpected, performance thresholds exceeded, user events like exceeding login attempts are example candidates.

These messages SHOULD be persisted to a data store (file, database, log storage).

Example

Unable to find student by ID {0}
Network call timed out, retrying (retry {0}).

Error

Events that disrupt user or business flows but, on a system level, is recoverable and allow for the application to continue servicing other requests and continue to run.

These messages MUST be persisted to a data store (file, database, log storage).

Examples

Network call failed.
Exception thrown when attempting to perform profile edit action
Received error code {0} from remote system

Serilog allows you to pass the exception directly into the framework. Wherever possible, use those mechanisms and do not print the exception type, message, or stack trace into your log message unless they add additional value. Use your log message to describe the nature under which the exception occurred.

Fatal

Anything that terminates processing unexpectedly and would cause an application to crash outright or cause, on a server level, the system to stop servicing all requests.

These messages MUST be persisted to a data store (file, database, log storage). These messages SHOULD notify support personel.

Examples

No available disk space
Unable to create web socket listener
Back to top