Orleans Painel

O Orleans Painel é uma ferramenta interna de monitoramento baseada na Web que fornece visibilidade em tempo real em seu Orleans cluster. Ele permite monitorar a integridade do silo, ativações de grãos, chamadas de método, lembretes e métricas do sistema sem a necessidade de infraestrutura de monitoramento externo.

Importante

Esse recurso está disponível a partir da Orleans versão 10.0. Ele está atualmente em versão prévia e pode mudar em versões futuras.

Features

O Orleans Painel fornece os seguintes recursos:

• Visão geral do cluster: exiba todos os silos no cluster com seu status, tempo de atividade e utilização de recursos.
• Monitoramento dos grãos: acompanhar as ativações de grãos, chamadas de método e métricas de desempenho por tipo de grão.
• Criação de perfil de método: analisar a frequência de chamada do método granular, a latência e as taxas de erro.
• Gerenciamento de lembretes: navegue e monitore todos os lembretes registrados em todo o cluster.
• Transmissão de log ao vivo: Veja a saída do log em tempo real do cluster.
• Detalhes do silo: inspecione as propriedades individuais do silo, os contadores e as distribuições de grãos.
• Inspeção de estado de grãos: Visualize o estado atual das instâncias de cada grão.

Installation

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

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

Configuração básica

Para adicionar o Orleans Painel ao aplicativo, chame AddDashboard() o construtor de silos e MapOrleansDashboard() mapeie os pontos de extremidade do painel:

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 seu aplicativo, navegue até http://localhost:5000/ (ou a URL configurada) para acessar o painel.

Prefixo de rota personalizado

Você pode hospedar o painel em um caminho personalizado especificando um prefixo de rota:

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

Com essa configuração, acesse o painel em http://localhost:5000/dashboard/.

Configuração

Opções de painel

Configurar o comportamento do painel 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	Padrão	Description
HideTrace	bool	false	Quando true, desativa o ponto de extremidade de transmissão de log 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 serem mantidos para métricas.

Opções do criador de perfil de grãos

O perfilador granular coleta dados de desempenho em nível de 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	Padrão	Description
TraceAlways	bool	false	Quando true, os dados de perfilagem são coletados continuamente mesmo quando o painel não está sendo consultado.
DeactivationTime	TimeSpan	1 minuto	Duração da inatividade após a qual a criação de perfil é interrompida automaticamente. Só se aplica quando TraceAlways é false.

Excluindo grãos da criação de perfil

Use o [NoProfiling] atributo para excluir grãos específicos da criação de 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-hospedagem com silo (recomendado)

O padrão de implantação mais simples é hospedar o painel diretamente com seu Orleans silo. Essa é 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();

Servidor de painel separado

Para cenários em que você deseja executar o painel separadamente de seus silos (por exemplo, para fornecer um endpoint de monitoramento dedicado), você pode hospedar o painel em um cliente Orleans.

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 painel separado, você ainda deve chamar AddDashboard() no construtor de silos. Os silos precisam dos serviços de painel para coletar e fornecer dados de métricas.

Authorization

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

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

Você 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");

Resolução de problemas

O painel mostra a mensagem "conectividade perdida"

Esse erro ocorre quando o painel não pode se comunicar com o Orleans cluster. Causas comuns:

1. Silo não iniciado: certifique-se de que o Orleans silo está em execução antes de acessar o painel.
2. Problemas de rede: verifique a conectividade de rede entre o host do painel e os silos.
3. Configuração incorreta do cluster: verifique se o clustering está configurado corretamente.

Dados de criação de perfil não exibidos

Se os dados de profiling do método grain estiverem vazios:

1. Fazer chamadas de grãos: a criação de perfil mostra apenas os dados depois que os métodos de grãos são invocados.
2. Verificar TraceAlways: por padrão, a criação de perfil é interrompida após 1 minuto de inatividade do painel. Defina TraceAlways = true para perfilamento contínuo.
3. Verifique [NoProfiling]: assegure-se de que o grão não está marcado com o [NoProfiling] atributo.

O endpoint de rastreamento em tempo real está desabilitado

Se o /Trace ponto de extremidade retornar 403 Proibido:

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

Consulte também

• Observabilidade em Orleans
• Pacotes NuGet

O Orleans Painel é uma ferramenta de monitoramento interna introduzida na Orleans 10.0. Para versões anteriores, considere usar:

• OrleansDashboard (comunidade): um painel mantido pela comunidade para Orleans 3.x a 8.x.
• Integração do OpenTelemetry: recursos embutidos de observabilidade disponíveis na Orleans versão 7.0 e posteriores. Veja Observabilidade em Orleans.