Merge branch 'agents/dotnet-aspire-opentelemetry-explorer'

ARCHITECTURE.md

@@ -37,6 +37,7 @@ flowchart LR
     Git[Local git repositories]
     Sidecar[.NET sidecar]
     Copilot[GitHub Copilot CLI<br/>+ agent runtime]
+    Telemetry[OTLP collector<br/>Aspire Dashboard]
     OS[Native windowing<br/>and desktop integration]
 
     User --> Renderer
@@ -46,6 +47,7 @@ flowchart LR
     Main <--> Git
     Main <--> Sidecar
     Sidecar <--> Copilot
+    Sidecar --> Telemetry
     Main <--> OS
 ```
 
@@ -56,8 +58,8 @@ flowchart LR
 | Renderer | Screens, interaction, local view composition, theme application | Filesystem, process spawning, raw Electron access, Copilot runtime | Typed preload API and pushed events |
 | Preload | Narrow bridge between browser context and Electron IPC | Business logic, persistence, orchestration | `ipcRenderer` / `ipcMain` |
 | Main process | Workspace mutation, persistence, git inspection/write operations, run change attribution, commit workflow orchestration, session lifecycle, native window state, global hotkey registration, sidecar lifecycle, PTY-backed terminal lifecycle | UI rendering, LLM orchestration internals | IPC, filesystem, git CLI, stdio with sidecar, native child processes |
-| Sidecar | Capability discovery, workflow validation, run execution, provider event normalization, streaming deltas and activity, streamed text assembly | UI, workspace persistence, Electron APIs | Line-delimited JSON over stdio |
+| Sidecar | Capability discovery, workflow validation, run execution, provider event normalization, optional OTLP trace export, streaming deltas and activity, streamed text assembly | UI, workspace persistence, Electron APIs | Line-delimited JSON over stdio, OTLP to external collectors |
-| External systems | Git data, Copilot account/model access, OS window chrome | Application state and UI behavior | Controlled adapters owned by main or sidecar |
+| External systems | Git data, Copilot account/model access, telemetry collectors, OS window chrome | Application state and UI behavior | Controlled adapters owned by main or sidecar |
 
 This split is the most important architectural feature in the app. It is what keeps the system understandable as more capabilities are added.
 
@@ -68,7 +70,7 @@ Aryx runs as a multi-process desktop application:
 1. The **renderer** displays the workspace and captures user intent.
 2. The **preload bridge** exposes a small, typed API into the browser context.
 3. The **main process** validates and mutates application state, persists it, and manages native integrations.
-4. The **sidecar** executes Copilot-backed turns and streams structured execution events back.
+4. The **sidecar** executes Copilot-backed turns, can export OpenTelemetry traces to an external collector, and streams structured execution events back.
 
 The sidecar is intentionally separate from the Electron main process so that AI runtime concerns stay isolated from UI and persistence concerns.
 

README.md

@@ -92,6 +92,8 @@ bun run test           # typecheck + unit tests
 bun run sidecar:test   # backend tests
 bun run build          # full build (electron + sidecar)
 
+bun run aspire         # start the standalone Aspire Dashboard in Docker
+bun run dev:otel       # start Aspire + Aryx dev with OTLP export enabled
 bun run package        # package for current platform → release/
 bun run installer      # create installable artifact
 bun run publish-release # publish to GitHub Releases
@@ -99,6 +101,10 @@ bun run release        # bump patch version, commit, tag, and push
 bun run release minor  # bump minor version instead (use major for breaking releases)
 ```
 
+For local observability, `bun run dev:otel` starts the Aspire Dashboard UI at `http://localhost:18888`
+and configures the sidecar to export OpenTelemetry traces to `http://localhost:4317` over OTLP/gRPC.
+This dev workflow requires Docker.
+
 Tagged releases use GitHub Actions to build and publish Windows (NSIS), macOS (DMG, signed + notarized), and Linux (AppImage) artifacts. The app uses `electron-updater` for in-app updates.
 The release helper expects a clean git worktree, an upstream branch configured for the current branch, and permission to push commits and tags.
 

package.json

