Destructurama.Attributed 5.1.0

Destructurama.Attributed

This package makes it possible to manipulate how objects are logged to Serilog using attributes.

Installation

Install from NuGet:

Install-Package Destructurama.Attributed

Usage

Modify logger configuration:

using Destructurama;
...
var log = new LoggerConfiguration()
  .Destructure.UsingAttributes()
...

1. Changing a property name

Apply the LogWithName attribute:

<a id='snippet-LogWithName'></a>

public class PersonalData
{
    [LogWithName("FullName")]
    public string? Name { get; set; }
}

^{<a href='/src/Destructurama.Attributed.Tests/LogWithNameAttributeTests.cs#L64-L70' title='Snippet source file'>snippet source</a> | <a href='#snippet-LogWithName' title='Start of snippet'>anchor</a>}

2. Ignoring a property

Apply the NotLogged attribute:

<a id='snippet-LoginCommand'></a>

public class LoginCommand
{
    public string? Username { get; set; }

    [NotLogged]
    public string? Password { get; set; }
}

^{<a href='/src/Destructurama.Attributed.Tests/Snippets.cs#L29-L37' title='Snippet source file'>snippet source</a> | <a href='#snippet-LoginCommand' title='Start of snippet'>anchor</a>}

When the object is passed using {@...} syntax the attributes will be consulted.

<a id='snippet-LogCommand'></a>

var command = new LoginCommand { Username = "logged", Password = "not logged" };
_log.Information("Logging in {@Command}", command);

^{<a href='/src/Destructurama.Attributed.Tests/Snippets.cs#L44-L47' title='Snippet source file'>snippet source</a> | <a href='#snippet-LogCommand' title='Start of snippet'>anchor</a>}

3. Ignoring a property if it has default value

Apply the NotLoggedIfDefault attribute:

public class LoginCommand
{
  public string Username { get; set; }

  [NotLoggedIfDefault]
  public string Password { get; set; }

  [NotLoggedIfDefault]
  public DateTime TimeStamp { get; set; }
}

4. Ignoring a property if it has null value

Apply the NotLoggedIfNull attribute:

public class LoginCommand
{
  /// <summary>
  /// `null` value results in removed property
  /// </summary>
  [NotLoggedIfNull]
  public string Username { get; set; }

  /// <summary>
  /// Can be applied with [LogMasked] or [LogReplaced] attributes
  /// `null` value results in removed property
  /// "123456789" results in "***"
  /// </summary>
  [NotLoggedIfNull]
  [LogMasked]
  public string Password { get; set; }

  /// <summary>
  /// Attribute has no effect on non-reference and non-nullable types
  /// </summary>
  [NotLoggedIfNull]
  public int TimeStamp { get; set; }
}

Ignore null properties can be globally applied during logger configuration without need to apply attributes:

var log = new LoggerConfiguration()
  .Destructure.UsingAttributes(x => x.IgnoreNullProperties = true)
  ...

5. Treating types and properties as scalars

To prevent destructuring of a type or property at all, apply the LogAsScalar attribute.

6. Masking a property

Apply the LogMasked attribute with various settings:

• Text: If set, the property value will be set to this text.
• ShowFirst: Shows the first x characters in the property value.
• ShowLast: Shows the last x characters in the property value.
• PreserveLength: If set, it will swap out each character with the default value. Note that this property will be ignored if Text has been set to custom value.

Masking works for all properties calling ToString() on their values. Note that masking also works for properties of type IEnumerable<string> or derived from it, for example, string[] or List<string>.

Examples

<a id='snippet-CustomizedMaskedLogs'></a>

public class CustomizedMaskedLogs
{
    /// <summary>
    /// 123456789 results in "***"
    /// </summary>
    [LogMasked]
    public string? DefaultMasked { get; set; }

    /// <summary>
    /// 9223372036854775807 results in "***"
    /// </summary>
    [LogMasked]
    public long? DefaultMaskedLong { get; set; }

