Add tracing instrumentation of Append & Subscribe operations

EventStore · Apr 25, 2024 · 0332127 · 0332127
1 parent 1c555a4
commit 0332127
Show file tree

Hide file tree

Showing 70 changed files with 1,786 additions and 755 deletions.
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -17,8 +17,8 @@
         <GrpcToolsPackageVersion>2.60.0</GrpcToolsPackageVersion>
     </PropertyGroup>
 
-		<ItemGroup Condition="'$(TargetFramework)' == 'net48'">
-			<Reference Include="System.Net.Http"/>
-			<Reference Include="System.Web"/>
-		</ItemGroup>
+    <ItemGroup Condition="'$(TargetFramework)' == 'net48'">
+        <Reference Include="System.Net.Http" />
+        <Reference Include="System.Web" />
+    </ItemGroup>
 </Project>
diff --git a/EventStore.Client.sln b/EventStore.Client.sln
@@ -33,6 +33,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "EventStore.Client.UserManag
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "EventStore.Client.Tests.Common", "test\EventStore.Client.Tests.Common\EventStore.Client.Tests.Common.csproj", "{E326832D-DE52-4DE4-9E54-C800908B75F3}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "EventStore.Client.Extensions.OpenTelemetry", "src\EventStore.Client.Extensions.OpenTelemetry\EventStore.Client.Extensions.OpenTelemetry.csproj", "{3723933C-585A-49BE-98E8-52D3FAD904CE}"
+EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "EventStore.Client.Plugins.Tests", "test\EventStore.Client.Plugins.Tests\EventStore.Client.Plugins.Tests.csproj", "{7D929D45-F1D9-462B-BE49-84BEC11D5039}"
 EndProject
 Global
@@ -96,6 +98,10 @@ Global
 		{E326832D-DE52-4DE4-9E54-C800908B75F3}.Debug|x64.Build.0 = Debug|Any CPU
 		{E326832D-DE52-4DE4-9E54-C800908B75F3}.Release|x64.ActiveCfg = Release|Any CPU
 		{E326832D-DE52-4DE4-9E54-C800908B75F3}.Release|x64.Build.0 = Release|Any CPU
+		{3723933C-585A-49BE-98E8-52D3FAD904CE}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{3723933C-585A-49BE-98E8-52D3FAD904CE}.Debug|x64.Build.0 = Debug|Any CPU
+		{3723933C-585A-49BE-98E8-52D3FAD904CE}.Release|x64.ActiveCfg = Release|Any CPU
+		{3723933C-585A-49BE-98E8-52D3FAD904CE}.Release|x64.Build.0 = Release|Any CPU
 		{7D929D45-F1D9-462B-BE49-84BEC11D5039}.Debug|x64.ActiveCfg = Debug|Any CPU
 		{7D929D45-F1D9-462B-BE49-84BEC11D5039}.Debug|x64.Build.0 = Debug|Any CPU
 		{7D929D45-F1D9-462B-BE49-84BEC11D5039}.Release|x64.ActiveCfg = Release|Any CPU
@@ -115,6 +121,7 @@ Global
 		{6CEB731F-72E1-461F-A6B3-54DBF3FD786C} = {C51F2C69-45A9-4D0D-A708-4FC319D5D340}
 		{22634CEE-4F7B-4679-A48D-38A2A8580ECA} = {C51F2C69-45A9-4D0D-A708-4FC319D5D340}
 		{E326832D-DE52-4DE4-9E54-C800908B75F3} = {C51F2C69-45A9-4D0D-A708-4FC319D5D340}
+		{3723933C-585A-49BE-98E8-52D3FAD904CE} = {EA59C1CB-16DA-4F68-AF8A-642A969B4CF8}
 		{7D929D45-F1D9-462B-BE49-84BEC11D5039} = {C51F2C69-45A9-4D0D-A708-4FC319D5D340}
 	EndGlobalSection
 EndGlobal
