Skip to content

Latest commit

 

History

History
273 lines (210 loc) · 10.8 KB

README.md

File metadata and controls

273 lines (210 loc) · 10.8 KB
Raw

OpenTelemetry .NET Logs

Table of Contents

Best Practices

The following tutorials have demonstrated the best practices for logging with OpenTelemetry .NET:

Structured Logging

✔️ You should use structured logging.

  • Structured logging is more efficient than unstructured logging.
    • Filtering and redaction can happen on individual key-value pairs instead of the entire log message.
    • Storage and indexing are more efficient.
  • Structured logging makes it easier to manage and consume logs.

🛑 You should avoid string interpolation.

Warning

The following code has bad performance due to string interpolation:

var food = "tomato";
var price = 2.99;

logger.LogInformation($"Hello from {food} {price}.");

Refer to the logging performance benchmark for more details.

Package Version

✔️ You should always use the ILogger interface (including ILogger<TCategoryName>) from the latest stable version of Microsoft.Extensions.Logging package, regardless of the .NET runtime version being used:

  • If you are using the latest stable version of OpenTelemetry .NET SDK, you do not have to worry about the version of Microsoft.Extensions.Logging package because it is already taken care of for you via package dependency.
  • Starting from version 3.1.0, the .NET runtime team is holding a high bar for backward compatibility on Microsoft.Extensions.Logging even during major version bumps, so compatibility is not a concern here.

Logging API

ILogger

.NET supports high performance, structured logging via the Microsoft.Extensions.Logging.ILogger interface (including ILogger<TCategoryName>) to help monitor application behavior and diagnose issues.

Get Logger

In order to use the ILogger interface, you need to first get a logger. How to get a logger depends on two things:

  • The type of application you are building.
  • The place where you want to log.

Here is the rule of thumb:

✔️ You should use dot-separated UpperCamelCase as the log category name, which makes it convenient to filter logs. A common practice is to use fully qualified class name, and if further categorization is desired, append a subcategory name. Refer to the .NET official document to learn more.

loggerFactory.CreateLogger<MyClass>(); // this is equivalent to CreateLogger("MyProduct.MyLibrary.MyClass")
loggerFactory.CreateLogger("MyProduct.MyLibrary.MyClass"); // use the fully qualified class name
loggerFactory.CreateLogger("MyProduct.MyLibrary.MyClass.DatabaseOperations"); // append a subcategory name
loggerFactory.CreateLogger("MyProduct.MyLibrary.MyClass.FileOperations"); // append another subcategory name

🛑 You should avoid creating loggers too frequently. Although loggers are not super expensive, they still come with CPU and memory cost, and are meant to be reused throughout the application. Refer to the logging performance benchmark for more details.

Use Logger

✔️ You should use compile-time logging source generation pattern to achieve the best performance.

var food = "tomato";
var price = 2.99;

logger.SayHello(food, price);

internal static partial class LoggerExtensions
{
    [LoggerMessage(Level = LogLevel.Information, Message = "Hello from {food} {price}.")]
    public static partial void SayHello(this ILogger logger, string food, double price);
}

Note

There is no need to pass in an explicit EventId while using LoggerMessageAttribute. A durable EventId will be automatically assigned based on the hash of the method name during code generation.

✔️ You can use LogPropertiesAttribute from Microsoft.Extensions.Telemetry.Abstractions if you need to log complex objects. Check out the Logging with Complex Objects tutorial for more details.

🛑 You should avoid the extension methods from LoggerExtensions, these methods are not optimized for performance.

Warning

The following code has bad performance due to boxing:

var food = "tomato";
var price = 2.99;

logger.LogInformation("Hello from {food} {price}.", food, price);

Refer to the logging performance benchmark for more details.

✔️ You should hold a high bar while using ILogger.IsEnabled.

The logging API is highly optimized for the scenario where most loggers are disabled for certain log levels. Making an extra call to IsEnabled before logging will not give you any performance gain.

Warning

The logger.IsEnabled(LogLevel.Information) call in the following code is not going to give any performance gain. Refer to the logging performance benchmark for more details.

var food = "tomato";
var price = 2.99;

if (logger.IsEnabled(LogLevel.Information)) // do not do this, there is no perf gain
{
    logger.SayHello(food, price);
}

internal static partial class LoggerExtensions
{
    [LoggerMessage(Level = LogLevel.Information, Message = "Hello from {food} {price}.")]
    public static partial void SayHello(this ILogger logger, string food, double price);
}

IsEnabled can give performance benefits when it is expensive to evaluate the arguments. For example, in the following code the Database.GetFoodPrice invocation will be skipped if the logger is not enabled:

if (logger.IsEnabled(LogLevel.Information))
{
    logger.SayHello(food, Database.GetFoodPrice(food));
}

Although IsEnabled can give some performance benefits in the above scenario, for most users it can cause more problems. For example, the performance of the code is now depending on which logger is being enabled, not to mention the argument evaluation might have significant side effects that are now depending on the logging configuration.

LoggerFactory

In many cases, you can use ILogger without having to interact with Microsoft.Extensions.Logging.LoggerFactory directly. This section is intended for users who need to create and manage LoggerFactory explicitly.

🛑 You should avoid creating LoggerFactory instances too frequently, LoggerFactory is fairly expensive and meant to be reused throughout the application. For most applications, one LoggerFactory instance per process would be sufficient.

✔️ You should properly manage the lifecycle of LoggerFactory instances if they are created by you.

  • If you forget to dispose the LoggerFactory instance before the application ends, logs might get dropped due to the lack of proper flush.
  • If you dispose the LoggerFactory instance too early, any subsequent logging API invocation associated with the logger factory could become no-op (i.e. no logs will be emitted).

Log Correlation

In OpenTelemetry, logs are automatically correlated to traces. Check the Log Correlation tutorial to learn more.

Log Enrichment

TBD

Log Filtering

The Customizing OpenTelemetry .NET SDK for Logs document has provided instructions for basic filtering based on logger category name and severity level.

For more advanced filtering and sampling, the .NET team has a plan to cover it in .NET 9 timeframe, please use this runtime issue to track the progress or provide feedback and suggestions.

Log Redaction

Logs might contain sensitive information such as passwords and credit card numbers, proper redaction is required to prevent privacy and security incidents. Check the Log Redaction tutorial to learn more.