Partilhar via

Inspeção de dados de telemetria com o Aspire Dashboard

  • Artigo

O Painel do Aspire faz parte da oferta do .NET Aspire . O painel permite que os desenvolvedores monitorem e inspecionem seus aplicativos distribuídos.

Neste exemplo, utilizaremos o modo autónomo e aprenderemos a exportar dados de telemetria para o Aspire Dashboard e a inspecionar os dados nesse ecrã.

Exportador

Os exportadores são responsáveis pelo envio de dados de telemetria para um destino. Leia mais sobre exportadores aqui. Neste exemplo, utilizamos o exportador do OpenTelemetry Protocol (OTLP) para enviar dados de telemetria para o Aspire Dashboard.

Pré-requisitos

  • Uma implantação de conclusão de chat do Azure OpenAI.
  • Docker
  • O SDK .Net mais recente para o seu sistema operacional.

Nota

A Observabilidade do Kernel Semântico ainda não está disponível para Java.

Configurar

Criar um novo aplicativo de console

Em um terminal, execute o seguinte comando para criar um novo aplicativo de console em C#:

dotnet new console -n TelemetryAspireDashboardQuickstart

Navegue até o diretório do projeto recém-criado após a conclusão do comando.

Instalar pacotes necessários

  • Kernel Semântico

    dotnet add package Microsoft.SemanticKernel

  • Exportador de console OpenTelemetry

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

Crie uma aplicação simples com o Kernel Semântico

No diretório do projeto, abra o Program.cs arquivo com seu editor favorito. Vamos criar um aplicativo simples que usa o Kernel Semântico para enviar um prompt para um modelo de conclusão de chat. Substitua o conteúdo existente pelo código a seguir e preencha os valores necessários para deploymentName, endpointe apiKey:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.SemanticKernel;
using OpenTelemetry;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

namespace TelemetryAspireDashboardQuickstart
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // Telemetry setup code goes here

            IKernelBuilder builder = Kernel.CreateBuilder();
            // builder.Services.AddSingleton(loggerFactory);
            builder.AddAzureOpenAIChatCompletion(
                deploymentName: "your-deployment-name",
                endpoint: "your-azure-openai-endpoint",
                apiKey: "your-azure-openai-api-key"
            );

            Kernel kernel = builder.Build();

            var answer = await kernel.InvokePromptAsync(
                "Why is the sky blue in one sentence?"
            );

            Console.WriteLine(answer);
        }
    }
}

Adicionar telemetria

Se você executar o aplicativo de console agora, você deve esperar ver uma frase explicando por que o céu é azul. Para observar o kernel via telemetria, substitua o // Telemetry setup code goes here comentário pelo seguinte código:

// Endpoint to the Aspire Dashboard
var endpoint = "http://localhost:4317";

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService("TelemetryAspireDashboardQuickstart");

// Enable model diagnostics with sensitive data.
AppContext.SetSwitch("Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnosticsSensitive", true);

using var traceProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource("Microsoft.SemanticKernel*")
    .AddOtlpExporter(options => options.Endpoint = new Uri(endpoint))
    .Build();

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddMeter("Microsoft.SemanticKernel*")
    .AddOtlpExporter(options => options.Endpoint = new Uri(endpoint))
    .Build();

using var loggerFactory = LoggerFactory.Create(builder =>
{
    // Add OpenTelemetry as a logging provider
    builder.AddOpenTelemetry(options =>
    {
        options.SetResourceBuilder(resourceBuilder);
        options.AddOtlpExporter(options => options.Endpoint = new Uri(endpoint));
        // Format log messages. This is default to false.
        options.IncludeFormattedMessage = true;
        options.IncludeScopes = true;
    });
    builder.SetMinimumLevel(LogLevel.Information);
});

Finalmente, Descomente a linha // builder.Services.AddSingleton(loggerFactory); para adicionar a fábrica de madeireiras ao construtor.

Consulte este artigo para obter mais informações sobre o código de configuração da telemetria. A única diferença aqui é que estamos a utilizar AddOtlpExporter para exportar dados de telemetria para o Aspire Dashboard.

Criar um novo ambiente virtual Python

python -m venv telemetry-aspire-dashboard-quickstart

Ative o ambiente virtual.

telemetry-aspire-dashboard-quickstart\Scripts\activate

Instalar pacotes necessários

pip install semantic-kernel opentelemetry-exporter-otlp-proto-grpc

Crie um script Python simples com o Kernel Semântico

Crie um novo script Python e abra-o com o seu editor favorito.

New-Item -Path telemetry_aspire_dashboard_quickstart.py -ItemType file

Vamos criar um script Python simples que usa o Kernel Semântico para enviar um prompt para um modelo de conclusão de chat. Substitua o conteúdo existente pelo código a seguir e preencha os valores necessários para deployment_name, endpointe api_key:

import asyncio
import logging

from opentelemetry._logs import set_logger_provider
from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.metrics import set_meter_provider
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.metrics.view import DropAggregation, View
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.semconv.resource import ResourceAttributes
from opentelemetry.trace import set_tracer_provider

from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion


