Add comments pointing to the source of logging dimension names

src/Libraries/Microsoft.AspNetCore.Diagnostics.Middleware/Logging/HeaderNormalizer.cs

@@ -20,9 +20,11 @@ public static string[] PrepareNormalizedHeaderNames(KeyValuePair<string, DataCla
     }
 
     [SuppressMessage("Globalization", "CA1308:Normalize strings to uppercase",
-        Justification = "Normalization to lower case is required by OTel's semantic conventions")]
+        Justification = "Normalization to lower case is required by OTel semantic conventions")]
     private static string Normalize(string header)
     {
+        // Normalization of header names required by OTel semantic-conventions:
+        // https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#common-attributes.
         return header.ToLowerInvariant();
     }
 }

src/Libraries/Microsoft.AspNetCore.Diagnostics.Middleware/Logging/HttpLoggingTagNames.cs

@@ -9,6 +9,12 @@ namespace Microsoft.AspNetCore.Diagnostics.Logging;
 /// <summary>
 /// Constants used for incoming HTTP request logging tags.
 /// </summary>
+// There is no OTel semantic convention for HTTP logs, therefore we are using
+// semantic conventions for HTTP spans:
+// https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md.
+// Some dimensions (e.g. Host and Method) were not renamed, though they had corresponding
+// names in the semantic conventions. The reason is that they are coming from ASP.NET Core 8
+// HttpLogging component, therefore we cannot rename them.
 public static class HttpLoggingTagNames
 {
     /// <summary>
@@ -19,6 +25,7 @@ public static class HttpLoggingTagNames
     /// <summary>
     /// HTTP Host.
     /// </summary>
+    // See https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#http-server-semantic-conventions.
     public const string Host = "server.address";
 
     /// <summary>
@@ -34,11 +41,13 @@ public static class HttpLoggingTagNames
     /// <summary>
     /// HTTP Request Headers prefix.
     /// </summary>
+    // See https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#common-attributes.
     public const string RequestHeaderPrefix = "http.request.header.";
 
     /// <summary>
     /// HTTP Response Headers prefix.
     /// </summary>
+    // See https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#common-attributes.
     public const string ResponseHeaderPrefix = "http.response.header.";
 
     /// <summary>

src/Libraries/Microsoft.Extensions.Diagnostics.Extra/Enrichment/ApplicationEnricherTags.cs

@@ -14,11 +14,13 @@ public static class ApplicationEnricherTags
     /// <summary>
     /// Application name.
     /// </summary>
+    // See https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#service.
     public const string ApplicationName = "service.name";
 
     /// <summary>
     /// Environment name.
     /// </summary>
+    // See https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/deployment-environment.md#deployment.
     public const string EnvironmentName = "deployment.environment";
 
     /// <summary>
@@ -29,6 +31,7 @@ public static class ApplicationEnricherTags
     /// <summary>
     /// Build version.
     /// </summary>
+    // See https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#service.
     public const string BuildVersion = "service.version";
 
     /// <summary>

src/Libraries/Microsoft.Extensions.Diagnostics.Extra/Enrichment/ProcessEnricherTagNames.cs

@@ -14,11 +14,13 @@ public static class ProcessEnricherTagNames
     /// <summary>
     /// Process ID.
     /// </summary>
+    // See https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/process.md#process.
     public const string ProcessId = "process.pid";
 
     /// <summary>
     /// Thread ID.
     /// </summary>
+    // See https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#general-thread-attributes.
     public const string ThreadId = "thread.id";
 
     /// <summary>

src/Libraries/Microsoft.Extensions.Diagnostics.Extra/Logging/ExtendedLogger.cs

@@ -21,6 +21,8 @@ namespace Microsoft.Extensions.Logging;
 
 internal sealed partial class ExtendedLogger : ILogger
 {
+    // We are using OTel semantic conventions for Exceptions in Logs:
+    // https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-logs.md.
     private const string ExceptionType = "exception.type";
     private const string ExceptionMessage = "exception.message";
     private const string ExceptionStackTrace = "exception.stacktrace";

src/Libraries/Microsoft.Extensions.Http.Diagnostics/Logging/HttpClientLoggingTagNames.cs

@@ -9,6 +9,9 @@ namespace Microsoft.Extensions.Http.Logging;
 /// <summary>
 /// Constants used for HTTP client logging tags.
 /// </summary>
+// There is no OTel semantic convention for HTTP logs, therefore we are using semantic conventions for HTTP spans:
+// https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md.
+// "Duration", "RequestBody" and "ResponseBody" are not part of the semantic conventions though.
 public static class HttpClientLoggingTagNames
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.Http.Diagnostics/Logging/Internal/LoggerMessageStateExtensions.cs

@@ -54,9 +54,11 @@ public static void AddResponseHeaders(this LoggerMessageState state, List<KeyVal
     }
 
     [SuppressMessage("Globalization", "CA1308:Normalize strings to uppercase",
-        Justification = "Normalization to lower case is required by OTel's semantic conventions")]
+        Justification = "Normalization to lower case is required by OTel semantic conventions")]
     private static string Normalize(string header)
     {
+        // Normalization of header names required by OTel semantic-conventions:
+        // https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#common-attributes.
         return header.ToLowerInvariant();
     }
 }