/
ExceptionSummary.cs
126 lines (114 loc) · 5.43 KB
/
ExceptionSummary.cs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
// 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 Microsoft.Shared.Diagnostics;
namespace Microsoft.Extensions.Diagnostics.ExceptionSummarization;
/// <summary>
/// Holds a summary of an exception for use in telemetry.
/// </summary>
/// <remarks>
/// Metric tags typically support a limited number of distinct values, and as such they are not suitable
/// to represent values that are highly variable, such as the result of <see cref="Exception.ToString"/>.
/// An exception summary represents a low-cardinality version of an exception's information, suitable for such
/// cases.
///
/// The <see cref="ExceptionSummary.Description"/> property never includes sensitive information.
/// But the <see cref="ExceptionSummary.AdditionalDetails"/> property might contain sensitive information and thus shouldn't be used in telemetry.
/// </remarks>
public readonly struct ExceptionSummary : IEquatable<ExceptionSummary>
{
/// <summary>
/// Initializes a new instance of the <see cref="ExceptionSummary"/> struct.
/// </summary>
/// <param name="exceptionType">The type of the exception.</param>
/// <param name="description">A summary description string for telemetry.</param>
/// <param name="additionalDetails">An additional details string, primarily for diagnostics and not telemetry.</param>
public ExceptionSummary(string exceptionType, string description, string additionalDetails)
{
ExceptionType = Throw.IfNullOrWhitespace(exceptionType);
Description = Throw.IfNullOrWhitespace(description);
AdditionalDetails = Throw.IfNull(additionalDetails);
}
/// <summary>
/// Gets the type description of the exception.
/// </summary>
/// <remarks>
/// This is not guaranteed to be a type name. In particular, for inner exceptions, this will include the
/// type name of the outer exception along with the type name of the inner exception.
/// </remarks>
public string ExceptionType { get; }
/// <summary>
/// Gets the summary description of the exception.
/// </summary>
/// <remarks>
/// This is a low cardinality string suitable for use as a metric dimension, and it is guaranteed not to
/// contain privacy-sensitive information.
/// </remarks>
public string Description { get; }
/// <summary>
/// Gets the additional details of the exception.
/// </summary>
/// <remarks>
/// This string can have a relatively high cardinality and may contain privacy-sensitive information and is therefore not suitable
/// as a metric dimension. It is primarily intended for use in low-level diagnostics.
/// </remarks>
public string AdditionalDetails { get; }
/// <summary>
/// Gets a hash code for this object.
/// </summary>
/// <returns>A hash code for the current object.</returns>
public override int GetHashCode() => HashCode.Combine(
ExceptionType.GetHashCode(StringComparison.Ordinal),
Description.GetHashCode(StringComparison.Ordinal),
AdditionalDetails.GetHashCode(StringComparison.Ordinal));
/// <summary>
/// Gets a string representation of this object.
/// </summary>
/// <returns>A string representing this object.</returns>
/// <remarks>
/// The string returned by this call is not suitable to be used in telemetry as it may contain privacy-sensitive information.
/// </remarks>
public override string ToString()
{
return AdditionalDetails.Length == 0
? $"{ExceptionType}:{Description}:"
: $"{ExceptionType}:{Description}:{AdditionalDetails}";
}
/// <summary>
/// Determines whether this summary and a specified other summary are identical.
/// </summary>
/// <param name="obj">The other summary.</param>
/// <returns><see langword="true"/> if the two summaries are identical; otherwise, <see langword="false"/>.</returns>
public override bool Equals(object? obj) => obj is ExceptionSummary summary && Equals(summary);
/// <summary>
/// Determines whether this summary and a specified other summary are identical.
/// </summary>
/// <param name="other">The other summary.</param>
/// <returns><see langword="true"/> if the two summaries are identical; otherwise, <see langword="false"/>.</returns>
public bool Equals(ExceptionSummary other)
{
return other.ExceptionType.Equals(ExceptionType, StringComparison.Ordinal)
&& other.Description.Equals(Description, StringComparison.Ordinal)
&& other.AdditionalDetails.Equals(AdditionalDetails, StringComparison.Ordinal);
}
/// <summary>
/// Equality operator.
/// </summary>
/// <param name="left">First value.</param>
/// <param name="right">Second value.</param>
/// <returns><see langword="true" /> if the operands are equal, <see langword="false" /> otherwise.</returns>
public static bool operator ==(ExceptionSummary left, ExceptionSummary right)
{
return left.Equals(right);
}
/// <summary>
/// Inequality operator.
/// </summary>
/// <param name="left">First value.</param>
/// <param name="right">Second value.</param>
/// <returns><see langword="true" /> if the operands are equal, <see langword="false" /> otherwise.</returns>
public static bool operator !=(ExceptionSummary left, ExceptionSummary right)
{
return !left.Equals(right);
}
}