Updated docs on audited members and more loggingt

docs/guide/logging.md

@@ -4,6 +4,44 @@ Wolverine logs through the standard .NET `ILogger` abstraction, and there's noth
 to enable that logging other than using one of the standard approaches for bootstrapping a .NET application
 using `IHostBuilder`. Wolverine is logging all messages sent, received, and executed inline.
 
+## Log Message Execution Start
+
+Wolverine is absolutely meant for "grown up development," so there's a few options for logging and instrumentation. While Open Telemetry logging 
+is built in and will always give you the activity span for message execution start and finish, you may want the start of each
+message execution to be logged as well. Rather than force your development teams to write repetitive logging statements for every single
+message handler method, you can ask Wolverine to do that for you:
+
+snippet: sample_log_message_starting
+
+With only the defaults, Wolverine is logging the type of message and the message id. As shown in the next section, you can also add
+additional context to these log messages.
+
+In conjunction with the "audited members" that are added to these logging statements, all the logging in Wolverine is using structural logging
+for better searching within your logs. 
+
+## Contextual Logging with Audited Members
+
+::: warning
+Be cognizant of the information you're writing to log files or Open Telemetry data and whether or not that data
+is some kind of protected data like personal data identifiers.
+:::
+
+Wolverine gives you the ability to mark public fields or properties on message types as "audited members" that will be
+part of the logging messages at the beginning of message execution described in the preview section, and also in the Open Telemetry support described in the
+next section.
+
+To explicitly mark members as "audited", you *can* use attributes within your message types (and these are inherited) like so:
+
+snippet: sample_using_audit_attribute
+
+Or if you are okay using a common message interface for common identification like "this message targets an account/organization/tenant/client"
+like the `IAccountCommand` shown below:
+
+snippet: sample_account_message_for_auditing
+
+You can specify audited members through this syntax:
+
+snippet: sample_explicit_registration_of_audit_properties
 
 ## Open Telemetry
 
@@ -33,8 +71,9 @@ builder.Services.AddOpenTelemetryTracing(x =>
 
 ## Message Correlation
 
-TODO
+TODO -- Soon. This is going to be tedious
 
 ## Metrics
 
-TODO
+TODO -- there's quite a bit built in that's published through System.Diagnostics.Metrics that should be available through open telemetry exports,
+but some more experimentation and actual docs are forthcoming.

src/Samples/DocumentationSamples/LoggingUsage.cs

@@ -0,0 +1,23 @@
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Wolverine;
+
+namespace DocumentationSamples;
+
+public class LoggingUsage
+{
+    public static async Task show_entry_logging()
+    {
+        #region sample_log_message_starting
+
+        using var host = await Host.CreateDefaultBuilder()
+            .UseWolverine(opts =>
+            {
+                // Opt into having Wolverine add a log message at the beginning
+                // of the message execution
+                opts.Policies.LogMessageStarting(LogLevel.Information);
+            }).StartAsync();
+
+        #endregion
+    }
+}

src/Testing/CoreTests/Configuration/auditing_determination.cs

@@ -71,14 +71,21 @@ public void use_audit_members_from_explicit_interface_adds()
     {
         with(opts =>
         {
+            #region sample_explicit_registration_of_audit_properties
+
+            // opts is WolverineOptions inside of a UseWolverine() call
             opts.Policies.Audit<IAccountMessage>(x => x.AccountId);
+
+            #endregion
         });
 
         var chain = chainFor<DebitAccount>();
         chain.AuditedMembers.Single().Member.Name.ShouldBe(nameof(IAccountMessage.AccountId));
     }
 }
 
+#region sample_using_audit_attribute
+
 public class AuditedMessage
 {
     [Audit]
@@ -87,6 +94,8 @@ public class AuditedMessage
     [Audit("AccountIdentifier")] public int AccountId;
 }
 
+#endregion
+
 public class AuditedHandler
 {
     public void Handle(AuditedMessage message) => Console.WriteLine("Hello");
@@ -103,10 +112,15 @@ public void Handle(DebitAccount message, ILogger logger, Envelope envelope)
     }
 }
 
+#region sample_account_message_for_auditing
+
 // Marker interface
 public interface IAccountMessage
 {
     public int AccountId { get; }
 }
 
-public record DebitAccount(int AccountId, decimal Amount) : IAccountMessage;
+// A possible command that uses our marker interface above
+public record DebitAccount(int AccountId, decimal Amount) : IAccountMessage;
+
+#endregion