    /// <summary>
    /// 2147483647 results in "***"
    /// </summary>
    [LogMasked]
    public int? DefaultMaskedInt { get; set; }

    /// <summary>
    /// [123456789,123456789,123456789] results in [***,***,***]
    /// </summary>
    [LogMasked]
    public string[]? DefaultMaskedArray { get; set; }

    /// <summary>
    /// 123456789 results in "*********"
    /// </summary>
    [LogMasked(PreserveLength = true)]
    public string? DefaultMaskedPreserved { get; set; }

    /// <summary>
    /// "" results in "***"
    /// </summary>
    [LogMasked]
    public string? DefaultMaskedNotPreservedOnEmptyString { get; set; }

    /// <summary>
    /// 123456789 results in "#"
    /// </summary>
    [LogMasked(Text = "_REMOVED_")]
    public string? CustomMasked { get; set; }

    /// <summary>
    /// 123456789 results in "#"
    /// </summary>
    [LogMasked(Text = "")]
    public string? CustomMaskedWithEmptyString { get; set; }

    /// <summary>
    /// 123456789 results in "#########"
    /// </summary>
    [LogMasked(Text = "#", PreserveLength = true)]
    public string? CustomMaskedPreservedLength { get; set; }

    /// <summary>
    /// 123456789 results in "123******"
    /// </summary>
    [LogMasked(ShowFirst = 3)]
    public string? ShowFirstThreeThenDefaultMasked { get; set; }

    /// <summary>
    /// 9223372036854775807 results in "922***807"
    /// </summary>
    [LogMasked(ShowFirst = 3, ShowLast = 3)]
    public long? ShowFirstAndLastThreeAndDefaultMaskLongInTheMiddle { get; set; }

    /// <summary>
    /// 2147483647 results in "214****647"
    /// </summary>
    [LogMasked(ShowFirst = 3, ShowLast = 3, PreserveLength = true)]
    public int? ShowFirstAndLastThreeAndDefaultMaskIntInTheMiddlePreservedLength { get; set; }

    /// <summary>
    /// 123456789 results in "123******"
    /// </summary>
    [LogMasked(ShowFirst = 3, PreserveLength = true)]
    public string? ShowFirstThreeThenDefaultMaskedPreservedLength { get; set; }

    /// <summary>
    /// 123456789 results in "***789"
    /// </summary>
    [LogMasked(ShowLast = 3)]
    public string? ShowLastThreeThenDefaultMasked { get; set; }

    /// <summary>
    /// 123456789 results in "******789"
    /// </summary>
    [LogMasked(ShowLast = 3, PreserveLength = true)]
    public string? ShowLastThreeThenDefaultMaskedPreservedLength { get; set; }

    /// <summary>
    /// 123456789 results in "123_REMOVED_"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowFirst = 3)]
    public string? ShowFirstThreeThenCustomMask { get; set; }

    /// <summary>
    /// d3c4a1f2-3b4e-4f5a-9b6c-7d8e9f0a1b2c results in "d3c4a_REMOVED_"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowFirst = 5)]
    public Guid? ShowFirstFiveThenCustomMaskGuid { get; set; }

    /// <summary>
    /// Descending results in "Desce_REMOVED_"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowFirst = 5)]
    public ListSortDirection ShowFirstFiveThenCustomMaskEnum { get; set; }

    /// <summary>
    /// 123456789 results in "123_REMOVED_"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowFirst = 3, PreserveLength = true)]
    public string? ShowFirstThreeThenCustomMaskPreservedLengthIgnored { get; set; }

    /// <summary>
    /// 123456789 results in "_REMOVED_789"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowLast = 3)]
    public string? ShowLastThreeThenCustomMask { get; set; }

    /// <summary>
    /// 123456789 results in "_REMOVED_789"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowLast = 3, PreserveLength = true)]
    public string? ShowLastThreeThenCustomMaskPreservedLengthIgnored { get; set; }

