Orleans Dashboard

The Orleans Dashboard is a built-in web-based monitoring tool that provides real-time visibility into your Orleans cluster. It allows you to monitor silo health, grain activations, method calls, reminders, and system metrics without requiring external monitoring infrastructure.

Features

The Orleans Dashboard provides the following capabilities:

• Cluster overview: View all silos in the cluster with their status, uptime, and resource utilization.
• Grain monitoring: Track grain activations, method calls, and performance metrics per grain type.
• Method profiling: Analyze grain method call frequency, latency, and error rates.
• Reminder management: Browse and monitor all registered reminders across the cluster.
• Live log streaming: View real-time log output from the cluster.
• Silo details: Inspect individual silo properties, counters, and grain distributions.
• Grain state inspection: View the current state of individual grain instances.

Installation

The Orleans Dashboard is distributed in two NuGet packages:

Basic setup

To add the Orleans Dashboard to your application, call AddDashboard() on your silo builder and MapOrleansDashboard() to map the dashboard endpoints:

using Orleans.Dashboard;

var builder = WebApplication.CreateBuilder(args);

// Configure Orleans with the dashboard
builder.UseOrleans(siloBuilder =>
{
    siloBuilder.UseLocalhostClustering();
    siloBuilder.AddMemoryGrainStorageAsDefault();

    // Add the dashboard services
    siloBuilder.AddDashboard();
});

var app = builder.Build();

// Map dashboard endpoints at the root path
app.MapOrleansDashboard();

app.Run();

After starting your application, navigate to http://localhost:5000/ (or your configured URL) to access the dashboard.

Custom route prefix

You can host the dashboard at a custom path by specifying a route prefix:

// Map dashboard endpoints at /dashboard
app.MapOrleansDashboard(routePrefix: "/dashboard");

With this configuration, access the dashboard at http://localhost:5000/dashboard/.

Configuration

Dashboard options

Configure dashboard behavior using DashboardOptions:

siloBuilder.AddDashboard(options =>
{
    // Disable the live log streaming endpoint
    options.HideTrace = true;

    // Set the counter update interval (minimum 1000ms)
    options.CounterUpdateIntervalMs = 2000;

    // Set the history buffer length for metrics
    options.HistoryLength = 200;
});

Grain profiler options

The grain profiler collects method-level performance data. Configure it using GrainProfilerOptions:

builder.Services.Configure<GrainProfilerOptions>(options =>
{
    // Always collect profiling data, even when dashboard is inactive
    options.TraceAlways = true;

    // Time after which profiling stops if dashboard is inactive
    options.DeactivationTime = TimeSpan.FromMinutes(5);
});

Excluding grains from profiling

Use the [NoProfiling] attribute to exclude specific grains from performance profiling:

using Orleans.Dashboard;

[NoProfiling]
public class HighFrequencyGrain : Grain, IHighFrequencyGrain
{
    // This grain won't be included in profiling data
}

Deployment patterns

Co-hosted with silo (recommended)

The simplest deployment pattern is to host the dashboard directly with your Orleans silo. This is the recommended approach for most scenarios:

using Orleans.Dashboard;

var builder = WebApplication.CreateBuilder(args);

builder.UseOrleans(siloBuilder =>
{
    siloBuilder.UseLocalhostClustering();
    siloBuilder.UseInMemoryReminderService();
    siloBuilder.AddMemoryGrainStorageAsDefault();
    siloBuilder.AddDashboard();
});

var app = builder.Build();

app.MapOrleansDashboard();

app.Run();

Separate dashboard host

For scenarios where you want to run the dashboard separately from your silos (for example, to provide a dedicated monitoring endpoint), you can host the dashboard on an Orleans client:

using Orleans.Configuration;
using Orleans.Dashboard;
using System.Net;

// Start the silo host
var siloHostBuilder = Host.CreateApplicationBuilder(args);
siloHostBuilder.UseOrleans(builder =>
{
    builder.UseDevelopmentClustering(options => 
        options.PrimarySiloEndpoint = new IPEndPoint(IPAddress.Loopback, 11111));
    builder.UseInMemoryReminderService();
    builder.AddMemoryGrainStorageAsDefault();
    builder.ConfigureEndpoints(IPAddress.Loopback, 11111, 30000);

    // Dashboard must also be added to silos
    builder.AddDashboard();
});
using var siloHost = siloHostBuilder.Build();
await siloHost.StartAsync();

// Create a separate web application for the dashboard
var dashboardBuilder = WebApplication.CreateBuilder(args);

// Configure Orleans client
dashboardBuilder.UseOrleansClient(clientBuilder =>
{
    clientBuilder.UseStaticClustering(options => 
        options.Gateways.Add(new IPEndPoint(IPAddress.Loopback, 30000).ToGatewayUri()));

    // Add dashboard services to the client
    clientBuilder.AddDashboard();
});

var dashboardApp = dashboardBuilder.Build();

// Map dashboard endpoints on the client
dashboardApp.MapOrleansDashboard();

await dashboardApp.RunAsync();

await siloHost.StopAsync();

Authorization

The dashboard endpoints support ASP.NET Core authorization. Use the RequireAuthorization() extension method to protect access:

// Require authentication for dashboard access
app.MapOrleansDashboard()
   .RequireAuthorization();

You can also apply specific authorization policies:

// Configure authorization
builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("DashboardAccess", policy =>
        policy.RequireRole("Admin", "Operator"));
});

builder.Services.AddAuthentication(/* your auth configuration */);

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

// Apply the policy to dashboard endpoints
app.MapOrleansDashboard()
   .RequireAuthorization("DashboardAccess");

Troubleshooting

Dashboard shows "lost connectivity" message

This error occurs when the dashboard cannot communicate with the Orleans cluster. Common causes:

1. Silo not started: Ensure your Orleans silo is running before accessing the dashboard.
2. Network issues: Verify network connectivity between the dashboard host and silos.
3. Cluster misconfiguration: Check that clustering is properly configured.

Profiling data not appearing

If grain method profiling data is empty:

1. Make grain calls: Profiling only shows data after grain methods are invoked.
2. Check TraceAlways: By default, profiling stops after 1 minute of dashboard inactivity. Set TraceAlways = true for continuous profiling.
3. Check [NoProfiling]: Ensure the grain isn't marked with the [NoProfiling] attribute.

Live trace endpoint is disabled

If the /Trace endpoint returns 403 Forbidden:

• Check that DashboardOptions.HideTrace is not set to true.

See also

• Observability in Orleans
• NuGet packages

The Orleans Dashboard is a built-in monitoring tool introduced in Orleans 10.0. For earlier versions, consider using:

• OrleansDashboard (community): A community-maintained dashboard for Orleans 3.x through 8.x.
• OpenTelemetry integration: Built-in observability features available in Orleans 7.0 and later. See Observability in Orleans.