@@ -6,6 +6,8 @@
   "main": "dist-electron/main/index.js",
   "scripts": {
     "dev": "electron-vite dev",
+    "dev:otel": "bun run scripts/dev-with-otel.ts",
+    "aspire": "bun run scripts/launch-aspire-dashboard.ts",
     "build:electron": "electron-vite build",
     "build": "bun run build:electron && bun run sidecar:build",
     "package": "bun run scripts/clean-release.ts && bun run build:electron && bun run sidecar:publish && electron-builder --dir --publish never",

scripts/aspireDashboard.ts

@@ -0,0 +1,233 @@
+import { spawn } from 'node:child_process';
+import net from 'node:net';
+import { setTimeout as delay } from 'node:timers/promises';
+
+export const aspireDashboardContainerName = 'aryx-aspire-dashboard';
+export const aspireDashboardImage = 'mcr.microsoft.com/dotnet/aspire-dashboard:latest';
+export const aspireDashboardUrls = {
+  dashboard: 'http://localhost:18888',
+  otlpGrpc: 'http://localhost:4317',
+  otlpHttp: 'http://localhost:4318',
+} as const;
+
+type ContainerState = 'missing' | 'running' | 'stopped';
+
+export interface AspireDashboardHandle {
+  readonly dashboardUrl: string;
+  readonly otlpGrpcEndpoint: string;
+  readonly otlpHttpEndpoint: string;
+  readonly startedByScript: boolean;
+}
+
+export function createAspireDashboardRunArgs(
+  containerName = aspireDashboardContainerName,
+  image = aspireDashboardImage,
+): string[] {
+  return [
+    'run',
+    '--rm',
+    '-d',
+    '--name',
+    containerName,
+    '-p',
+    '18888:18888',
+    '-p',
+    '4317:18889',
+    '-p',
+    '4318:18890',
+    '-e',
+    'ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS=true',
+    image,
+  ];
+}
+
+export function createOpenTelemetryEnvironment(
+  baseEnvironment: NodeJS.ProcessEnv,
+  endpoint: string = aspireDashboardUrls.otlpGrpc,
+): NodeJS.ProcessEnv {
+  return {
+    ...baseEnvironment,
+    OTEL_EXPORTER_OTLP_ENDPOINT: endpoint,
+    OTEL_EXPORTER_OTLP_PROTOCOL: 'grpc',
+  };
+}
+
+export async function startAspireDashboard(): Promise<AspireDashboardHandle> {
+  await ensureDockerAvailable();
+
+  let startedByScript = false;
+  const containerState = await getContainerState(aspireDashboardContainerName);
+  if (containerState !== 'running') {
+    if (containerState === 'stopped') {
+      await runCommand('docker', ['rm', '-f', aspireDashboardContainerName], 'pipe');
+    }
+
+    await runCommand('docker', createAspireDashboardRunArgs(), 'pipe');
+    startedByScript = true;
+  }
+
+  await waitForTcpPort(18888);
+  await waitForTcpPort(4317);
+
+  return {
+    dashboardUrl: aspireDashboardUrls.dashboard,
+    otlpGrpcEndpoint: aspireDashboardUrls.otlpGrpc,
+    otlpHttpEndpoint: aspireDashboardUrls.otlpHttp,
+    startedByScript,
+  };
+}
+
+export async function stopAspireDashboard(): Promise<void> {
+  const containerState = await getContainerState(aspireDashboardContainerName);
+  if (containerState === 'missing') {
+    return;
+  }
+
+  await runCommand('docker', ['rm', '-f', aspireDashboardContainerName], 'pipe');
+}
+
+async function ensureDockerAvailable(): Promise<void> {
+  const cliVersion = await runCommandCapture('docker', ['--version']);
+  if (cliVersion.exitCode !== 0) {
+    throw new Error(
+      'Docker is required to run the standalone Aspire Dashboard. Install Docker Desktop and ensure `docker` is available on PATH.',
+    );
+  }
+
+  if (await isDockerDaemonAvailable()) {
+    return;
+  }
+
+  if (await hasDockerDesktopCli()) {
+    console.log('Docker Desktop is not running. Starting it now...');
+    await runCommand('docker', ['desktop', 'start', '--detach'], 'pipe');
+    await waitForDockerDaemon();
+    return;
+  }
+
+  throw new Error(
+    'Docker is installed but the daemon is not running. Start Docker Desktop and rerun the Aspire command.',
+  );
+}
+
+async function getContainerState(containerName: string): Promise<ContainerState> {
+  const result = await runCommandCapture('docker', [
+    'container',
+    'inspect',
+    '--format',
+    '{{.State.Status}}',
+    containerName,
+  ]);
+
+  if (result.exitCode !== 0) {
+    return 'missing';
+  }
+
+  return result.stdout.trim() === 'running' ? 'running' : 'stopped';
+}
+
+async function waitForTcpPort(port: number, timeoutMs = 30_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await canConnect(port)) {
+      return;
+    }
+
+    await delay(250);
+  }
+
+  throw new Error(`Timed out waiting for localhost:${port} to accept connections.`);
+}
+
+async function isDockerDaemonAvailable(): Promise<boolean> {
+  const result = await runCommandCapture('docker', ['info', '--format', '{{.ServerVersion}}']);
+  return result.exitCode === 0;
+}
+
+async function hasDockerDesktopCli(): Promise<boolean> {
+  const result = await runCommandCapture('docker', ['desktop', 'version']);
+  return result.exitCode === 0;
+}
+
+async function waitForDockerDaemon(timeoutMs = 120_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isDockerDaemonAvailable()) {
+      return;
+    }
+
+    await delay(1_000);
+  }
+
+  throw new Error('Timed out waiting for Docker Desktop to start and accept API connections.');
+}
+
+async function canConnect(port: number): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    const socket = net.createConnection({ host: '127.0.0.1', port });
+    const finalize = (connected: boolean) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(connected);
+    };
+
+    socket.once('connect', () => finalize(true));
+    socket.once('error', () => finalize(false));
+  });
+}
+
+async function runCommand(command: string, args: string[], stdio: 'inherit' | 'pipe'): Promise<void> {
+  const result = await spawnProcess(command, args, stdio);
+  if (result.exitCode === 0) {
+    return;
+  }
+
+  if (result.stderr.trim().length > 0) {
+    throw new Error(result.stderr.trim());
+  }
+
+  throw new Error(`${command} exited with code ${result.exitCode}.`);
+}
+
+async function runCommandCapture(command: string, args: string[]): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  return spawnProcess(command, args, 'pipe');
+}
+
+async function spawnProcess(
+  command: string,
+  args: string[],
+  stdio: 'inherit' | 'pipe',
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: stdio === 'inherit' ? 'inherit' : ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    if (stdio === 'pipe') {
+      child.stdout?.on('data', (chunk: Buffer | string) => {
+        stdout += chunk.toString();
+      });
+      child.stderr?.on('data', (chunk: Buffer | string) => {
+        stderr += chunk.toString();
+      });
+    }
+
+    child.on('error', reject);
+    child.on('exit', (code, signal) => {
+      if (signal) {
+        reject(new Error(`${command} exited because of signal ${signal}.`));
+        return;
+      }
+
+      resolve({
+        exitCode: code ?? 1,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}

scripts/dev-with-otel.ts

@@ -0,0 +1,57 @@
+import { spawn } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  createOpenTelemetryEnvironment,
+  startAspireDashboard,
+  stopAspireDashboard,
+} from './aspireDashboard';
+
+const scriptDirectory = dirname(fileURLToPath(import.meta.url));
+const repositoryRoot = resolve(scriptDirectory, '..');
+const signalExitCodes: Partial<Record<NodeJS.Signals, number>> = {
+  SIGINT: 130,
+  SIGTERM: 143,
+};
+
+const dashboard = await startAspireDashboard();
+
+console.log(`Aspire Dashboard: ${dashboard.dashboardUrl}`);
+console.log(`Aryx sidecar OTLP endpoint: ${dashboard.otlpGrpcEndpoint}`);
+
+const child = spawn(process.execPath, ['run', 'dev'], {
+  cwd: repositoryRoot,
+  env: createOpenTelemetryEnvironment(process.env, dashboard.otlpGrpcEndpoint),
+  stdio: 'inherit',
+  windowsHide: true,
+});
+
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+  process.on(signal, () => {
+    if (child.exitCode === null && child.signalCode === null) {
+      child.kill(signal);
+    }
+  });
+}
+
+let exitResult: { code: number | null; signal: NodeJS.Signals | null };
+
+try {
+  exitResult = await new Promise((resolve, reject) => {
+    child.on('error', reject);
+    child.on('exit', (code, signal) => {
+      resolve({ code, signal });
+    });
+  });
+} finally {
+  if (dashboard.startedByScript) {
+    await stopAspireDashboard();
+  }
+}
+
+if (exitResult.signal) {
+  process.exitCode = signalExitCodes[exitResult.signal] ?? 1;
+} else {
+  process.exitCode = exitResult.code ?? 1;
+}

scripts/launch-aspire-dashboard.ts

@@ -0,0 +1,9 @@
+import { startAspireDashboard } from './aspireDashboard';
+
+const dashboard = await startAspireDashboard();
+
+console.log(
+  `${dashboard.startedByScript ? 'Started' : 'Reusing'} Aspire Dashboard at ${dashboard.dashboardUrl}`,
+);
+console.log(`OTLP/gRPC receiver: ${dashboard.otlpGrpcEndpoint}`);
+console.log(`OTLP/HTTP receiver: ${dashboard.otlpHttpEndpoint}`);

sidecar/src/Aryx.AgentHost/Aryx.AgentHost.csproj

@@ -13,6 +13,8 @@
     <PackageReference Include="Microsoft.Agents.AI" Version="1.1.0" />
     <PackageReference Include="Microsoft.Agents.AI.GitHub.Copilot" Version="1.1.0-preview.260410.1" />
     <PackageReference Include="Microsoft.Agents.AI.Workflows" Version="1.1.0" />
+    <PackageReference Include="OpenTelemetry" Version="1.13.1" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.13.1" />
   </ItemGroup>
 
 </Project>

sidecar/src/Aryx.AgentHost/Program.cs

@@ -1,4 +1,5 @@
 using Aryx.AgentHost.Services;
+using OpenTelemetry.Trace;
 
 if (!args.Contains("--stdio", StringComparer.Ordinal))
 {
@@ -6,5 +7,7 @@ if (!args.Contains("--stdio", StringComparer.Ordinal))
     return;
 }
 
+using TracerProvider? tracerProvider = OpenTelemetrySetup.CreateTracerProviderFromEnvironment();
+
 SidecarProtocolHost host = new();
 await host.RunAsync(Console.In, Console.Out, CancellationToken.None);

sidecar/src/Aryx.AgentHost/Services/OpenTelemetrySetup.cs

@@ -0,0 +1,137 @@
+using System.Collections;
+using OpenTelemetry;
+using OpenTelemetry.Exporter;
+using OpenTelemetry.Resources;
+using OpenTelemetry.Trace;
+
+namespace Aryx.AgentHost.Services;
+
+internal static class OpenTelemetrySetup
+{
+    private const string ServiceName = "Aryx.AgentHost";
+    private const string EndpointEnvironmentVariableName = "OTEL_EXPORTER_OTLP_ENDPOINT";
+    private const string ProtocolEnvironmentVariableName = "OTEL_EXPORTER_OTLP_PROTOCOL";
+
+    private static readonly string[] ActivitySourceNames =
+    [
+        "Microsoft.Agents.AI",
+        "Microsoft.Agents.AI.Workflows",
+    ];
+
+    public static TracerProvider? CreateTracerProviderFromEnvironment(TextWriter? diagnosticsWriter = null)
+    {
+        return CreateTracerProvider(ReadEnvironmentVariables(), diagnosticsWriter ?? Console.Error);
+    }
+
+    internal static TracerProvider? CreateTracerProvider(
+        IEnumerable<KeyValuePair<string, string?>> environmentVariables,
+        TextWriter diagnosticsWriter)
+    {
+        ArgumentNullException.ThrowIfNull(environmentVariables);
+        ArgumentNullException.ThrowIfNull(diagnosticsWriter);
+
+        OpenTelemetryTracingConfiguration? configuration = ResolveTracingConfiguration(environmentVariables);
+        if (configuration is null)
+        {
+            return null;
+        }
+
+        diagnosticsWriter.WriteLine(
+            $"Aryx.AgentHost OpenTelemetry tracing enabled ({configuration.ProtocolLabel}) -> {configuration.Endpoint}.");
+
+        return Sdk.CreateTracerProviderBuilder()
+            .SetResourceBuilder(
+                ResourceBuilder.CreateDefault()
+                    .AddService(ServiceName, serviceVersion: ResolveServiceVersion()))
+            .AddSource(configuration.ActivitySourceNames.ToArray())
+            .AddOtlpExporter(options =>
+            {
+                options.Endpoint = configuration.Endpoint;
+                options.Protocol = configuration.Protocol;
+            })
+            .Build();
+    }
+
+    internal static OpenTelemetryTracingConfiguration? ResolveTracingConfiguration(
+        IEnumerable<KeyValuePair<string, string?>> environmentVariables)
+    {
+        ArgumentNullException.ThrowIfNull(environmentVariables);
+
+        string? endpointValue = ReadSetting(environmentVariables, EndpointEnvironmentVariableName);
+        if (string.IsNullOrWhiteSpace(endpointValue))
+        {
+            return null;
+        }
+
+        if (!Uri.TryCreate(endpointValue, UriKind.Absolute, out Uri? endpoint)
+            || (endpoint.Scheme != Uri.UriSchemeHttp && endpoint.Scheme != Uri.UriSchemeHttps))
+        {
+            throw new InvalidOperationException(
+                $"{EndpointEnvironmentVariableName} must be an absolute http or https URL. Received '{endpointValue}'.");
+        }
+
+        OtlpExportProtocol protocol = ResolveProtocol(ReadSetting(environmentVariables, ProtocolEnvironmentVariableName));
+        return new OpenTelemetryTracingConfiguration(endpoint, protocol, ActivitySourceNames);
+    }
+
+    private static string? ResolveServiceVersion()
+    {
+        return typeof(OpenTelemetrySetup).Assembly.GetName().Version?.ToString();
+    }
+
+    private static IEnumerable<KeyValuePair<string, string?>> ReadEnvironmentVariables()
+    {
+        return Environment.GetEnvironmentVariables()
+            .Cast<DictionaryEntry>()
+            .Select(entry => new KeyValuePair<string, string?>(
+                entry.Key?.ToString() ?? string.Empty,
+                entry.Value?.ToString()));
+    }
+
+    private static string? ReadSetting(
+        IEnumerable<KeyValuePair<string, string?>> environmentVariables,
+        string name)
+    {
+        foreach (KeyValuePair<string, string?> entry in environmentVariables)
+        {
+            if (!string.Equals(entry.Key, name, StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            return string.IsNullOrWhiteSpace(entry.Value)
+                ? null
+                : entry.Value.Trim();
+        }
+
+        return null;
+    }
+
+    private static OtlpExportProtocol ResolveProtocol(string? protocolValue)
+    {
+        if (string.IsNullOrWhiteSpace(protocolValue))
+        {
+            return OtlpExportProtocol.Grpc;
+        }
+
+        return protocolValue.Trim().ToLowerInvariant() switch
+        {
+            "grpc" => OtlpExportProtocol.Grpc,
+            "http/protobuf" => OtlpExportProtocol.HttpProtobuf,
+            _ => throw new InvalidOperationException(
+                $"{ProtocolEnvironmentVariableName} must be 'grpc' or 'http/protobuf'. Received '{protocolValue}'."),
+        };
+    }
+}
+
+internal sealed record OpenTelemetryTracingConfiguration(
+    Uri Endpoint,
+    OtlpExportProtocol Protocol,
+    IReadOnlyList<string> ActivitySourceNames)
+{
+    public string ProtocolLabel => Protocol switch
+    {
+        OtlpExportProtocol.HttpProtobuf => "http/protobuf",
+        _ => "grpc",
+    };
+}

sidecar/tests/Aryx.AgentHost.Tests/OpenTelemetrySetupTests.cs

@@ -0,0 +1,87 @@
+using Aryx.AgentHost.Services;
+using OpenTelemetry.Exporter;
+using OpenTelemetry.Trace;
+
+namespace Aryx.AgentHost.Tests;
+
+public sealed class OpenTelemetrySetupTests
+{
+    [Fact]
+    public void ResolveTracingConfiguration_ReturnsNullWhenEndpointMissing()
+    {
+        OpenTelemetryTracingConfiguration? configuration = OpenTelemetrySetup.ResolveTracingConfiguration([]);
+
+        Assert.Null(configuration);
+    }
+
+    [Fact]
+    public void ResolveTracingConfiguration_UsesGrpcByDefault()
+    {
+        OpenTelemetryTracingConfiguration? configuration = OpenTelemetrySetup.ResolveTracingConfiguration(
+        [
+            new KeyValuePair<string, string?>("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317"),
+        ]);
+
+        Assert.NotNull(configuration);
+        Assert.Equal(new Uri("http://localhost:4317"), configuration.Endpoint);
+        Assert.Equal(OtlpExportProtocol.Grpc, configuration.Protocol);
+        Assert.Collection(
+            configuration.ActivitySourceNames,
+            source => Assert.Equal("Microsoft.Agents.AI", source),
+            source => Assert.Equal("Microsoft.Agents.AI.Workflows", source));
+    }
+
+    [Fact]
+    public void ResolveTracingConfiguration_UsesHttpProtobufWhenRequested()
+    {
+        OpenTelemetryTracingConfiguration? configuration = OpenTelemetrySetup.ResolveTracingConfiguration(
+        [
+            new KeyValuePair<string, string?>("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4318"),
+            new KeyValuePair<string, string?>("OTEL_EXPORTER_OTLP_PROTOCOL", "http/protobuf"),
+        ]);
+
+        Assert.NotNull(configuration);
+        Assert.Equal(new Uri("http://localhost:4318"), configuration.Endpoint);
+        Assert.Equal(OtlpExportProtocol.HttpProtobuf, configuration.Protocol);
+    }
+
+    [Fact]
+    public void ResolveTracingConfiguration_ThrowsWhenEndpointInvalid()
+    {
+        InvalidOperationException error = Assert.Throws<InvalidOperationException>(() =>
+            OpenTelemetrySetup.ResolveTracingConfiguration(
+            [
+                new KeyValuePair<string, string?>("OTEL_EXPORTER_OTLP_ENDPOINT", "localhost:4317"),
+            ]));
+
+        Assert.Contains("OTEL_EXPORTER_OTLP_ENDPOINT", error.Message, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void ResolveTracingConfiguration_ThrowsWhenProtocolUnsupported()
+    {
+        InvalidOperationException error = Assert.Throws<InvalidOperationException>(() =>
+            OpenTelemetrySetup.ResolveTracingConfiguration(
+            [
+                new KeyValuePair<string, string?>("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317"),
+                new KeyValuePair<string, string?>("OTEL_EXPORTER_OTLP_PROTOCOL", "http/json"),
+            ]));
+
+        Assert.Contains("OTEL_EXPORTER_OTLP_PROTOCOL", error.Message, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void CreateTracerProvider_CreatesProviderAndWritesDiagnosticsWhenConfigured()
+    {
+        StringWriter diagnosticsWriter = new();
+
+        using TracerProvider? tracerProvider = OpenTelemetrySetup.CreateTracerProvider(
+        [
+            new KeyValuePair<string, string?>("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317"),
+        ],
+        diagnosticsWriter);
+
+        Assert.NotNull(tracerProvider);
+        Assert.Contains("Aryx.AgentHost OpenTelemetry tracing enabled", diagnosticsWriter.ToString(), StringComparison.Ordinal);
+    }
+}

src/main/AryxAppService.ts

@@ -140,6 +140,7 @@ import {
   type AppearanceTheme,
   type LspProfileDefinition,
   type McpServerDefinition,
+  type OpenTelemetrySettings,
   type QuickPromptSettings,
   type SessionToolingSelection,
   type WorkspaceToolingSettings,
@@ -469,6 +470,7 @@ export class AryxAppService extends EventEmitter<AppServiceEvents> {
   async loadWorkspace(): Promise<WorkspaceState> {
     if (!this.workspace) {
       this.workspace = await this.workspaceRepository.load();
+      this.sidecar.setOpenTelemetrySettings(this.workspace.settings.openTelemetry);
       const selectedProjectId = this.workspace.selectedProjectId;
       const selectedProject = selectedProjectId
         ? this.workspace.projects.find((project) => project.id === selectedProjectId)
@@ -830,6 +832,13 @@ export class AryxAppService extends EventEmitter<AppServiceEvents> {
     return this.persistAndBroadcast(workspace);
   }
 
+  async setOpenTelemetry(settings: OpenTelemetrySettings): Promise<WorkspaceState> {
+    const workspace = await this.loadWorkspace();
+    workspace.settings.openTelemetry = settings;
+    this.sidecar.setOpenTelemetrySettings(settings);
+    return this.persistAndBroadcast(workspace);
+  }
+
   getQuickPromptSettings(): QuickPromptSettings {
     return this.workspace?.settings.quickPrompt ?? createDefaultQuickPromptSettings();
   }

src/main/ipc/registerIpcHandlers.ts

@@ -56,7 +56,7 @@ import type {
   QuickPromptSendInput,
 } from '@shared/contracts/ipc';
 import type { QuerySessionsInput } from '@shared/domain/sessionLibrary';
-import type { AppearanceTheme, QuickPromptSettings } from '@shared/domain/tooling';
+import type { AppearanceTheme, OpenTelemetrySettings, QuickPromptSettings } from '@shared/domain/tooling';
 
 import { AryxAppService } from '@main/AryxAppService';
 import { AutoUpdateService } from '@main/services/autoUpdater';
@@ -155,6 +155,10 @@ export function registerIpcHandlers(
     ipcChannels.setGitAutoRefreshEnabled,
     (_event, enabled: boolean) => service.setGitAutoRefreshEnabled(enabled),
   );
+  ipcMain.handle(
+    ipcChannels.setOpenTelemetry,
+    (_event, settings: OpenTelemetrySettings) => service.setOpenTelemetry(settings),
+  );
   ipcMain.handle(ipcChannels.checkForUpdates, () => autoUpdateService.checkForUpdates());
   ipcMain.handle(ipcChannels.installUpdate, () => {
     autoUpdateService.installUpdate();

src/main/sidecar/sidecarEnvironment.ts

@@ -1,6 +1,11 @@
+import type { OpenTelemetrySettings } from '@shared/domain/tooling';
+
 const blockedEnvironmentPrefixes = ['BUN_', 'COPILOT_', 'ELECTRON_', 'NODE_', 'NPM_'];
 
-export function createSidecarEnvironment(baseEnvironment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+export function createSidecarEnvironment(
+  baseEnvironment: NodeJS.ProcessEnv,
+  openTelemetry?: OpenTelemetrySettings,
+): NodeJS.ProcessEnv {
   const sanitizedEnvironment: NodeJS.ProcessEnv = {};
 
   for (const [name, value] of Object.entries(baseEnvironment)) {
@@ -13,5 +18,9 @@ export function createSidecarEnvironment(baseEnvironment: NodeJS.ProcessEnv): No
     sanitizedEnvironment[name] = value;
   }
 
+  if (openTelemetry?.enabled && openTelemetry.endpoint) {
+    sanitizedEnvironment.OTEL_EXPORTER_OTLP_ENDPOINT = openTelemetry.endpoint;
+  }
+
   return sanitizedEnvironment;
 }

src/main/sidecar/sidecarProcess.ts

@@ -21,6 +21,7 @@ import type {
 } from '@shared/contracts/sidecar';
 import type { ApprovalDecision } from '@shared/domain/approval';
 import type { ChatMessageRecord } from '@shared/domain/session';
+import type { OpenTelemetrySettings } from '@shared/domain/tooling';
 import { createSidecarEnvironment } from '@main/sidecar/sidecarEnvironment';
 import {
   markRunTurnPendingErrored,
@@ -109,6 +110,11 @@ export class SidecarClient {
   private processState?: ManagedSidecarProcess;
   private nextProcessId = 0;
   private readonly pending = new Map<string, PendingCommand>();
+  private openTelemetrySettings?: OpenTelemetrySettings;
+
+  setOpenTelemetrySettings(settings?: OpenTelemetrySettings): void {
+    this.openTelemetrySettings = settings;
+  }
 
   async describeCapabilities(): Promise<SidecarCapabilities> {
     const command = await this.dispatch<SidecarCapabilities>({
@@ -240,7 +246,7 @@ export class SidecarClient {
     });
     const childProcess = spawn(sidecar.command, sidecar.args, {
       cwd: sidecar.cwd,
-      env: createSidecarEnvironment(process.env),
+      env: createSidecarEnvironment(process.env, this.openTelemetrySettings),
       stdio: 'pipe',
       windowsHide: true,
     });

src/preload/index.ts

@@ -36,6 +36,7 @@ const api: ElectronApi = {
   setNotificationsEnabled: (enabled) => ipcRenderer.invoke(ipcChannels.setNotificationsEnabled, enabled),
   setMinimizeToTray: (enabled) => ipcRenderer.invoke(ipcChannels.setMinimizeToTray, enabled),
   setGitAutoRefreshEnabled: (enabled) => ipcRenderer.invoke(ipcChannels.setGitAutoRefreshEnabled, enabled),
+  setOpenTelemetry: (settings) => ipcRenderer.invoke(ipcChannels.setOpenTelemetry, settings),
   getQuickPromptSettings: () => ipcRenderer.invoke(ipcChannels.quickPromptGetSettings),
   setQuickPromptSettings: (settings) => ipcRenderer.invoke(ipcChannels.quickPromptSetSettings, settings),
   checkForUpdates: () => ipcRenderer.invoke(ipcChannels.checkForUpdates),

src/renderer/App.tsx

@@ -873,6 +873,8 @@ export default function App() {
           setQuickPromptSettings(updated);
           void api.setQuickPromptSettings(patch);
         }}
+        openTelemetry={workspace.settings.openTelemetry}
+        onSetOpenTelemetry={(settings) => void api.setOpenTelemetry(settings)}
       />
     </Suspense>
   ) : null;

src/renderer/components/SettingsPanel.tsx

@@ -1,9 +1,9 @@
 import { useEffect, useState, type ReactNode } from 'react';
-import { ChevronLeft, ChevronRight, CircleCheck, Code, Cpu, FolderOpen, GitBranch, Palette, Plus, RefreshCw, Server, Sparkles, TriangleAlert, UserCircle, Wrench } from 'lucide-react';
+import { ChevronLeft, ChevronRight, CircleCheck, Code, Cpu, FolderOpen, GitBranch, Palette, Plus, RefreshCw, Server, Sparkles, TriangleAlert, UserCircle, Wrench, Activity } from 'lucide-react';
 
 import { CopilotStatusCard } from '@renderer/components/CopilotStatusCard';
 import { WorkflowEditor } from '@renderer/components/WorkflowEditor';
-import { HotkeyRecorder, ToggleSwitch } from '@renderer/components/ui';
+import { HotkeyRecorder, TextInput, ToggleSwitch } from '@renderer/components/ui';
 import { LspProfileEditor } from '@renderer/components/settings/LspProfileEditor';
 import { McpServerEditor } from '@renderer/components/settings/McpServerEditor';
 import { WorkspaceAgentEditor } from '@renderer/components/settings/WorkspaceAgentEditor';
@@ -18,9 +18,11 @@ import type { WorkflowTemplateCategory, WorkflowTemplateDefinition } from '@shar
 import {
   normalizeLspProfileDefinition,
   normalizeMcpServerDefinition,
+  DEFAULT_OTEL_ENDPOINT,
   type AppearanceTheme,
   type LspProfileDefinition,
   type McpServerDefinition,
+  type OpenTelemetrySettings,
   type QuickPromptSettings,
   type WorkspaceToolingSettings,
 } from '@shared/domain/tooling';
@@ -65,9 +67,11 @@ interface SettingsPanelProps {
   onCreateWorkflowFromTemplate?: (templateId: string, name?: string) => Promise<void>;
   quickPromptSettings?: QuickPromptSettings;
   onSetQuickPromptSettings?: (patch: Partial<QuickPromptSettings>) => void;
+  openTelemetry?: OpenTelemetrySettings;
+  onSetOpenTelemetry?: (settings: OpenTelemetrySettings) => void;
 }
 
-export type SettingsSection = 'appearance' | 'connection' | 'workflows' | 'agents' | 'mcp-servers' | 'lsp-profiles' | 'quick-prompt' | 'troubleshooting';
+export type SettingsSection = 'appearance' | 'connection' | 'workflows' | 'agents' | 'mcp-servers' | 'lsp-profiles' | 'quick-prompt' | 'telemetry' | 'troubleshooting';
 
 interface NavItem {
   id: SettingsSection;
@@ -86,6 +90,7 @@ const navGroups: NavGroup[] = [
     items: [
       { id: 'appearance', label: 'Appearance', icon: <Palette className="size-3.5" /> },
       { id: 'quick-prompt', label: 'Quick Prompt', icon: <Sparkles className="size-3.5" /> },
+      { id: 'telemetry', label: 'Telemetry', icon: <Activity className="size-3.5" /> },
     ],
   },
   {
@@ -155,6 +160,8 @@ export function SettingsPanel({
   onCreateWorkflowFromTemplate,
   quickPromptSettings,
   onSetQuickPromptSettings,
+  openTelemetry,
+  onSetOpenTelemetry,
 }: SettingsPanelProps) {
   const [activeSection, setActiveSection] = useState<SettingsSection>(initialSection ?? 'appearance');
   const [editingWorkflow, setEditingWorkflow] = useState<WorkflowDefinition | null>(null);
@@ -394,6 +401,12 @@ export function SettingsPanel({
                 onUpdate={onSetQuickPromptSettings}
               />
             )}
+            {activeSection === 'telemetry' && (
+              <TelemetrySection
+                openTelemetry={openTelemetry}
+                onSetOpenTelemetry={onSetOpenTelemetry}
+              />
+            )}
             {activeSection === 'troubleshooting' && (
               <TroubleshootingSection
                 onOpenAppDataFolder={onOpenAppDataFolder}
@@ -548,6 +561,67 @@ function AppearanceSection({
   );
 }
 
+function TelemetrySection({
+  openTelemetry,
+  onSetOpenTelemetry,
+}: {
+  openTelemetry?: OpenTelemetrySettings;
+  onSetOpenTelemetry?: (settings: OpenTelemetrySettings) => void;
+}) {
+  const enabled = openTelemetry?.enabled ?? false;
+  const endpoint = openTelemetry?.endpoint ?? DEFAULT_OTEL_ENDPOINT;
+
+  const handleToggle = () => {
+    onSetOpenTelemetry?.({ enabled: !enabled, endpoint });
+  };
+
+  const handleEndpointChange = (value: string) => {
+    onSetOpenTelemetry?.({ enabled, endpoint: value });
+  };
+
+  return (
+    <div>
+      <div className="mb-1">
+        <h3 className="font-display text-[13px] font-semibold text-[var(--color-text-primary)]">OpenTelemetry</h3>
+        <p className="mt-0.5 text-[12px] text-[var(--color-text-muted)]">
+          Export traces from the sidecar to an OTLP-compatible collector
+        </p>
+      </div>
+
+      <button
+        className="mt-4 flex w-full items-center justify-between rounded-lg border border-[var(--color-border)] px-4 py-3 text-left transition hover:bg-[var(--color-surface-3)]/40"
+        onClick={handleToggle}
+        type="button"
+      >
+        <div>
+          <span className="text-[13px] font-medium text-[var(--color-text-primary)]">
+            Enable OTLP export
+          </span>
+          <p className="text-[12px] text-[var(--color-text-muted)]">
+            Send traces to the configured OTLP endpoint when a new sidecar session starts
+          </p>
+        </div>
+        <ToggleSwitch enabled={enabled} />
+      </button>
+
+      <div className="mt-5">
+        <label className="mb-1.5 block text-[12px] font-medium text-[var(--color-text-secondary)]">
+          OTLP endpoint
+        </label>
+        <TextInput
+          value={endpoint}
+          onChange={handleEndpointChange}
+          placeholder={DEFAULT_OTEL_ENDPOINT}
+        />
+        <p className="mt-1.5 text-[11px] text-[var(--color-text-muted)]">
+          Use <span className="font-mono">bun run aspire</span> to launch the Aspire Dashboard locally at this default endpoint.
+          Changes take effect on the next sidecar session.
+        </p>
+      </div>
+    </div>
+  );
+}
+
 function ConnectionSection({
   connection,
   modelCount,

src/shared/contracts/channels.ts

@@ -25,6 +25,7 @@ export const ipcChannels = {
   setNotificationsEnabled: 'settings:set-notifications-enabled',
   setMinimizeToTray: 'settings:set-minimize-to-tray',
   setGitAutoRefreshEnabled: 'settings:set-git-auto-refresh-enabled',
+  setOpenTelemetry: 'settings:set-opentelemetry',
   checkForUpdates: 'app:check-for-updates',
   installUpdate: 'app:install-update',
   saveMcpServer: 'tooling:mcp:save',

src/shared/contracts/ipc.ts

@@ -20,6 +20,7 @@ import type {
   SessionToolingSelection,
   AppearanceTheme,
   QuickPromptSettings,
+  OpenTelemetrySettings,
 } from '@shared/domain/tooling';
 import type { WorkspaceState } from '@shared/domain/workspace';
 import type { ChatMessageAttachment } from '@shared/domain/attachment';
@@ -364,6 +365,7 @@ export interface ElectronApi {
   setNotificationsEnabled(enabled: boolean): Promise<WorkspaceState>;
   setMinimizeToTray(enabled: boolean): Promise<WorkspaceState>;
   setGitAutoRefreshEnabled(enabled: boolean): Promise<WorkspaceState>;
+  setOpenTelemetry(settings: OpenTelemetrySettings): Promise<WorkspaceState>;
   checkForUpdates(): Promise<UpdateStatus>;
   installUpdate(): Promise<void>;
   describeTerminal(): Promise<TerminalSnapshot | undefined>;

src/shared/domain/tooling.ts

@@ -68,6 +68,13 @@ export interface QuickPromptSettings {
   defaultReasoningEffort?: 'low' | 'medium' | 'high' | 'xhigh';
 }
 
+export interface OpenTelemetrySettings {
+  enabled: boolean;
+  endpoint: string;
+}
+
+export const DEFAULT_OTEL_ENDPOINT = 'http://localhost:4317';
+
 export function createDefaultQuickPromptSettings(): QuickPromptSettings {
   return {
     enabled: true,
@@ -85,6 +92,7 @@ export interface WorkspaceSettings {
   minimizeToTray?: boolean;
   gitAutoRefreshEnabled?: boolean;
   quickPrompt?: QuickPromptSettings;
+  openTelemetry?: OpenTelemetrySettings;
 }
 
 export interface SessionToolingSelection {
@@ -231,6 +239,16 @@ export function normalizeWorkspaceSettings(settings?: Partial<WorkspaceSettings>
     ...(settings?.minimizeToTray !== undefined ? { minimizeToTray: settings.minimizeToTray } : {}),
     ...(settings?.gitAutoRefreshEnabled !== undefined ? { gitAutoRefreshEnabled: settings.gitAutoRefreshEnabled } : {}),
     ...(settings?.quickPrompt !== undefined ? { quickPrompt: settings.quickPrompt } : {}),
+    ...(settings?.openTelemetry !== undefined ? { openTelemetry: normalizeOpenTelemetrySettings(settings.openTelemetry) } : {}),
+  };
+}
+
+export function normalizeOpenTelemetrySettings(settings?: Partial<OpenTelemetrySettings>): OpenTelemetrySettings {
+  return {
+    enabled: settings?.enabled === true,
+    endpoint: typeof settings?.endpoint === 'string' && settings.endpoint.trim() !== ''
+      ? settings.endpoint.trim()
+      : DEFAULT_OTEL_ENDPOINT,
   };
 }
 

tests/main/sidecarEnvironment.test.ts

@@ -37,4 +37,46 @@ describe('createSidecarEnvironment', () => {
       HTTPS_PROXY: 'http://proxy.local:8080',
     });
   });
+
+  test('injects OTEL_EXPORTER_OTLP_ENDPOINT when OpenTelemetry is enabled', () => {
+    expect(
+      createSidecarEnvironment(
+        { PATH: 'C:\\tools' },
+        { enabled: true, endpoint: 'http://localhost:4317' },
+      ),
+    ).toEqual({
+      PATH: 'C:\\tools',
+      OTEL_EXPORTER_OTLP_ENDPOINT: 'http://localhost:4317',
+    });
+  });
+
+  test('does not inject OTEL_EXPORTER_OTLP_ENDPOINT when OpenTelemetry is disabled', () => {
+    expect(
+      createSidecarEnvironment(
+        { PATH: 'C:\\tools' },
+        { enabled: false, endpoint: 'http://localhost:4317' },
+      ),
+    ).toEqual({
+      PATH: 'C:\\tools',
+    });
+  });
+
+  test('does not inject OTEL_EXPORTER_OTLP_ENDPOINT when settings are undefined', () => {
+    expect(
+      createSidecarEnvironment({ PATH: 'C:\\tools' }),
+    ).toEqual({
+      PATH: 'C:\\tools',
+    });
+  });
+
+  test('does not inject OTEL_EXPORTER_OTLP_ENDPOINT when endpoint is empty', () => {
+    expect(
+      createSidecarEnvironment(
+        { PATH: 'C:\\tools' },
+        { enabled: true, endpoint: '' },
+      ),
+    ).toEqual({
+      PATH: 'C:\\tools',
+    });
+  });
 });

tests/scripts/aspireDashboard.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  aspireDashboardContainerName,
+  aspireDashboardImage,
+  aspireDashboardUrls,
+  createAspireDashboardRunArgs,
+  createOpenTelemetryEnvironment,
+} from '../../scripts/aspireDashboard';
+
+describe('aspire dashboard helpers', () => {
+  test('creates the official standalone Docker command with mapped OTLP ports', () => {
+    expect(createAspireDashboardRunArgs()).toEqual([
+      'run',
+      '--rm',
+      '-d',
+      '--name',
+      aspireDashboardContainerName,
+      '-p',
+      '18888:18888',
+      '-p',
+      '4317:18889',
+      '-p',
+      '4318:18890',
+      '-e',
+      'ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS=true',
+      aspireDashboardImage,
+    ]);
+  });
+
+  test('injects OTLP exporter settings for local Aspire development', () => {
+    expect(
+      createOpenTelemetryEnvironment(
+        {
+          PATH: 'C:\\tools',
+        },
+        aspireDashboardUrls.otlpGrpc,
+      ),
+    ).toEqual({
+      PATH: 'C:\\tools',
+      OTEL_EXPORTER_OTLP_ENDPOINT: aspireDashboardUrls.otlpGrpc,
+      OTEL_EXPORTER_OTLP_PROTOCOL: 'grpc',
+    });
+  });
+});

tests/shared/tooling.test.ts

@@ -6,12 +6,14 @@ import {
   groupApprovalToolsByProvider,
   listApprovalToolDefinitions,
   listApprovalToolNames,
+  normalizeOpenTelemetrySettings,
   normalizeWorkspaceSettings,
   resolveProjectToolingSettings,
   resolveToolLabel,
   resolveWorkspaceToolingSettings,
   validateLspProfileDefinition,
   validateMcpServerDefinition,
+  DEFAULT_OTEL_ENDPOINT,
   type LspProfileDefinition,
   type McpServerDefinition,
   type WorkspaceToolingSettings,
@@ -118,6 +120,40 @@ describe('tooling settings helpers', () => {
     expect(normalizeWorkspaceSettings({ terminalHeight: Number.NaN }).terminalHeight).toBeUndefined();
   });
 
+  test('normalizes OpenTelemetry settings with defaults', () => {
+    const otel = normalizeOpenTelemetrySettings();
+    expect(otel.enabled).toBe(false);
+    expect(otel.endpoint).toBe(DEFAULT_OTEL_ENDPOINT);
+  });
+
+  test('preserves valid OpenTelemetry settings', () => {
+    const otel = normalizeOpenTelemetrySettings({ enabled: true, endpoint: 'http://custom:4317' });
+    expect(otel.enabled).toBe(true);
+    expect(otel.endpoint).toBe('http://custom:4317');
+  });
+
+  test('trims whitespace from OpenTelemetry endpoint', () => {
+    const otel = normalizeOpenTelemetrySettings({ enabled: true, endpoint: '  http://localhost:4317  ' });
+    expect(otel.endpoint).toBe('http://localhost:4317');
+  });
+
+  test('falls back to default endpoint when blank', () => {
+    const otel = normalizeOpenTelemetrySettings({ enabled: true, endpoint: '  ' });
+    expect(otel.endpoint).toBe(DEFAULT_OTEL_ENDPOINT);
+  });
+
+  test('normalizeWorkspaceSettings preserves OpenTelemetry when present', () => {
+    const settings = normalizeWorkspaceSettings({
+      openTelemetry: { enabled: true, endpoint: 'http://jaeger:4317' },
+    });
+    expect(settings.openTelemetry).toEqual({ enabled: true, endpoint: 'http://jaeger:4317' });
+  });
+
+  test('normalizeWorkspaceSettings omits OpenTelemetry when absent', () => {
+    const settings = normalizeWorkspaceSettings({});
+    expect(settings.openTelemetry).toBeUndefined();
+  });
+
   test('validates required MCP transport settings', () => {
     const localServer: McpServerDefinition = {
       id: 'mcp-local',