Orleans Painel de controlo

O Orleans Dashboard é uma ferramenta integrada de monitorização baseada na web que oferece visibilidade em tempo real do seu Orleans cluster. Permite-lhe monitorizar o estado do silo, a ativação dos grãos, chamadas de métodos, lembretes e métricas do sistema sem necessitar de uma infraestrutura de monitorização externa.

Importante

Esta funcionalidade está disponível a partir da Orleans versão 10.0. Está atualmente em pré-visualização e pode mudar em futuras versões.

Caraterísticas

O Orleans Dashboard oferece as seguintes funcionalidades:

• Visão geral do cluster: Veja todos os silos do cluster com o seu estado, tempo de atividade e utilização de recursos.
• Monitorização de grãos: Acompanhar ativações de grãos, chamadas de método e métricas de desempenho por tipo de grão.
• Perfilagem de métodos: Analisar a frequência, latência e taxas de erro das chamadas de método granular.
• Gestão de lembretes: Navegue e monitorize todos os lembretes registados em todo o cluster.
• Transmissão de registos em direto: Veja a saída de registo em tempo real do cluster.
• Detalhes do silo: Inspecione as propriedades individuais dos silos, contadores e distribuições de cereais.
• Inspeção do estado dos grãos: Veja o estado atual das instâncias individuais de grãos.

Installation

O Orleans Dashboard é distribuído em dois pacotes NuGet:

Package	Description
Orleans	Pacote principal de dashboards com endpoints UI e API
Microsoft.Orleans.Dashboard.Abstractions	Abstrações para integração de dashboards (por exemplo, NoProfilingAttribute)

Configuração básica

Para adicionar o Orleans Dashboard à sua aplicação, chame AddDashboard() no seu construtor de silos e MapOrleansDashboard() para mapear os endpoints do dashboard.

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();

Depois de iniciar a sua aplicação, navegue até http://localhost:5000/ (ou para a sua URL configurada) para aceder ao painel.

Prefixo de rota personalizado

Pode hospedar o painel num caminho personalizado especificando um prefixo de rota:

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

Com esta configuração, aceda ao painel em http://localhost:5000/dashboard/.

Configuração

Opções do painel de instrumentos

Configure o comportamento do dashboard usando 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;
});

Opção	Tipo	Predefinido	Description
HideTrace	bool	false	Quando true, desativa o endpoint de streaming de logs ao vivo.
CounterUpdateIntervalMs	int	1000	Milissegundos entre amostras de contador. Deve ser >= 1000.
HistoryLength	int	100	Número de pontos de dados históricos a manter para métricas.

Opções do perfilador de grãos

O perfilador de grãos recolhe dados de desempenho ao nível do método. Configure-o usando 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);
});

Opção	Tipo	Predefinido	Description
TraceAlways	bool	false	Quando true, os dados de perfilagem são recolhidos continuamente mesmo quando o painel não está a ser consultado.
DeactivationTime	TimeSpan	1 minuto	Duração da inatividade, após a qual o perfil termina automaticamente. Só se aplica quando TraceAlways é false.

Exclusão de grãos do perfilamento

Use o [NoProfiling] atributo para excluir grãos específicos do perfil de desempenho:

using Orleans.Dashboard;

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

Padrões de implantação

Co-apresentado com SILO (recomendado)

O padrão de implementação mais simples é alojar o dashboard diretamente com o seu Orleans silo. Esta é a abordagem recomendada para a maioria dos cenários:

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();

Host de painel separado

Para cenários em que pretende executar o dashboard separadamente dos seus silos (por exemplo, para fornecer um endpoint dedicado de monitorização), pode hospedar o dashboard num Orleans cliente:

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();

Importante

Ao usar um host de dashboard separado, deve ainda assim invocar AddDashboard() no construtor de silos. Os silos precisam dos serviços de painel de controlo para coletar e fornecer dados de métricas.

Authorization

Os endpoints do painel suportam a autorização do ASP.NET Core. Utilize o método de extensão RequireAuthorization() para proteger o acesso:

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

Também pode aplicar políticas de autorização específicas:

// 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");

Solução de problemas

O painel mostra a mensagem de "perda de conectividade"

Este erro ocorre quando o painel não consegue comunicar com o Orleans cluster. Causas comuns:

1. Silo não iniciado: Certifique-se de que o seu Orleans silo está a funcionar antes de aceder ao dashboard.
2. Problemas de rede: Verifique a conectividade de rede entre o host do painel e os silos.
3. Configuração errada do cluster: Verifique se o clustering está devidamente configurado.

Dados de perfilagem não aparecem

Se os dados de perfilagem do método de grãos estão vazios:

1. Make grain calls: A perfilagem só mostra dados depois de os métodos de grain serem invocados.
2. Verificar TraceAlways: Por defeito, o perfil para após 1 minuto de inatividade no dashboard. Definir TraceAlways = true para perfil contínuo.
3. Verificação [NoProfiling]: Certifique-se de que o grão não esteja marcado com o atributo [NoProfiling].

O endpoint do rastreamento ao vivo está desativado

Se o /Trace endpoint devolver 403 Proibido:

• Verifique se DashboardOptions.HideTrace não está definido para true.

Consulte também

• Observabilidade em Orleans
• pacotes NuGet

O Orleans Dashboard é uma ferramenta de monitorização integrada introduzida na Orleans versão 10.0. Para versões anteriores, considere usar:

• OrleansDashboard (comunidade): Um painel mantido pela comunidade para Orleans as versões 3.x a 8.x.
• Integração OpenTelemetry: Funcionalidades de observabilidade incorporadas disponíveis a partir da Orleans 7.0 e versões posteriores. Ver Observabilidade em Orleans.