# Telemetry setup code goes here

async def main():
    # Create a kernel and add a service
    kernel = Kernel()
    kernel.add_service(AzureChatCompletion(
        api_key="your-azure-openai-api-key",
        endpoint="your-azure-openai-endpoint",
        deployment_name="your-deployment-name"
    ))

    answer = await kernel.invoke_prompt("Why is the sky blue in one sentence?")
    print(answer)


if __name__ == "__main__":
    asyncio.run(main())

Adicionar telemetria

Variáveis de ambiente

Consulte este artigo para obter mais informações sobre como configurar as variáveis de ambiente necessárias para permitir que o kernel emita extensões para conectores de IA.

Código

Se você executar o script agora, você deve esperar ver uma frase explicando por que o céu é azul. Para observar o kernel via telemetria, substitua o # Telemetry setup code goes here comentário pelo seguinte código:

# Endpoint to the Aspire Dashboard
endpoint = "http://localhost:4317"

# Create a resource to represent the service/sample
resource = Resource.create({ResourceAttributes.SERVICE_NAME: "telemetry-aspire-dashboard-quickstart"})


def set_up_logging():
    exporter = OTLPLogExporter(endpoint=endpoint)

    # Create and set a global logger provider for the application.
    logger_provider = LoggerProvider(resource=resource)
    # Log processors are initialized with an exporter which is responsible
    # for sending the telemetry data to a particular backend.
    logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
    # Sets the global default logger provider
    set_logger_provider(logger_provider)

    # Create a logging handler to write logging records, in OTLP format, to the exporter.
    handler = LoggingHandler()
    # Add filters to the handler to only process records from semantic_kernel.
    handler.addFilter(logging.Filter("semantic_kernel"))
    # Attach the handler to the root logger. `getLogger()` with no arguments returns the root logger.
    # Events from all child loggers will be processed by this handler.
    logger = logging.getLogger()
    logger.addHandler(handler)
    logger.setLevel(logging.INFO)


def set_up_tracing():
    exporter = OTLPSpanExporter(endpoint=endpoint)

    # Initialize a trace provider for the application. This is a factory for creating tracers.
    tracer_provider = TracerProvider(resource=resource)
    # Span processors are initialized with an exporter which is responsible
    # for sending the telemetry data to a particular backend.
    tracer_provider.add_span_processor(BatchSpanProcessor(exporter))
    # Sets the global default tracer provider
    set_tracer_provider(tracer_provider)


def set_up_metrics():
    exporter = OTLPMetricExporter(endpoint=endpoint)

    # Initialize a metric provider for the application. This is a factory for creating meters.
    meter_provider = MeterProvider(
        metric_readers=[PeriodicExportingMetricReader(exporter, export_interval_millis=5000)],
        resource=resource,
        views=[
            # Dropping all instrument names except for those starting with "semantic_kernel"
            View(instrument_name="*", aggregation=DropAggregation()),
            View(instrument_name="semantic_kernel*"),
        ],
    )
    # Sets the global default meter provider
    set_meter_provider(meter_provider)


# This must be done before any other telemetry calls
set_up_logging()
set_up_tracing()
set_up_metrics()

Consulte este artigo para obter mais informações sobre o código de configuração da telemetria. A única diferença aqui é que estamos a utilizar OTLP[Span|Metric|Log]Exporter para exportar dados de telemetria para o Aspire Dashboard.

Nota

A Observabilidade do Kernel Semântico ainda não está disponível para Java.

Iniciar o Painel de Instrumentos do Aspire

Siga as instruções aqui para iniciar o painel. Quando o painel estiver em execução, abra um navegador e navegue até para http://localhost:18888 acessar o painel.

Executar

Execute o aplicativo de console com o seguinte comando:

dotnet run

Execute o script Python com o seguinte comando:

python telemetry_aspire_dashboard_quickstart.py

Nota

A Observabilidade do Kernel Semântico ainda não está disponível para Java.

Inspecionar dados de telemetria

Depois de executar o aplicativo, vá até o painel para inspecionar os dados de telemetria.

Gorjeta

Siga este guia para explorar a interface do Aspire Dashboard.

Rastreios

Se esta for a primeira vez que você executa o aplicativo depois de iniciar o painel, você verá que um rastreamento é a Traces guia. Clique no rastreamento para ver mais detalhes.

RastreamentoVisão geral

Nos detalhes do rastreamento, você pode ver a extensão que representa a função de prompt e a extensão que representa o modelo de conclusão de chat. Clique no período de conclusão do chat para ver detalhes sobre a solicitação e a resposta.

Gorjeta

Você pode filtrar os atributos dos vãos para encontrar o que você está interessado.

RastreamentosDetalhes

Registos

Vá até a Structured guia para visualizar os logs emitidos pelo aplicativo. Consulte este guia sobre como trabalhar com logs estruturados no painel.

Próximos passos

Agora que já enviou com sucesso dados de telemetria para o Aspire Dashboard, pode explorar mais funcionalidades do Kernel Semântico que o podem ajudar a monitorizar e diagnosticar a sua aplicação:

Telemetria avançada com kernel semântico