Logging Generation v2

Logging Gen v2 - Basics

Important

v4 Update: All attributes are now in the unified Purview.Telemetry namespace. See Breaking Changes for migration details.

All logging-related attributes are hosted within the Purview.Telemetry 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.

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.

It is advised to use the LogAttribute for scoped log entries, due to the Level property not being supported.

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, unless an Exception is detected in the parameters, and then Error is used.
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.
GenerationMode	LoggerGenerationMode	Optional. Per-method override for the generation mode. Auto (default) inherits from the interface-level [LoggerAttribute].GenerationMode. Use V1 to force Generation v1 or V2 to force Generation v2 for this method specifically.

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	LogPrefixType	Determines the type of prefix to use when generating the log entry name. Defaults to Default.
GenerationMode	LoggerGenerationMode	Controls which generation mode is used for all log methods on this interface. Auto (default) selects the best mode per method. Use V1 to force Generation v1 or V2 to force Generation v2 for all methods. Can be overridden per-method via [LogAttribute].GenerationMode.

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.
GenerationMode	LoggerGenerationMode	Controls which generation mode is used for all log methods in the assembly. Auto (default) selects the best mode per method. Can be overridden per-interface via [LoggerAttribute].GenerationMode or per-method via [LogAttribute].GenerationMode.
DefaultPrefixType	LogPrefixType	Specifies the default prefix type for all log entries in the assembly. Defaults to Default.

LogPrefixType

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

Value	Description
Default	Does not generate any suffix.
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.
TrimmedClassName	The name of the interface without the "I" prefix or "Log", "Logger" or "Telemetry" suffixes.

ExpandEnumerableAttribute

When used on an array or IEnumerable parameter, enables the logged output of individual elements. The default maximum number of elements to output is controlled by the MaximumValueCount property, which defaults to 5.

Anything greater than this value generates the TSG2008 diagnostic warning.

Note

This warning diagnostic can be ignored, but ensure you test your application performance thoroughly.

Value	Description
MaximumValueCount	The maximum number of elements to output from the enumeration/ array.