Skip to content

Logging

Jump to bottom
Kieron Lanning edited this page Feb 2, 2025 · 5 revisions

Basics

The types are hosted within the Purview.Telemetry.Logging namespace.

To signal an interface for logging target generation, decorate the interface with the LoggerAttribute. The signal for a method is the LogAttribute, where you can control various aspects of it's generation.

We also support the generation of scoped loggers.

All log generation is achieved using the LoggerMessage class, as part of the high-performance logging libraries.

Note: that the maximum number of parameters allowed by the LoggerMessage class is 6, plus one optional Exception. You must also reference the Microsoft.Extensions.Logging package on NuGet.

Microsoft.Extensions.Logging Not Referenced

In your project, if the Microsoft.Extensions.Logging.ILogger type is not available, your project will fail to compile. This is due to the generated attributes using related types such as the LogLevel.

In this case, add a build constant to either you .csproj or Directory.Build.props with a value of EXCLUDE_PURVIEW_TELEMETRY_LOGGING, and the logging attributes will be ignored.

<!-- In a .csproj -->
<DefineConstants>EXCLUDE_PURVIEW_TELEMETRY_LOGGING</DefineConstants>

<!-- In a Directory.Build.Props -->
<PropertyGroup>
  <DefineConstants>EXCLUDE_PURVIEW_TELEMETRY_LOGGING</DefineConstants>
</PropertyGroup>

Log Generation

To generate a log entry, the method should be decorated with the LogAttribute and return either void, in the case of a non-scoped log entry. Or IDisposable/ IDisposable? for scoped log entries.

The parameters, if any, are used by the LogAttribute.MessageTemplate and form part of the structured log generation.

There are several options such as the level, name, event Id and message template that can be adjusted via the LogAttribute.

Semantic Level-Based LogAttribute Types

If you prefer, you can use semantic type attributes to specify the level instead of the LogAttribute.Level property.

  • TraceAttribute
  • DebugAttribute
  • InfoAttribute
  • WarningAttribute
  • ErrorAttribute
  • CriticalAttribute

These support all the same properties as LogAttribute except for the Level property.

Inferring

When not using multi-targeting you can avoid adding the LogAttribute explicitly.

You can set the default log level using either the LoggerAttribute.DefaultLevel on the interface, or the LoggerGenerationAttribute.DefaultLevel on the assembly.

If no level is specified on the method, and an Exception is defined the level is changed to an Error automatically. This also raises the TSG2002 diagnostic, that can safely be ignored if you are comfortable with this inferred behaviour.

Types

LogAttribute

Used to define the log entry details on a method.

Name Type Description
Level Microsoft.Extensions.Logging.LogLevel Determines the level used when defining the log entry. Also available on construction. Defaults to Information.
MessageTemplate string? Defines the template used to populate the log entry method. If one is not specified, it will automatically be generated based on the prefixes and the available parameters. Also available on construction. Defaults to null.
EventId int? Used when generating the EventId. Also available on construction. Defaults to null. One will be generated if one is not supplied.
Name string? The name of the log entry, if one is not defined then the name of the method is used. Also available on construction. Defaults to null.

LoggerAttribute

Used to enrol an interface in the source generation process.

Name Type Description
DefaultLevel Microsoft.Extensions.Logging.LogLevel Determines the default level to use when one is not provided. Also available on construction. Defaults to Information.
CustomPrefix string? Used when generating the log entry name's prefix. If this is set, the PrefixType is automatically set to Custom. Also available on construction. Defaults to null.
PrefixType Purview.Telemetry.Logging.LogPrefixType Determines the type of prefix to use when generating the log entry name. Defaults to Default.

LoggerGenerationAttribute

Used to control defaults at the assembly level.

Name Type Description
DefaultLevel Microsoft.Extensions.Logging.LogLevel Determines the default level to use when one is not provided. Also available on construction. Defaults to Information.

LogPrefixType

When generating a log entry name, provides options to customise the prefix.

Value Description
Default The name of the interface without the "I" prefix or "Log", "Logger" or "Telemetry" suffixes.
Interface Uses the name of the interface.
Class The name of the class used for generation. This can be specified using the TelemetryGenerationAttribute.ClassName property, or through auto generation.
Custom Used when the LoggerAttribute.CustomPrefix is set.
NoSuffix Does not generate any suffix.
Clone this wiki locally