[CSHARP-969] - OpenTelemetry tracing

doc/features/README.md

@@ -24,9 +24,11 @@ The DataStax C# Driver for Apache Cassandra and DataStax Enterprise is a feature
   - [App.Metrics Provider](metrics/app-metrics)
   - [List of metrics](metrics/metrics-list)
 - [Native protocol](native-protocol)
+- [OpenTelemetry](opentelemetry)
 - [Parametrized queries](parametrized-queries)
 - [Query timestamps](query-timestamps)
 - [Query warnings](query-warnings)
+- [Request tracker](request-tracker)
 - [Result paging](paging)
 - [Routing queries](routing-queries)
 - [Speculative executions](speculative-retries)

doc/features/opentelemetry/README.md

@@ -0,0 +1,78 @@
+# OpenTelemetry
+
+The driver provides support for session and node level [traces](https://opentelemetry.io/docs/concepts/signals/traces/) using [OpenTelemetry instrumentation](https://opentelemetry.io/docs/instrumentation/net/).
+
+## Including OpenTelemetry instrumentation in your code
+
+Add the package `Cassandra.OpenTelemetry` to the project and add the extension method `AddOpenTelemetryInstrumentation()` when building your cluster:
+
+```csharp
+var cluster = Cluster.Builder()
+    .AddContactPoint(Program.ContactPoint)
+    .WithSessionName(Program.SessionName)
+    .AddOpenTelemetryInstrumentation()
+    .Build();
+```
+
+Once you have your .NET application instrumentation configured, Cassandra activities can be captured by adding the source `CassandraActivitySourceHelper.ActivitySourceName` in the tracer provider builder:
+
+```csharp
+using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+    .AddSource(CassandraActivitySourceHelper.ActivitySourceName)
+    ...
+```
+
+### Attributes
+
+The table below displays the list of included attributes in this feature:
+
+| Attribute  | Description  | Output Values|
+|---|---|---|
+| db.name | The keyspace name. | *keyspace in use* |
+| db.operation | The type name of the operation being executed. | *Session Request* for session level calls and *Node Request* for node level calls |
+| db.statement | The database statement being executed. Included as [optional configuration](#include-statement-as-an-attribute). | *database statement in use* |
+| db.system | An identifier for the database management system (DBMS) product being used. | cassandra |
+| server.address | The host node. | e.g.: 127.0.0.1 |
+| server.port | Port number. | e.g.: 9042 |
+
+The console log below displays an example of a full Cassandra activity:
+
+```console
+Activity.TraceId:            710e1a99afec9bcd056c9fe825bcbb3c
+Activity.SpanId:             bd42cfc78b552cd1
+Activity.TraceFlags:         Recorded
+Activity.ActivitySourceName: Cassandra.OpenTelemetry
+Activity.ActivitySourceVersion: 1.0.0.0
+Activity.DisplayName:        Session Request
+Activity.Kind:               Client
+Activity.StartTime:          2024-09-13T14:08:36.9762191Z
+Activity.Duration:           00:00:00.0416284
+Activity.Tags:
+    db.system: cassandra
+    db.operation: Session Request
+    db.name: system
+    db.statement: SELECT * FROM system.local
+Resource associated with Activity:
+    service.name: CassandraDemo
+    service.version: 1.0.0
+    service.instance.id: 5a5d88b9-cc86-4f8a-a206-9b4f507630b9
+    telemetry.sdk.name: opentelemetry
+    telemetry.sdk.language: dotnet
+    telemetry.sdk.version: 1.8.0
+```
+
+## Advanced Configuration
+
+The instrumentation can be configured to extend the default behavior by using `CassandraInstrumentationOptions`.
+
+### Include Statement as an attribute
+
+As mentioned above, the attribute `db.statement` is not included by default in the activity. To change it, set the `CassandraInstrumentationOptions` property `IncludeDatabaseStatement` as *true* when building the cluster:
+
+```csharp
+var cluster = Cluster.Builder()
+    .AddContactPoint(Program.ContactPoint)
+    .WithSessionName(Program.SessionName)
+    .AddOpenTelemetryInstrumentation(options => options.IncludeDatabaseStatement = true)
+    .Build();
+```

doc/features/request-tracker/README.md

@@ -0,0 +1,15 @@
+# Request Tracker
+
+The driver provides the `IRequestTracker` interface that tracks the requests at Session and Node levels. It contains *start*, *finish*, and *error* events that can be subscribed by implementing the interface, and should be used by passing the implementation as an argument of the method `WithRequestTracker` that is available in the `Builder`.\
+An example of an `IRequestTracker` implementation is the extension package `Cassandra.OpenTelemetry` that can be checked in the [documentation](/doc/features/opentelemetry/README.md).
+
+## Available events
+
+The full API doc is available [here](https://docs.datastax.com/en/drivers/csharp/latest/api/Cassandra.IRequestTracker.html) but the list below summarizes the events are available in the tracker:
+
+- **OnStartAsync** - that is triggered when a session level request starts.
+- **OnSuccessAsync** - that is triggered when the session level request finishes successfully.
+- **OnErrorAsync** - that is triggered when the session level request finishes unsuccessfully.
+- **OnNodeStartAsync** - that is triggered when the node request starts
+- **OnNodeSuccessAsync** - that is triggered when the node level request finishes successfully.
+- **OnNodeErrorAsync** - that is triggered when the node request finishes unsuccessfully.

examples/OpenTelemetry/ConsoleExporter/ConsoleExporter.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.8.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Extensions\Cassandra.OpenTelemetry\Cassandra.OpenTelemetry.csproj" />
+  </ItemGroup>
+
+</Project>

examples/OpenTelemetry/ConsoleExporter/Program.cs

@@ -0,0 +1,82 @@
+//
+//       Copyright (C) DataStax Inc.
+//
+//    Licensed under the Apache License, Version 2.0 (the "License");
+//    you may not use this file except in compliance with the License.
+//    You may obtain a copy of the License at
+//
+//       http://www.apache.org/licenses/LICENSE-2.0
+//
+//    Unless required by applicable law or agreed to in writing, software
+//    distributed under the License is distributed on an "AS IS" BASIS,
+//    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//    See the License for the specific language governing permissions and
+//    limitations under the License.
+//
+
+using Cassandra;
+using Cassandra.OpenTelemetry;
+using OpenTelemetry;
+using OpenTelemetry.Resources;
+using OpenTelemetry.Trace;
+
+namespace ConsoleExporter
+{
+    internal class Program
+    {
+        private const string ContactPoint = "localhost";
+        private const string SessionName = "otel-example";
+
+        private static void Main(string[] args)
+        {
+            Program.MainAsync(args).GetAwaiter().GetResult();
+        }
+
+        private static async Task MainAsync(string[] args)
+        {
+            using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+             .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(
+                 serviceName: "CassandraDemo",
+                 serviceVersion: "1.0.0"))
+             .AddSource(CassandraActivitySourceHelper.ActivitySourceName)
+             .AddConsoleExporter()
+             .Build();
+
+            var cluster = Cluster.Builder()
+                .AddContactPoint(Program.ContactPoint)
+                .WithSessionName(Program.SessionName)
+                .AddOpenTelemetryInstrumentation(options => options.IncludeDatabaseStatement = true)
+                .Build();
+
+            var session = await cluster.ConnectAsync().ConfigureAwait(false);
+
+            //// Execute a query every 5 seconds
+
+            var cts = new CancellationTokenSource();
+            var task = Task.Run(async () =>
+            {
+                while (!cts.IsCancellationRequested)
+                {
+                    try
+                    {
+                        var x = await session.ExecuteAsync(new SimpleStatement("SELECT * FROM system.local"));
+                    }
+                    catch (Exception ex)
+                    {
+                        Console.WriteLine($"ERROR: {ex}");
+                    }
+
+                    Thread.Sleep(5000);
+                }
+            });
+
+            Console.WriteLine("Press enter to shutdown the session and exit.");
+            Console.ReadLine();
+
+            cts.Cancel();
+
+            await task.ConfigureAwait(false);
+            await cluster.ShutdownAsync().ConfigureAwait(false);
+        }
+    }
+}

examples/examples.sln

@@ -37,6 +37,12 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "ColumnEncryption", "ColumnE
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ColumnEncryptionExample", "ColumnEncryption\ColumnEncryptionExample\ColumnEncryptionExample.csproj", "{AE159E33-D289-472C-8174-4FA9C55C29DF}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Cassandra.OpenTelemetry", "..\src\Extensions\Cassandra.OpenTelemetry\Cassandra.OpenTelemetry.csproj", "{10076771-C9F5-4FF4-82E7-33EC4AF555FD}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "OpenTelemetry", "OpenTelemetry", "{DD2D2F9B-513D-4518-8289-E12CB2BC5B12}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ConsoleExporter", "OpenTelemetry\ConsoleExporter\ConsoleExporter.csproj", "{616E808D-9BF5-4AB5-866B-6D4F35D1102E}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -79,6 +85,14 @@ Global
 		{AE159E33-D289-472C-8174-4FA9C55C29DF}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{AE159E33-D289-472C-8174-4FA9C55C29DF}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{AE159E33-D289-472C-8174-4FA9C55C29DF}.Release|Any CPU.Build.0 = Release|Any CPU
+		{10076771-C9F5-4FF4-82E7-33EC4AF555FD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{10076771-C9F5-4FF4-82E7-33EC4AF555FD}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{10076771-C9F5-4FF4-82E7-33EC4AF555FD}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{10076771-C9F5-4FF4-82E7-33EC4AF555FD}.Release|Any CPU.Build.0 = Release|Any CPU
+		{616E808D-9BF5-4AB5-866B-6D4F35D1102E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{616E808D-9BF5-4AB5-866B-6D4F35D1102E}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{616E808D-9BF5-4AB5-866B-6D4F35D1102E}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{616E808D-9BF5-4AB5-866B-6D4F35D1102E}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -99,6 +113,9 @@ Global
 		{1A866971-206C-4A6F-B6B1-8B0408B67618} = {A68222F1-E44C-4B20-8CEC-A10A89FC4982}
 		{1320BA10-E76B-4247-B1F1-71221349A94E} = {A589A223-6F57-40C7-BE7D-00E87354A69E}
 		{AE159E33-D289-472C-8174-4FA9C55C29DF} = {1320BA10-E76B-4247-B1F1-71221349A94E}
+		{10076771-C9F5-4FF4-82E7-33EC4AF555FD} = {EE6E727D-835E-42D1-8E62-081E0B6FAAC2}
+		{DD2D2F9B-513D-4518-8289-E12CB2BC5B12} = {A589A223-6F57-40C7-BE7D-00E87354A69E}
+		{616E808D-9BF5-4AB5-866B-6D4F35D1102E} = {DD2D2F9B-513D-4518-8289-E12CB2BC5B12}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {A731352A-6C46-4D13-A44F-07731EE671DA}

src/Cassandra.IntegrationTests/Cassandra.IntegrationTests.csproj

@@ -92,6 +92,7 @@
 
   <ItemGroup>
     <PackageReference Include="App.Metrics" Version="3.2.0" />
+    <PackageReference Include="OpenTelemetry.Exporter.InMemory" Version="1.5.1" />
     <PackageReference Include="SSH.NET" Version="2020.0.2" />
     <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
     <PackageReference Include="Appveyor.TestLogger" Version="2.0.0" />
@@ -119,6 +120,9 @@
     <PackageReference Include="JetBrains.DotMemoryUnit" Version="3.2.20220510" />
     <Reference Include="System" />
   </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\Extensions\Cassandra.OpenTelemetry\Cassandra.OpenTelemetry.csproj" />
+  </ItemGroup>
   <ItemGroup>
     <Service Include="{82a7f48d-3b50-4b1e-b82e-3ada8210c358}" />
   </ItemGroup>

src/Cassandra.IntegrationTests/Core/ConnectionTests.cs

@@ -30,7 +30,7 @@
 using Cassandra.IntegrationTests.SimulacronAPI.Models.Logs;
 using Cassandra.IntegrationTests.TestBase;
 using Cassandra.IntegrationTests.TestClusterManagement.Simulacron;
-using Cassandra.Observers;
+using Cassandra.Observers.Null;
 using Cassandra.Tasks;
 using Cassandra.Tests;
 using Cassandra.Requests;