Document TraceLens setup (#2286)

Author: rogeralsing

Directory.Packages.props

@@ -64,6 +64,7 @@
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
     <PackageVersion Include="OpenTelemetry" Version="1.12.0" />
     <PackageVersion Include="OpenTelemetry.Api" Version="1.12.0" />
+    <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.12.0" />
     <PackageVersion Include="OpenTelemetry.Exporter.Jaeger" Version="1.5.1" />
     <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
     <PackageVersion Include="OpenTelemetry.Exporter.Prometheus" Version="1.3.0-rc.2" />

examples/actor.open-telemetry/ActorOpenTelemetry.csproj

@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <LangVersion>10</LangVersion>
+  </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Proto.OpenTelemetry\Proto.OpenTelemetry.csproj" />
+  </ItemGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Logging.Console" />
+    <PackageReference Include="OpenTelemetry" />
+    <PackageReference Include="OpenTelemetry.Exporter.Console" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
+  </ItemGroup>
+</Project>

examples/actor.open-telemetry/Program.cs

@@ -0,0 +1,55 @@
+using System;
+using System.Diagnostics;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+using OpenTelemetry;
+using OpenTelemetry.Metrics;
+using OpenTelemetry.Resources;
+using OpenTelemetry.Trace;
+using Proto;
+using Proto.OpenTelemetry;
+
+// Configure logging so Proto.Actor writes to the console
+var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole());
+Log.SetLoggerFactory(loggerFactory);
+
+// Export spans and metrics to the console and an OTLP collector (e.g., TraceLens)
+using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("ActorOpenTelemetrySample"))
+    .AddProtoActorInstrumentation()
+    .AddConsoleExporter()
+    .AddOtlpExporter()
+    .Build();
+
+using var meterProvider = Sdk.CreateMeterProviderBuilder()
+    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("ActorOpenTelemetrySample"))
+    .AddProtoActorInstrumentation()
+    .AddConsoleExporter()
+    .AddOtlpExporter()
+    .Build();
+
+var system = new ActorSystem(ActorSystemConfig.Setup().WithMetrics());
+
+// Simple actor that prints its trace id
+var props = Props.FromFunc(ctx =>
+{
+    if (ctx.Message is string msg)
+    {
+        Console.WriteLine($"[actor] received '{msg}' traceId={Activity.Current?.TraceId}");
+    }
+
+    return Task.CompletedTask;
+}).WithTracing();
+
+var pid = system.Root.Spawn(props);
+var tracedRoot = system.Root.WithTracing();
+
+using var rootActivity = new ActivitySource(Proto.ProtoTags.ActivitySourceName).StartActivity("root");
+tracedRoot.Send(pid, "hello");
+
+// Flush telemetry before exiting
+tracerProvider.ForceFlush();
+meterProvider.ForceFlush();
+
+Console.WriteLine("Press enter to exit");
+Console.ReadLine();

examples/actor.open-telemetry/README.md

@@ -0,0 +1,22 @@
+# Actor OpenTelemetry
+
+Demonstrates Proto.Actor tracing and metrics using OpenTelemetry with console exporters. The sample runs a single actor system and prints spans and counters directly to the console, so no external collector is required. It also sends telemetry to an OTLP collector on `localhost:4317`, which can be visualized with [TraceLens](https://tracelens.io).
+
+## Run
+
+```bash
+DOTNET_ReadyToRun=0 dotnet run --project examples/actor.open-telemetry
+```
+
+The program sends a message to an instrumented actor. The console output shows the trace identifier for the message and periodic dumps of Proto.Actor metrics.
+
+## Visualize with TraceLens
+
+Start TraceLens via Docker Compose to explore the emitted spans and counters:
+
+```bash
+curl -L https://raw.githubusercontent.com/asynkron/TraceLens/main/docker-compose.yml -o docker-compose.yml
+docker compose up
+```
+
+With TraceLens running, execute the example again. Open http://localhost:5001 to inspect traces and metrics.