    /// <summary>
    /// 123456789 results in "123***789"
    /// </summary>
    [LogMasked(ShowFirst = 3, ShowLast = 3)]
    public string? ShowFirstAndLastThreeAndDefaultMaskInTheMiddle { get; set; }

    /// <summary>
    /// 123456789 results in "123456789", no mask applied
    /// </summary>
    [LogMasked(ShowFirst = -1, ShowLast = -1)]
    public string? ShowFirstAndLastInvalidValues { get; set; }

    /// <summary>
    /// 123456789 results in "123***789"
    /// </summary>
    [LogMasked(ShowFirst = 3, ShowLast = 3, PreserveLength = true)]
    public string? ShowFirstAndLastThreeAndDefaultMaskInTheMiddlePreservedLength { get; set; }

    /// <summary>
    /// 123456789 results in "123_REMOVED_789"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowFirst = 3, ShowLast = 3)]
    public string? ShowFirstAndLastThreeAndCustomMaskInTheMiddle { get; set; }

    /// <summary>
    /// 123456789 results in "123_REMOVED_789". PreserveLength is ignored"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowFirst = 3, ShowLast = 3, PreserveLength = true)]
    public string? ShowFirstAndLastThreeAndCustomMaskInTheMiddlePreservedLengthIgnored { get; set; }
}

^{<a href='/src/Destructurama.Attributed.Tests/MaskedAttributeTests.cs#L9-L170' title='Snippet source file'>snippet source</a> | <a href='#snippet-CustomizedMaskedLogs' title='Start of snippet'>anchor</a>}

7. Masking a string property with regular expressions

Apply the LogReplaced attribute on a string to apply a RegEx replacement during Logging.

This is applicable in scenarios when a string contains both Sensitive and Non-Sensitive information. An example of this could be a string such as "Sensitive|NonSensitive". Then apply the attribute like the following snippet:

[LogReplaced(@"([a-zA-Z0-9]+)\|([a-zA-Z0-9]+)", "***|$2")]
public property Information { get; set; }

// Will log: "***|NonSensitive"

LogReplaced attribute is available with the following constructor:

LogReplaced(string pattern, string replacement)

Constructor arguments:

• pattern: The pattern that should be applied on value.
• replacement: The string that will be applied by RegEx.

Available properties:

• Options: The RegexOptions that will be applied. Defaults to RegexOptions.None.
• Timeout: A time-out interval to evaluate regular expression. Defaults to Regex.InfiniteMatchTimeout.

Note that replacement also works for properties of type IEnumerable<string> or derived from it, for example, string[] or List<string>.

Examples

<a id='snippet-WithRegex'></a>

public class WithRegex
{
    private const string REGEX_WITH_VERTICAL_BARS = @"([a-zA-Z0-9]+)\|([a-zA-Z0-9]+)\|([a-zA-Z0-9]+)";

    /// <summary>
    /// 123|456|789 results in "***|456|789"
    /// </summary>
    [LogReplaced(REGEX_WITH_VERTICAL_BARS, "***|$2|$3")]
    public string? RegexReplaceFirst { get; set; }

    /// <summary>
    /// 123|456|789 results in "123|***|789"
    /// </summary>
    [LogReplaced(REGEX_WITH_VERTICAL_BARS, "$1|***|$3")]
    public string? RegexReplaceSecond { get; set; }
}

^{<a href='/src/Destructurama.Attributed.Tests/Snippets.cs#L6-L25' title='Snippet source file'>snippet source</a> | <a href='#snippet-WithRegex' title='Start of snippet'>anchor</a>}

8. Working with MetadataTypeAttribute

You can apply MetadataTypeAttribute to your class providing another type with annotated properties. It may help you in the case when source type with its properties is defined in a code generated file so you don't want to put the attributes in there as they would get overwritten by the generator. Note that you have to set AttributedDestructuringPolicyOptions.RespectMetadataTypeAttribute to true.

var log = new LoggerConfiguration()
  .Destructure.UsingAttributes(x => x.RespectMetadataTypeAttribute = true)
  ...

Benchmarks

The results are available here.