diff --git a/README.md b/README.md
@@ -19,6 +19,24 @@ Reference the nuget package(s) for the API that you would like to call
 
 [User Management](https://www.nuget.org/packages/EventStore.Client.Grpc.UserManagement)
 
+## Open Telemetry
+
+Telemetry instrumentation can be enabled by installing the [Open Telemetry Extensions](https://www.nuget.org/packages/EventStore.Client.Extensions.OpenTelemetry) package.
+
+Once installed you can configure instrumentation using the `AddEventStoreClientInstrumentation` extension method on a `TracerProviderBuilder`.
+
+```csharp
+using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+    ...
+    .AddEventStoreClientInstrumentation()
+    ...
+    .Build();
+```
+
+Tracing is the only telemetry currently exported, specifically for the `Append` and `Subscribe` (Catchup and Persistent) operations.
+
+For more information about Open Telemetry, refer to the [official documentation](https://opentelemetry.io/docs/what-is-opentelemetry/).
+
 ## Support
 
 Information on support and commercial tools such as LDAP authentication can be found here: [Event Store Support](https://eventstore.com/support/).

diff --git a/gencert.ps1 b/gencert.ps1
@@ -7,7 +7,7 @@ New-Item -ItemType Directory -Path .\certs -Force
 icacls .\certs /grant:r "$($env:UserName):(OI)(CI)F"
 
 # Pull the Docker image
-docker pull ghcr.io/eventstore/es-gencert-cli:1.3
+docker pull ghcr.io/eventstore/es-gencert-cli:1.3.0
 
 docker run --rm --volume .\certs:/tmp ghcr.io/eventstore/es-gencert-cli create-ca -out /tmp/ca
 

diff --git a/gencert.sh b/gencert.sh
@@ -13,7 +13,7 @@ mkdir -p certs
 
 chmod 0755 ./certs
 
-docker pull ghcr.io/eventstore/es-gencert-cli:1.3
+docker pull ghcr.io/eventstore/es-gencert-cli:1.3.0
 
 docker run --rm --volume $PWD/certs:/tmp --user $(id -u):$(id -g) ghcr.io/eventstore/es-gencert-cli create-ca -out /tmp/ca
 

diff --git a/samples/secure-with-tls/docker-compose.certs.yml b/samples/secure-with-tls/docker-compose.certs.yml
@@ -16,7 +16,7 @@ services:
     network_mode: none
 
   cert-gen:
-    image: ghcr.io/eventstore/es-gencert-cli:1.3
+    image: eventstore/es-gencert-cli:1.3.0
     container_name: cert-gen
     user: "1000:1000"
     entrypoint: [ "/bin/sh","-c" ]

diff --git a/src/Directory.Build.props b/src/Directory.Build.props
@@ -1,19 +1,25 @@
 <Project>
-    <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))"/>
+    <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />
+
     <PropertyGroup>
         <RootNamespace>EventStore.Client</RootNamespace>
     </PropertyGroup>
 
-    <PropertyGroup Condition="$(MSBuildProjectName) != 'EventStore.Client'">
-        <ESPackageIdSuffix>$(MSBuildProjectName.Remove(0,18))</ESPackageIdSuffix>
-        <ESProto>$(ESPackageIdSuffix.ToLower()).proto</ESProto>
-        <ESProtoPath>../EventStore.Client.Common/protos/$(ESProto)</ESProtoPath>
-        <PackageId>EventStore.Client.Grpc.$(ESPackageIdSuffix)</PackageId>
-    </PropertyGroup>
-
+    <!-- Reference client base project -->
     <ItemGroup Condition="$(MSBuildProjectName) != 'EventStore.Client'">
-        <ProjectReference Include="..\EventStore.Client\EventStore.Client.csproj"/>
-        <Protobuf Access="internal" Include="$(ESProtoPath)" GrpcServices="Client" Link="protos/$(ESProto)"/>
+        <ProjectReference Include="..\EventStore.Client\EventStore.Client.csproj" />
+    </ItemGroup>
+
+    <!-- Set package id and generate proto file path-->
+    <PropertyGroup Condition="$(MSBuildProjectName) != 'EventStore.Client' And $(MSBuildProjectName) != 'EventStore.Client.Extensions.OpenTelemetry'">
+        <PackageIdSuffix>$(MSBuildProjectName.Remove(0,18))</PackageIdSuffix>
+        <PackageId>EventStore.Client.Grpc.$(PackageIdSuffix)</PackageId>
+        <ESProtoFilePath>../EventStore.Client/Common/protos/$(PackageIdSuffix.ToLower()).proto</ESProtoFilePath>
+    </PropertyGroup>
+
+    <!-- Configure grpc services -->
+    <ItemGroup Condition="$(MSBuildProjectName) != 'EventStore.Client' And $(MSBuildProjectName) != 'EventStore.Client.Extensions.OpenTelemetry'">
+        <Protobuf Access="internal" Include="$(ESProtoFilePath)" GrpcServices="Client" Link="protos/%(FileName)%(Extension)" />
     </ItemGroup>
 
     <PropertyGroup>
@@ -26,14 +32,13 @@
         <Authors>Event Store Ltd</Authors>
         <Copyright>Copyright 2012-2020 Event Store Ltd</Copyright>
         <MinVerTagPrefix>v</MinVerTagPrefix>
-        <GenerateDocumentationFile>true</GenerateDocumentationFile>
     </PropertyGroup>
 
     <ItemGroup>
-        <None Include="..\..\LICENSE.md" Pack="true" PackagePath="\"/>
-        <None Include="..\..\ouro.png" Pack="true" PackagePath="\"/>
+        <None Include="..\..\LICENSE.md" Pack="true" PackagePath="\" />
+        <None Include="..\..\ouro.png" Pack="true" PackagePath="\" />
     </ItemGroup>
-
+    
     <ItemGroup>
         <PackageReference Include="ConfigureAwaitChecker.Analyzer" Version="4.0.0">
             <PrivateAssets>all</PrivateAssets>
@@ -43,22 +48,24 @@
             <PrivateAssets>all</PrivateAssets>
             <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
         </PackageReference>
-        <PackageReference Include="MinVer" Version="3.0.0" PrivateAssets="All"/>
+        <PackageReference Include="MinVer" Version="3.0.0" PrivateAssets="All" />
     </ItemGroup>
-
-    <ItemGroup>
-        <Compile Include="../EventStore.Client.Common/**/*.cs" Link="Common\%(RecursiveDir)/%(FileName)%(Extension)"/>
-    </ItemGroup>
-
+
     <ItemGroup>
-        <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
-            <_Parameter1>$(ProjectName).Tests</_Parameter1>
-        </AssemblyAttribute>
-        <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
-            <_Parameter1>$(ProjectName).Tests.Common</_Parameter1>
-        </AssemblyAttribute>
-        <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
-            <_Parameter1>EventStore.Client</_Parameter1>
-        </AssemblyAttribute>
+        <InternalsVisibleTo Include="$(ProjectName)" />
+        <InternalsVisibleTo Include="$(ProjectName).Operations" />
+        <InternalsVisibleTo Include="$(ProjectName).Operations.Tests" />
+        <InternalsVisibleTo Include="$(ProjectName).PersistentSubscriptions" />
+        <InternalsVisibleTo Include="$(ProjectName).PersistentSubscriptions.Tests" />
+        <InternalsVisibleTo Include="$(ProjectName).ProjectionManagement" />
+        <InternalsVisibleTo Include="$(ProjectName).ProjectionManagement.Tests" />
+        <InternalsVisibleTo Include="$(ProjectName).Streams" />
+        <InternalsVisibleTo Include="$(ProjectName).Streams.Tests" />
+        <InternalsVisibleTo Include="$(ProjectName).UserManagement" />
+        <InternalsVisibleTo Include="$(ProjectName).UserManagement.Tests" />
+        <InternalsVisibleTo Include="$(ProjectName).Extensions.OpenTelemetry" />
+        <InternalsVisibleTo Include="$(ProjectName).Tests" />
+        <InternalsVisibleTo Include="$(ProjectName).Common.Tests" />
+        <InternalsVisibleTo Include="$(ProjectName).Tests.Common" />
     </ItemGroup>
 </Project>
diff --git a/src/EventStore.Client.Common/Shims/TaskCompletionSource.cs b/src/EventStore.Client.Common/Shims/TaskCompletionSource.cs
diff --git a/...ntStore.Client.Extensions.OpenTelemetry/EventStore.Client.Extensions.OpenTelemetry.csproj b/...ntStore.Client.Extensions.OpenTelemetry/EventStore.Client.Extensions.OpenTelemetry.csproj
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project Sdk="Microsoft.NET.Sdk">
+	<PropertyGroup>
+		<RootNamespace>EventStore.Client.Extensions.OpenTelemetry</RootNamespace>
+	</PropertyGroup>
+
+	<PropertyGroup>
+		<PackageId>EventStore.Client.Extensions.OpenTelemetry</PackageId>
+		<Description>Extensions used to facilitate instrumentation of the EventStore Client.</Description>
+	</PropertyGroup>
+
+	<ItemGroup>
+	  <PackageReference Include="OpenTelemetry.Api" Version="1.8.0" />
+	</ItemGroup>
+
+</Project>
diff --git a/src/EventStore.Client.Extensions.OpenTelemetry/TracerProviderBuilderExtensions.cs b/src/EventStore.Client.Extensions.OpenTelemetry/TracerProviderBuilderExtensions.cs
@@ -0,0 +1,19 @@
+using EventStore.Client.Diagnostics;
+using JetBrains.Annotations;
+using OpenTelemetry.Trace;
+
+namespace EventStore.Client.Extensions.OpenTelemetry;
+
+/// <summary>
+/// Extension methods used to facilitate tracing instrumentation of the EventStore Client.
+/// </summary>
+[PublicAPI]
+public static class TracerProviderBuilderExtensions {
+    /// <summary>
+    /// Adds the EventStore client ActivitySource name to the list of subscribed sources on the <see cref="TracerProviderBuilder"/>
+    /// </summary>
+    /// <param name="builder"><see cref="TracerProviderBuilder"/> being configured.</param>
+    /// <returns>The instance of <see cref="TracerProviderBuilder"/> to chain configuration.</returns>
+    public static TracerProviderBuilder AddEventStoreClientInstrumentation(this TracerProviderBuilder builder) =>
+        builder.AddSource(EventStoreClientDiagnostics.InstrumentationName);
+}
diff --git a/...ventStore.Client.PersistentSubscriptions/EventStore.Client.PersistentSubscriptions.csproj b/...ventStore.Client.PersistentSubscriptions/EventStore.Client.PersistentSubscriptions.csproj
@@ -3,7 +3,4 @@
     <PropertyGroup>
         <Description>The GRPC client API for Event Store Persistent Subscriptions. Get the open source or commercial versions of Event Store server from https://eventstore.com/</Description>
     </PropertyGroup>
-    <ItemGroup>
-        <InternalsVisibleTo Include="EventStore.Client.PersistentSubscriptions.Tests"/>
-    </ItemGroup>
 </Project>