Adding readme

Author: kevbite

README.md

@@ -0,0 +1,116 @@
+# Kevsoft.AWSXRayRecorder.Handlers.MongoDB [![Continuous Integration Workflow](https://github.com/kevbite/Kevsoft.AWSXRayRecorder.Handlers.MongoDB/actions/workflows/continuous-integration-workflow.yml/badge.svg)](https://github.com/kevbite/Kevsoft.AWSXRayRecorder.Handlers.MongoDB/actions/workflows/continuous-integration-workflow.yml) [![install from nuget](http://img.shields.io/nuget/v/Kevsoft.AWSXRayRecorder.Handlers.MongoDB.svg?style=flat-square)](https://www.nuget.org/packages/Kevsoft.AWSXRayRecorder.Handlers.MongoDB) [![downloads](http://img.shields.io/nuget/dt/Kevsoft.AWSXRayRecorder.Handlers.MongoDB.svg?style=flat-square)](https://www.nuget.org/packages/Kevsoft.AWSXRayRecorder.Handlers.MongoDB)
+
+.NET library to trace MongoDB queries with AWS XRay
+
+![XRay Trace Map](assets/xray-trace-map.png "XRay Trace Map")
+
+## Getting Started
+
+### Installing Package
+
+**Kevsoft.AWSXRayRecorder.Handlers.MongoDB** can be installed directly via the package manager console by executing the following commandlet:
+
+```powershell
+Install-Package Kevsoft.AWSXRayRecorder.Handlers.MongoDB
+```
+
+alternative you can use the dotnet CLI.
+
+```bash
+dotnet add package Kevsoft.AWSXRayRecorder.Handlers.MongoDB
+```
+
+## Usage
+
+### Configuring MongoDB Client
+
+When creating a MongoDB client you'll need to add some extra configuration with the `ConfigureXRay` extension method:
+```csharp
+var settings = new MongoClientSettings
+      {
+            Server = new MongoServerAddress("localhost")
+      }.ConfigureXRay();
+var mongoClient = new MongoClient(settings);
+```
+
+You can also configure it straight from the MongoUrl:
+
+```csharp
+var mongoUrl = MongoUrl.Create("mongodb://localhost");
+var settings = MongoClientSettings.FromUrl(mongoUrl)
+      .ConfigureXRay();
+var mongoClient = new MongoClient(settings);
+```
+
+Once configured then the queries to MongoDB will be sampled based on your [XRay sampling configuration](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-configuration.html#xray-sdk-dotnet-configuration-sampling).
+
+### Mongo XRay Options
+
+The `ConfigureXRay` extension method can accept an additional `MongoXRayOptions` object that allows you to configure what is traced to AWS XRay.
+
+#### Filtering Commands
+
+By default the library filters out the following MongoDB commands sent to the server:
+- buildInfo
+- getLastError
+- isMaster
+- ping
+- saslStart
+- saslContinue
+
+If you require these to commands to be traced, you can clear (or remove) the filtered commands:
+```csharp
+var mongoXRayOptions = new MongoXRayOptions();
+mongoXRayOptions.FilteredCommands.Clear();
+
+var mongoClientSettings = new MongoClientSettings()
+                     .ConfigureXRay(mongoXRayOptions);
+```
+
+Additional if you want to omit a command when tracing you can add an extra command, for example if we want to omit the `find` command.
+
+```csharp
+var mongoXRayOptions = new MongoXRayOptions();
+mongoXRayOptions.FilteredCommands.Add("find");
+
+var mongoClientSettings = new MongoClientSettings()
+                     .ConfigureXRay(mongoXRayOptions);
+```
+
+#### Disabling Command Text
+
+By default the library add the command to the AWS XRay annotations, however, if you're sending across secret information you might want to disable this.
+```csharp
+var mongoXRayOptions = new MongoXRayOptions
+{
+   EnableMongoCommandTextInstrumentation = false
+};
+
+var mongoClientSettings = new MongoClientSettings()
+                     .ConfigureXRay(mongoXRayOptions);
+```
+
+#### Adjusting Max Query Time
+
+The library has to keep trace of currently inflight queries, however, this could be come problematic if no query every finishes or spans for days. The library sets a sensible default of 4 hours, but you can change this by settings the `MaxQueryTime` on the settings:
+```csharp
+var mongoXRayOptions = new MongoXRayOptions
+{
+   MaxQueryTime = TimeSpan.FromSeconds(30)
+};
+
+var mongoClientSettings = new MongoClientSettings()
+                     .ConfigureXRay(mongoXRayOptions);
+```
+
+## Samples
+
+The [samples](samples/) folder containers examples of how you could use the Library.
+
+## Contributing
+
+1. Issue
+1. Fork
+1. Hack!
+1. Pull Request
+

assets/xray-trace-map.png

@@ -1,4 +1,4 @@
-using System.Threading.Tasks;
+using System.Threading.Tasks;
 using Kevsoft.AWSXRayRecorder.Handlers.MongoDB;
 using Microsoft.AspNetCore.Mvc;
 using MongoDB.Bson;
@@ -14,7 +14,7 @@ public class ExampleController : ControllerBase
         [HttpGet]
         public async Task<string> Get()
         {
-            var settings = XRayMongoClientSettingsConfigurator.Configure(new MongoClientSettings { }, new MongoXRayOptions());
+            var settings = XRayMongoClientSettingsConfigurator.ConfigureXRay(new MongoClientSettings { }, new MongoXRayOptions());
 
             var mongoClient = new MongoClient(settings);
 

samples/AspNetCoreWebAPI/Controllers/ExampleController.cs

@@ -21,13 +21,22 @@ public static class XRayMongoClientSettingsConfigurator
 
         private static MongoXRayOptions _settings = new();
 
+        /// <summary>
+        /// Configures the mongo client settings to trace with XRay
+        /// </summary>
+        /// <param name="mongoDbSettings"></param>
+        /// <returns></returns>
+        public static MongoClientSettings ConfigureXRay(this MongoClientSettings mongoDbSettings)
+        {
+            return ConfigureXRay(mongoDbSettings, new MongoXRayOptions());
+        }
         /// <summary>
         /// Configures the mongo client settings to trace with XRay
         /// </summary>
         /// <param name="mongoDbSettings"></param>
         /// <param name="settings"></param>
         /// <returns></returns>
-        public static MongoClientSettings Configure(MongoClientSettings mongoDbSettings, MongoXRayOptions settings)
+        public static MongoClientSettings ConfigureXRay(this MongoClientSettings mongoDbSettings, MongoXRayOptions settings)
         {
             _settings = settings;
             _nextPruneTimeTicks = DateTime.UtcNow.Add(_settings.MaxQueryTime).Ticks;

src/Kevsoft.AWSXRayRecorder.Handlers.MongoDB/XRayMongoClientSettingsConfigurator.cs

@@ -19,9 +19,8 @@ public async Task ShouldEmitMongoDBSubSegment()
         {
             Amazon.XRay.Recorder.Core.AWSXRayRecorder.InitializeInstance();
             Amazon.XRay.Recorder.Core.AWSXRayRecorder.Instance.Emitter = this;
-            var settings =
-                XRayMongoClientSettingsConfigurator.Configure(new MongoClientSettings(), new MongoXRayOptions());
 
+            var settings = new MongoClientSettings().ConfigureXRay();
             var mongoClient = new MongoClient(settings);
 
             var database = mongoClient.GetDatabase("test");
@@ -52,7 +51,7 @@ public async Task ShouldEmitMongoDBSubSegmentOnFailedCommand()
             Amazon.XRay.Recorder.Core.AWSXRayRecorder.InitializeInstance();
             Amazon.XRay.Recorder.Core.AWSXRayRecorder.Instance.Emitter = this;
 
-            var settings = XRayMongoClientSettingsConfigurator.Configure(new MongoClientSettings(), new MongoXRayOptions());
+            var settings = new MongoClientSettings().ConfigureXRay();
 
             var mongoClient = new MongoClient(settings);