Using Squad with the Aspire Dashboard

Try this:

squad aspire

Aspire is a free, open-source dashboard for observing any OpenTelemetry app — traces, metrics, logs, all in one place. Squad ships with an Aspire integration that streams all your telemetry (agent spawns, token usage, session metrics, errors) to the dashboard in real time.

1. What Is Aspire?

Aspire is not a .NET thing — it’s a standalone dashboard for any app that speaks OpenTelemetry. You can run it in Docker, point any OTLP client at it, and watch telemetry flow in:

  • Traces — see every agent spawn, task execution, and error with timing
  • Metrics — counters (agents spawned, tokens consumed), histograms (latency), gauges (active sessions)
  • Resources — grouping by service and environment

Squad’s OTel integration exports OTLP/gRPC (the only protocol Aspire understands), so you get instant visibility into what your agents are doing.

2. Launch the Aspire Container

The easiest way is the built-in squad aspire command:

squad aspire

This will:

  1. Pull the Aspire dashboard image: mcr.microsoft.com/dotnet/aspire-dashboard:latest
  2. Start the container on port 18888 (UI) and port 4317 (OTLP gRPC)
  3. Print the dashboard URL (usually http://localhost:18888)

Behind the scenes, the container runs with:

docker run -d \
  --name aspire-dashboard \
  -p 18888:18888 \
  -p 4317:18889 \
  -e DASHBOARD__FRONTEND__AUTHMODE=Unsecured \
  -e DASHBOARD__OTLP__AUTHMODE=Unsecured \
  mcr.microsoft.com/dotnet/aspire-dashboard:latest

The DASHBOARD__FRONTEND__AUTHMODE=Unsecured env var disables dashboard auth so you can view traces without a login. DASHBOARD__OTLP__AUTHMODE=Unsecured allows the OTLP gRPC endpoint to accept connections without an API key. (For production, secure both with auth tokens.)

3. Connect Squad to Aspire

When you run Squad (via the CLI or SDK), set the OTLP endpoint:

Option A: CLI (standalone)

$env:OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
squad run

export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
squad run "your prompt here"

Option B: SDK (programmatic)

import { initSquadTelemetry, EventBus } from 'squad-sdk';

const bus = new EventBus();
const telemetry = initSquadTelemetry({
  endpoint: 'http://localhost:4317',
  eventBus: bus,
});

// … run your squad …

await telemetry.shutdown();

That’s it. Squad will automatically:

  1. Initialize OpenTelemetry providers (tracing + metrics)
  2. Export all agent spawns, token usage, session metrics, and errors to Aspire
  3. Flush telemetry on shutdown

4. What You’ll See in the Dashboard

Open http://localhost:18888 and navigate to:

Traces (/traces)

You’ll see a list of spans for each operation. Examples:

squad.init                 3ms      ✓
squad.agent.spawn          250ms    ✓  (agent-name: "Lead")
squad.agent.spawn          180ms    ✓  (agent-name: "Backend")
squad.agent.error          5ms      ✗  (error: "timeout")
squad.run                  2100ms   ✓

Each span has attributes:

  • agent.name — the agent that ran
  • session.id — which session this belongs to
  • mode — “sync” or “async”
  • status — success or error

Click a span to see full details (attributes, events, timing).

Metrics (/metrics)

You’ll see gauges, counters, and histograms:

Counters:

  • squad.tokens.input — total input tokens consumed
  • squad.tokens.output — total output tokens produced
  • squad.agent.spawns — total agents spawned
  • squad.sessions.created — total sessions created

Gauges:

  • squad.agent.active — currently active agent sessions
  • squad.sessions.active — currently active sessions
  • squad.sessions.idle — pooled sessions waiting for reuse

Histograms:

  • squad.agent.duration — agent task duration (ms)
  • squad.response.ttft — time to first token (ms)
  • squad.response.duration — total response duration (ms)

Resources

Aspire groups all telemetry by service. You’ll see:

  • service.name — “squad-cli” or your custom app name
  • squad.version — which version of Squad you’re running

5. Example Workflow

1. Start Aspire

squad aspire

2. Run Squad with telemetry

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
squad run "Implement user registration with email verification"

3. Watch in real time

Refresh the Aspire dashboard. You’ll see:

  • Traces section fills with squad.agent.spawn, squad.init, etc.
  • Metrics show counters ticking up for tokens consumed, agents spawned
  • Latency histogram shows how long agents took

4. Click a span

Click squad.agent.spawn to see:

Duration:     250ms
Attributes:
  agent.name:  "Lead"
  session.id:  "abc-123"
  mode:        "sync"

6. Troubleshooting

Quick Debug Checklist

If no telemetry appears in the Aspire dashboard, walk through this list:

  1. Is the container running?

    docker ps | grep aspire-dashboard

    You should see ports 18888 and 4317 mapped.

  2. Is the OTLP endpoint set correctly?

    echo $OTEL_EXPORTER_OTLP_ENDPOINT
# Must be: http://localhost:4317

    Port 4317 on the host maps to the Aspire OTLP/gRPC listener on container port 18889. Do not use the dashboard UI port (18888).

  3. Is the protocol correct? Squad exports OTLP/gRPC. Aspire only accepts gRPC on port 18889. If you see UNIMPLEMENTED or connection errors, confirm you’re not accidentally using an OTLP/HTTP endpoint (port 4318).

  4. Check Aspire container logs for incoming connections:

    docker logs aspire-dashboard 2>&1 | grep -i otlp

    You should see log lines indicating the OTLP service is listening. If you see auth errors, ensure DASHBOARD__OTLP__AUTHMODE=Unsecured is set.

  5. Is the OTLP auth mode unsecured? If the container was started with DASHBOARD__OTLP__AUTHMODE=ApiKey, the SDK must send a matching API key header. For local dev, use Unsecured instead.

  6. Firewall / network: Port 4317 must be reachable between your app and the Docker host. On Docker Desktop (Windows/Mac), localhost:4317 should work.

  7. Wait for batching: OTel batches span exports. Traces may take 1–2 seconds to appear. Metrics export every 30 seconds by default (set OTEL_METRIC_EXPORT_INTERVAL_MILLIS=1000 for faster feedback).

Dashboard shows no traces

  • Check the container is running: docker ps | grep aspire-dashboard
  • Verify the endpoint: OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
  • Wait a moment: Aspire batches exports — it may take 1–2 seconds for traces to appear
  • Check firewall: Port 4317 needs to be open between your app and Docker

Dashboard is slow or unresponsive

  • Restart the container: squad aspire (auto-stops and restarts)
  • Check Docker resources: Aspire needs ~500MB RAM
  • Look at logs: docker logs aspire-dashboard

OTLP/gRPC connection refused

  • Ensure port 4317 is mapped: The docker run command above maps -p 4317:18889
  • On Windows/Mac: If using Docker Desktop, localhost:4317 should work. If not, try host.docker.internal:4317
  • Custom endpoint? Set OTEL_EXPORTER_OTLP_ENDPOINT explicitly

7. Stop Aspire

squad aspire --stop

Or manually:

docker stop aspire-dashboard
docker rm aspire-dashboard

8. Pro Tips

  • Export metrics frequently: Set OTEL_METRIC_EXPORT_INTERVAL_MILLIS=1000 for near-real-time metric updates (default is 60s)
  • Tag your service: Customize the service name with OTEL_SERVICE_NAME=my-app
  • Batch size: Adjust OTEL_BSP_MAX_QUEUE_SIZE if you’re emitting tons of spans
  • Only export what you need: If Squad is a tiny part of your app, filter traces by service name in Aspire UI

9. Learn More

Aspire pairs perfectly with Squad: watch your agents work in real time, catch performance issues early, and prove to yourself (and your team) that AI agents are deterministic and safe.