-
Notifications
You must be signed in to change notification settings - Fork 751
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Introduce new extended logging model.
- Replace the OpenTelemetry-specific logger design with a LoggerFactory-based approach independent of OpenTelemetry. This delivers enrichment and redaction to all ILogger users. The basic idea is that the code generator will no longer be responsible for doing redaction. Instead, the generated code will accumulate normal properties in one collection and will accumulate classified properties in a different collection. Within the Logger type, the classified properties are run through redaction and added to the normal property list. This list is then used to enrich into. And then the final thing is given to the set of currently registered ILogger instances in the system. So all these loggers get redacted and enriched state. This separates static vs. dynamic log enrichment. The idea is to reduce overhead for stuff that never changes. Thus, we have the new IStaticLogEnricher type. We now support structured logging as a first class concept using the new StructuredLog extension methods around ILogger. NOTES: - The idea is that the customer should call AddExtendedLogging instead of AddLogging. By virtue of using this call, they'll also be using the newer code generator which will take advantage of the new features. - This PR doesn't currently include updated tests, that's coming next after we validate the general approach. - This PR doesn't currently include an updated logging code generator that will take advantage of this new functionality. - Right now, if a user calls AddLogging after they had already called AddExtendedLogging, this will undo the extended logging stuff and leave the system in classic mode. We need to find a strategy to deal with this.
- Loading branch information
Martin Taillefer
committed
Jun 25, 2023
1 parent
1f7da6f
commit a25f03b
Showing
35 changed files
with
1,553 additions
and
462 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
19 changes: 19 additions & 0 deletions
19
src/Libraries/Microsoft.Extensions.Telemetry.Abstractions/Enrichment/IStaticLogEnricher.cs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
// Licensed to the .NET Foundation under one or more agreements. | ||
// The .NET Foundation licenses this file to you under the MIT license. | ||
|
||
using System.Diagnostics.CodeAnalysis; | ||
|
||
namespace Microsoft.Extensions.Telemetry.Enrichment; | ||
|
||
/// <summary> | ||
/// A component that augments log records with additional properties which are unchanging over the life of the object. | ||
/// </summary> | ||
[Experimental] | ||
public interface IStaticLogEnricher | ||
{ | ||
/// <summary> | ||
/// Called to generate properties for a log record. | ||
/// </summary> | ||
/// <param name="bag">Where the enricher puts the properties it is producing.</param> | ||
void Enrich(IEnrichmentPropertyBag bag); | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
41 changes: 41 additions & 0 deletions
41
src/Libraries/Microsoft.Extensions.Telemetry.Abstractions/Logging/LoggerExtensions.cs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,41 @@ | ||
// Licensed to the .NET Foundation under one or more agreements. | ||
// The .NET Foundation licenses this file to you under the MIT license. | ||
|
||
using System; | ||
using System.Diagnostics.CodeAnalysis; | ||
using Microsoft.Extensions.Logging; | ||
using Microsoft.Shared.Diagnostics; | ||
|
||
namespace Microsoft.Extensions.Telemetry.Logging; | ||
|
||
/// <summary> | ||
/// Extensions for <see cref="ILogger"/>. | ||
/// </summary> | ||
[Experimental] | ||
public static class LoggerExtensions | ||
{ | ||
/// <summary> | ||
/// Emits a structured log entry. | ||
/// </summary> | ||
/// <param name="logger">The logger to emit the log entry to.</param> | ||
/// <param name="logLevel">Entry will be written on this level.</param> | ||
/// <param name="eventId">Id of the event.</param> | ||
/// <param name="properties">The set of name/value pairs to log with this entry.</param> | ||
public static void StructuredLog(this ILogger logger, LogLevel logLevel, EventId eventId, LoggerMessageProperties properties) | ||
{ | ||
Throw.IfNull(logger).Log<LoggerMessageProperties>(logLevel, eventId, properties, null, (_, _) => string.Empty); | ||
} | ||
|
||
/// <summary> | ||
/// Emits a structured log entry. | ||
/// </summary> | ||
/// <param name="logger">The logger to emit the log entry to.</param> | ||
/// <param name="logLevel">Entry will be written on this level.</param> | ||
/// <param name="eventId">Id of the event.</param> | ||
/// <param name="properties">The set of name/value pairs to log with this entry.</param> | ||
/// <param name="exception">The exception related to this entry.</param> | ||
public static void StructuredLog(this ILogger logger, LogLevel logLevel, EventId eventId, LoggerMessageProperties properties, Exception? exception) | ||
{ | ||
Throw.IfNull(logger).Log<LoggerMessageProperties>(logLevel, eventId, properties, exception, (_, _) => string.Empty); | ||
} | ||
} |
133 changes: 133 additions & 0 deletions
133
src/Libraries/Microsoft.Extensions.Telemetry.Abstractions/Logging/LoggerMessageHelper.cs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,133 @@ | ||
// Licensed to the .NET Foundation under one or more agreements. | ||
// The .NET Foundation licenses this file to you under the MIT license. | ||
|
||
using System; | ||
using System.Collections; | ||
using System.Collections.Generic; | ||
using System.ComponentModel; | ||
using System.Diagnostics.CodeAnalysis; | ||
using Microsoft.Extensions.ObjectPool; | ||
using Microsoft.Shared.Pools; | ||
|
||
namespace Microsoft.Extensions.Telemetry.Logging; | ||
|
||
/// <summary> | ||
/// Utility type to support generated logging methods. | ||
/// </summary> | ||
[EditorBrowsable(EditorBrowsableState.Never)] | ||
[Experimental] | ||
public static class LoggerMessageHelper | ||
{ | ||
[ThreadStatic] | ||
private static LoggerMessageProperties? _properties; | ||
|
||
/// <summary> | ||
/// Gets a thread-local instance of this type. | ||
/// </summary> | ||
public static LoggerMessageProperties ThreadStaticLoggerMessageProperties | ||
{ | ||
get | ||
{ | ||
_properties ??= new(); | ||
_ = _properties.TryReset(); | ||
return _properties; | ||
} | ||
} | ||
|
||
/// <summary> | ||
/// Enumerates an enumerable into a string. | ||
/// </summary> | ||
/// <param name="enumerable">The enumerable object.</param> | ||
/// <returns> | ||
/// A string representation of the enumerable. | ||
/// </returns> | ||
public static string Stringify(IEnumerable? enumerable) | ||
{ | ||
if (enumerable == null) | ||
{ | ||
return "null"; | ||
} | ||
|
||
var sb = PoolFactory.SharedStringBuilderPool.Get(); | ||
_ = sb.Append('['); | ||
|
||
bool first = true; | ||
foreach (object? e in enumerable) | ||
{ | ||
if (!first) | ||
{ | ||
_ = sb.Append(','); | ||
} | ||
|
||
if (e == null) | ||
{ | ||
_ = sb.Append("null"); | ||
} | ||
else | ||
{ | ||
_ = sb.Append(FormattableString.Invariant($"\"{e}\"")); | ||
} | ||
|
||
first = false; | ||
} | ||
|
||
_ = sb.Append(']'); | ||
var result = sb.ToString(); | ||
PoolFactory.SharedStringBuilderPool.Return(sb); | ||
return result; | ||
} | ||
|
||
/// <summary> | ||
/// Enumerates an enumerable of key/value pairs into a string. | ||
/// </summary> | ||
/// <typeparam name="TKey">Type of keys.</typeparam> | ||
/// <typeparam name="TValue">Type of values.</typeparam> | ||
/// <param name="enumerable">The enumerable object.</param> | ||
/// <returns> | ||
/// A string representation of the enumerable. | ||
/// </returns> | ||
public static string Stringify<TKey, TValue>(IEnumerable<KeyValuePair<TKey, TValue>>? enumerable) | ||
{ | ||
if (enumerable == null) | ||
{ | ||
return "null"; | ||
} | ||
|
||
var sb = PoolFactory.SharedStringBuilderPool.Get(); | ||
_ = sb.Append('{'); | ||
|
||
bool first = true; | ||
foreach (var kvp in enumerable) | ||
{ | ||
if (!first) | ||
{ | ||
_ = sb.Append(','); | ||
} | ||
|
||
if (typeof(TKey).IsValueType || kvp.Key is not null) | ||
{ | ||
_ = sb.Append(FormattableString.Invariant($"\"{kvp.Key}\"=")); | ||
} | ||
else | ||
{ | ||
_ = sb.Append("null="); | ||
} | ||
|
||
if (typeof(TValue).IsValueType || kvp.Value is not null) | ||
{ | ||
_ = sb.Append(FormattableString.Invariant($"\"{kvp.Value}\"")); | ||
} | ||
else | ||
{ | ||
_ = sb.Append("null"); | ||
} | ||
|
||
first = false; | ||
} | ||
|
||
_ = sb.Append('}'); | ||
var result = sb.ToString(); | ||
PoolFactory.SharedStringBuilderPool.Return(sb); | ||
return result; | ||
} | ||
} |
45 changes: 45 additions & 0 deletions
45
...t.Extensions.Telemetry.Abstractions/Logging/LoggerMessageProperties.ClassifiedProperty.cs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,45 @@ | ||
// Licensed to the .NET Foundation under one or more agreements. | ||
// The .NET Foundation licenses this file to you under the MIT license. | ||
|
||
using System.ComponentModel; | ||
using System.Diagnostics.CodeAnalysis; | ||
using Microsoft.Extensions.Compliance.Classification; | ||
|
||
namespace Microsoft.Extensions.Telemetry.Logging; | ||
|
||
public partial class LoggerMessageProperties | ||
{ | ||
/// <summary> | ||
/// Represents a captured property that needs redaction. | ||
/// </summary> | ||
[SuppressMessage("Design", "CA1034:Nested types should not be visible", Justification = "Not for customer use and hidden from docs")] | ||
[SuppressMessage("Performance", "CA1815:Override equals and operator equals on value types", Justification = "Not needed")] | ||
[EditorBrowsable(EditorBrowsableState.Never)] | ||
public readonly struct ClassifiedProperty | ||
{ | ||
/// <summary> | ||
/// Gets the name of the property. | ||
/// </summary> | ||
public readonly string Name { get; } | ||
|
||
/// <summary> | ||
/// Gets the property's value. | ||
/// </summary> | ||
public readonly object? Value { get; } | ||
|
||
/// <summary> | ||
/// Gets the property's data classification. | ||
/// </summary> | ||
public readonly DataClassification Classification { get; } | ||
|
||
/// <summary> | ||
/// Initializes a new instance of the <see cref="ClassifiedProperty"/> struct. | ||
/// </summary> | ||
public ClassifiedProperty(string name, object? value, DataClassification classification) | ||
{ | ||
Name = name; | ||
Value = value; | ||
Classification = classification; | ||
} | ||
} | ||
} |
53 changes: 53 additions & 0 deletions
53
...icrosoft.Extensions.Telemetry.Abstractions/Logging/LoggerMessageProperties.PropertyBag.cs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,53 @@ | ||
// Licensed to the .NET Foundation under one or more agreements. | ||
// The .NET Foundation licenses this file to you under the MIT license. | ||
|
||
using System; | ||
using System.Collections.Generic; | ||
using Microsoft.Extensions.Telemetry.Enrichment; | ||
|
||
namespace Microsoft.Extensions.Telemetry.Logging; | ||
|
||
public partial class LoggerMessageProperties | ||
{ | ||
private sealed class PropertyBag : IEnrichmentPropertyBag | ||
{ | ||
private readonly List<KeyValuePair<string, object?>> _properties; | ||
|
||
public PropertyBag(List<KeyValuePair<string, object?>> properties) | ||
{ | ||
_properties = properties; | ||
} | ||
|
||
void IEnrichmentPropertyBag.Add(string key, object value) | ||
{ | ||
_properties.Add(new KeyValuePair<string, object?>(key, value)); | ||
} | ||
|
||
/// <inheritdoc/> | ||
void IEnrichmentPropertyBag.Add(string key, string value) | ||
{ | ||
_properties.Add(new KeyValuePair<string, object?>(key, value)); | ||
} | ||
|
||
/// <inheritdoc/> | ||
void IEnrichmentPropertyBag.Add(ReadOnlySpan<KeyValuePair<string, object>> properties) | ||
{ | ||
foreach (var p in properties) | ||
{ | ||
// we're going from KVP<string, object> to KVP<string, object?> which is strictly correct, so ignore the complaint | ||
#pragma warning disable CS8620 // Argument cannot be used for parameter due to differences in the nullability of reference types. | ||
_properties.Add(p); | ||
#pragma warning restore CS8620 // Argument cannot be used for parameter due to differences in the nullability of reference types. | ||
} | ||
} | ||
|
||
/// <inheritdoc/> | ||
void IEnrichmentPropertyBag.Add(ReadOnlySpan<KeyValuePair<string, string>> properties) | ||
{ | ||
foreach (var p in properties) | ||
{ | ||
_properties.Add(new KeyValuePair<string, object?>(p.Key, p.Value)); | ||
} | ||
} | ||
} | ||
} |
Oops, something went wrong.