Add OpenTelemetry event tracing to connections

.github/workflows/docs-prs.yml

@@ -28,7 +28,7 @@ jobs:
       - uses: actions/setup-node@v4
         name: Setup node
         with:
-          node-version: 18
+          node-version: 20
       - run: npm install -g cspell
         name: Install cSpell
       - run: cspell --config ./docs/cSpell.json "docs/**/*.md"

.github/workflows/docs.yml

@@ -15,7 +15,7 @@ env:
   config: Release
   DOTNET_CLI_TELEMETRY_OPTOUT: 1
   DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
-  node_version: 18.x
+  node_version: 20.x
 
 jobs:
   build-and-test-code:
@@ -32,7 +32,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Install Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ env.node_version }}
 

Directory.Build.props

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project>
     <PropertyGroup>
-        <Version>7.5.0</Version>
+        <Version>7.8.0</Version>
         <LangVersion>12.0</LangVersion>
         <Authors>Jeremy D. Miller;Babu Annamalai;Oskar Dudycz;Joona-Pekka Kokko</Authors>
         <PackageIconUrl>https://martendb.io/logo.png</PackageIconUrl>

docs/.vitepress/config.mts

@@ -84,13 +84,13 @@ const config: UserConfig<DefaultTheme.Config> = {
           text: 'Configuration',
           collapsed: false,
           items: [
-            { text: 'Bootstrap with HostBuilder', link: '/configuration/hostbuilder' },
+            { text: 'Bootstrapping Marten', link: '/configuration/hostbuilder' },
             { text: 'Configuring Document Storage', link: '/configuration/storeoptions' },
             { text: 'Json Serialization', link: '/configuration/json' },
             { text: 'Resiliency Policies', link: '/configuration/retries' },
             { text: 'Pre-Building Generated Types', link: '/configuration/prebuilding' },
             { text: 'Command Line Tooling', link: '/configuration/cli' },
-            { text: 'Development versus Production Usage', link: '/configuration/optimized_artifact_workflow' },
+            { text: 'Optimized Development Workflow', link: '/configuration/optimized_artifact_workflow' },
             { text: 'Multi-Tenancy with Database per Tenant', link: '/configuration/multitenancy' },
             { text: 'Environment Checks', link: '/configuration/environment-checks' },
             { text: 'Custom IoC Integration', link: '/configuration/ioc' },
@@ -108,7 +108,7 @@ const config: UserConfig<DefaultTheme.Config> = {
             { text: 'Storing Documents', link: '/documents/storing' },
             { text: 'Deleting Documents', link: '/documents/deletes' },
             {
-              text: 'Querying Documents', link: '/documents/querying/', collapsed: false, items: [
+              text: 'Querying Documents', link: '/documents/querying/', collapsed: true, items: [
                 { text: 'Loading Documents by Id', link: '/documents/querying/byid' },
                 { text: 'Querying Documents with Linq', link: '/documents/querying/linq/' },
                 { text: 'Supported Linq Operators', link: '/documents/querying/linq/operators' },
@@ -130,7 +130,7 @@ const config: UserConfig<DefaultTheme.Config> = {
             },
 
             {
-              text: 'Indexing Documents', link: '/documents/indexing/', collapsed: false, items: [
+              text: 'Indexing Documents', link: '/documents/indexing/', collapsed: true, items: [
                 { text: 'Calculated Indexes', link: '/documents/indexing/computed-indexes' },
                 { text: 'Duplicated Fields', link: '/documents/indexing/duplicated-fields' },
                 { text: 'Unique Indexes', link: '/documents/indexing/unique' },
@@ -165,7 +165,7 @@ const config: UserConfig<DefaultTheme.Config> = {
             { text: 'Metadata', link: '/events/metadata' },
             { text: 'Archiving Streams', link: '/events/archiving' },
             {
-              text: 'Projections Overview', link: '/events/projections/', collapsed: false, items: [
+              text: 'Projections Overview', link: '/events/projections/', collapsed: true, items: [
                 {
                   text: 'Aggregate Projections', link: '/events/projections/aggregate-projections', items: [
                     { text: 'Live Aggregations', link: '/events/projections/live-aggregates' },
@@ -181,8 +181,11 @@ const config: UserConfig<DefaultTheme.Config> = {
                 { text: 'Rebuilding Projections', link: '/events/projections/rebuilding' },
                 { text: 'Projections and IoC Services', link: '/events/projections/ioc' },
                 { text: 'Async Daemon HealthChecks', link: '/events/projections/healthchecks' },]
+            }, 
+            {
+                text: 'Event Subscriptions',
+                link: '/events/subscriptions'
             },
-
             {
               text: 'Event Versioning',
               link: '/events/versioning'

docs/configuration/hostbuilder.md

@@ -1,13 +1,6 @@
-# Bootstrapping in .Net Applications
+# Bootstrapping Marten
 
-:::tip
-The exact formula for bootstrapping .Net applications has changed quite a bit from early .Net Core to the latest `WebApplication` model in .Net 6.0 at the time this page was last updated. Regardless, the `IServiceCollection` abstraction for registering services in an IoC container has remained stable and everything in this page functions against that model.
-:::
-
-As briefly shown in the [getting started](/) page, Marten comes with extension methods for the .Net Core standard `IServiceCollection` to quickly add Marten services to any .Net application that is bootstrapped by either the [Generic IHostBuilder abstraction](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/host/generic-host) or the [ASP.Net Core IWebHostBuilder](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.hosting.iwebhostbuilder) or the [.Net 6 WebApplication](https://docs.microsoft.com/en-us/aspnet/core/migration/50-to-60?view=aspnetcore-6.0&tabs=visual-studio#new-hosting-model) hosting models.
-
-Jumping right into a basic ASP.NET Core application using the out of the box Web API template, you'd have a class called `Startup` that holds most of the configuration for your application including
-the IoC service registrations for your application in the `Startup.ConfigureServices()` method. To add Marten to your application, use the `AddMarten()` method as shown below:
+As briefly shown in the [getting started](/) page, Marten comes with the `AddMarten()` extension method for the .NET `IServiceCollection` to quickly add Marten to any ASP.NET Core or Worker Service application:
 
 <!-- snippet: sample_StartupConfigureServices -->
 <a id='snippet-sample_startupconfigureservices'></a>
@@ -19,6 +12,9 @@ builder.Services.AddMarten(options =>
     // Establish the connection string to your Marten database
     options.Connection(builder.Configuration.GetConnectionString("Marten")!);
 
+    // Specify that we want to use STJ as our serializer
+    options.UseSystemTextJsonForSerialization();
+
     // If we're running in development mode, let Marten just take care
     // of all necessary schema building and patching behind the scenes
     if (builder.Environment.IsDevelopment())
@@ -27,7 +23,7 @@ builder.Services.AddMarten(options =>
     }
 });
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/AspNetCoreWithMarten/Program.cs#L14-L29' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_startupconfigureservices' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/AspNetCoreWithMarten/Program.cs#L15-L33' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_startupconfigureservices' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 The `AddMarten()` method will add these service registrations to your application:
@@ -46,9 +42,10 @@ At runtime, when your application needs to resolve `IDocumentStore` for the firs
 
 1. Resolve a `StoreOptions` object from the initial `AddMarten()` configuration
 2. Apply all registered `IConfigureMarten` services to alter that `StoreOptions` object
-3. Reads the `IHostEnvironment` for the application if it exists to try to determine the main application assembly and paths for generated code output
-4. Attaches any `IInitialData` services that were registered in the IoC container to the `StoreOptions` object
-5. *Finally*, Marten builds a new `DocumentStore` object using the now configured `StoreOptions` object
+3. Apply all registered `IAsyncConfigureMarten` services to alter that `StoreOptions` object
+4. Reads the `IHostEnvironment` for the application if it exists to try to determine the main application assembly and paths for generated code output
+5. Attaches any `IInitialData` services that were registered in the IoC container to the `StoreOptions` object
+6. *Finally*, Marten builds a new `DocumentStore` object using the now configured `StoreOptions` object
 
 This model is comparable to the .Net `IOptions` model.
 
@@ -215,7 +212,7 @@ public interface IConfigureMarten
     void Configure(IServiceProvider services, StoreOptions options);
 }
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/MartenServiceCollectionExtensions.cs#L816-L827' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_iconfiguremarten' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/MartenServiceCollectionExtensions.cs#L894-L905' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_iconfiguremarten' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 You could alternatively implement a custom `IConfigureMarten` (or `IConfigureMarten<T> where T : IDocumentStore` if you're [working with multiple databases](#working-with-multiple-marten-databases)) class like so:
@@ -258,7 +255,67 @@ public static IServiceCollection AddUserModule2(this IServiceCollection services
 <sup><a href='https://github.com/JasperFx/marten/blob/master/src/CoreTests/BootstrappingExamples.cs#L36-L53' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_addusermodule2' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
-## Using Lightweight Sessions
+### Using IoC Services for Configuring Marten <Badge type="tip" text="7.7" />
+
+There is also a newer mechanism called `IAsyncConfigureMarten` that was originally built to enable services
+like the [Feature Management library from Microsoft](https://learn.microsoft.com/en-us/azure/azure-app-configuration/use-feature-flags-dotnet-core) to
+be used to selectively configure Marten using potentially asynchronous methods and IoC resolved services. 
+
+That interface signature is:
+
+<!-- snippet: sample_IAsyncConfigureMarten -->
+<a id='snippet-sample_iasyncconfiguremarten'></a>
+```cs
+/// <summary>
+///     Mechanism to register additional Marten configuration that is applied after AddMarten()
+///     configuration, but before DocumentStore is initialized when you need to utilize some
+/// kind of asynchronous services like Microsoft's FeatureManagement feature to configure Marten
+/// </summary>
+public interface IAsyncConfigureMarten
+{
+    ValueTask Configure(StoreOptions options, CancellationToken cancellationToken);
+}
+```
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/MartenServiceCollectionExtensions.cs#L907-L919' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_iasyncconfiguremarten' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+As an example from the tests, here's a custom version that uses the Feature Management service:
+
+<!-- snippet: sample_FeatureManagementUsingExtension -->
+<a id='snippet-sample_featuremanagementusingextension'></a>
+```cs
+public class FeatureManagementUsingExtension: IAsyncConfigureMarten
+{
+    private readonly IFeatureManager _manager;
+
+    public FeatureManagementUsingExtension(IFeatureManager manager)
+    {
+        _manager = manager;
+    }
+
+    public async ValueTask Configure(StoreOptions options, CancellationToken cancellationToken)
+    {
+        if (await _manager.IsEnabledAsync("Module1"))
+        {
+            options.Events.MapEventType<Module1Event>("module1:event");
+        }
+    }
+}
+```
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/CoreTests/configuring_marten_with_async_extensions.cs#L77-L97' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_featuremanagementusingextension' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+And lastly, these extensions can be registered directly against `IServiceCollection` like so:
+
+<!-- snippet: sample_registering_async_config_marten -->
+<a id='snippet-sample_registering_async_config_marten'></a>
+```cs
+services.ConfigureMartenWithServices<FeatureManagementUsingExtension>();
+```
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/CoreTests/configuring_marten_with_async_extensions.cs#L34-L38' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_registering_async_config_marten' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+## Using Lightweight Sessions 
 
 ::: tip
 Most usages of Marten should default to the lightweight sessions for better performance

docs/configuration/optimized_artifact_workflow.md

@@ -1,10 +1,4 @@
-# Development versus Production Usage
-
-:::tip
-Marten V5.0 introduces the new `AddMarten().OptimizeArtifactWorkflow()` option
-that helps users utilize Marten "best practices" for database and code generation
-artifact creation.
-:::
+# Optimized Development Workflow
 
 The original point of Marten was to have a persistence option that mostly got out of your way and
 let developers just get things done without having to spend a lot of time fiddling with database

docs/configuration/prebuilding.md

@@ -1,9 +1,9 @@
 # Pre-Building Generated Types
 
-Marten >= v4 extensively uses runtime code generation backed by [Roslyn runtime compilation](https://jeremydmiller.com/2018/06/04/compiling-code-at-runtime-with-lamar-part-1/) for dynamic code.
+Marten uses runtime code generation backed by [Roslyn runtime compilation](https://jeremydmiller.com/2018/06/04/compiling-code-at-runtime-with-lamar-part-1/) for dynamic code.
 This is both much more powerful than [source generators](https://docs.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview) in what it allows us to actually do, but can have
 significant memory usage and “[cold start](https://en.wikipedia.org/wiki/Cold_start_(computing))” problems (seems to depend on exact configurations, so it’s not a given that you’ll have these issues).
-Fear not though, Marten v4 introduced a facility to “generate ahead” the code to greatly optimize the "cold start" and memory usage in production scenarios.
+Fear not though, Marten introduced a facility to “generate ahead” the code to greatly optimize the "cold start" and memory usage in production scenarios.
 
 The code generation for document storage, event handling, event projections, and additional document stores can be done
 with one of three modes as shown below:
@@ -21,17 +21,17 @@ using var store = DocumentStore.For(opts =>
 
     // Marten will only use types that are compiled into
     // the application assembly ahead of time. This is the
-    // V4 "pre-built" model
+    // "pre-built" model
     opts.GeneratedCodeMode = TypeLoadMode.Static;
 
-    // New for V5. More explanation in the docs:)
+    // Explained Below :)
     opts.GeneratedCodeMode = TypeLoadMode.Auto;
 });
 ```
 <sup><a href='https://github.com/JasperFx/marten/blob/master/src/CoreTests/Examples/CodeGenerationOptions.cs#L16-L35' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_code_generation_modes' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
-The *Auto* mode is new for Marten V5 to alleviate usability issues for folks who did not find the command line options or pre-registration
+The *Auto* mode was added alleviate usability issues for folks who did not find the command line options or pre-registration
 of document types to be practical. Using the `Marten.Testing.Documents.User` document from the Marten testing suite
 as an example, let's start a new document store with the `Auto` mode:
 
@@ -80,7 +80,7 @@ into the actually deployed binaries for the system in production deployments. Of
 you will need to delete the generated code.
 
 :::tip
-Just like ASP.Net MVC, Marten uses the `IHostEnvironment.ApplicationName` property to determine the main application assembly. If
+Just like ASP.NET Core, Marten uses the `IHostEnvironment.ApplicationName` property to determine the main application assembly. If
 that value is missing, Marten falls back to the `Assembly.GetEntryAssembly()` value.
 :::
 

docs/diagnostics.md

@@ -89,7 +89,7 @@ public interface IDocumentSessionListener
     void DocumentAddedForStorage(object id, object document);
 }
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/IDocumentSessionListener.cs#L8-L84' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_idocumentsessionlistener' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/IDocumentSessionListener.cs#L27-L103' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_idocumentsessionlistener' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 You can build and inject your own listeners by adding them to the `StoreOptions` object you use to configure a `DocumentStore`:

docs/documents/aspnetcore.md

@@ -4,7 +4,7 @@
 For a little more context, see the blog post [Efficient Web Services with Marten V4](https://jeremydmiller.com/2021/09/28/efficient-web-services-with-marten-v4/).
 :::
 
-In Marten V4, there is a small new addon that adds helpers for ASP.Net Core development, expressly
+Marten has a small addon that adds helpers for ASP.Net Core development, expressly
 the ability to very efficiently _stream_ the raw JSON of persisted documents straight to an HTTP response
 without every having to waste time with deserialization/serialization or even reading the data into a JSON
 string in memory.