Compartir a través de

Inspección de datos de telemetría con el panel Aspire

  • Artículo

Aspire Dashboard forma parte de la oferta de .NET Aspire . El panel permite a los desarrolladores supervisar e inspeccionar sus aplicaciones distribuidas.

En este ejemplo, usaremos el modo independiente y aprenderemos a exportar datos de telemetría a Aspire Dashboard e inspeccionaremos los datos allí.

Exportador

Los exportadores son responsables de enviar datos de telemetría a un destino. Obtenga más información sobre los exportadores aquí. En este ejemplo, usamos el exportador de OpenTelemetry Protocol (OTLP) para enviar datos de telemetría al panel aspire.

Requisitos previos

  • Una implementación de finalización de chat de Azure OpenAI.
  • Docker
  • El SDK de .Net más reciente para el sistema operativo.

Nota:

La observabilidad semántica del kernel aún no está disponible para Java.

Configurar

Creación de una nueva aplicación de consola

En un terminal, ejecute el siguiente comando para crear una nueva aplicación de consola en C#:

dotnet new console -n TelemetryAspireDashboardQuickstart

Vaya al directorio del proyecto recién creado una vez completado el comando.

Instalación de los paquetes requeridos

  • Kernel semántico

    dotnet add package Microsoft.SemanticKernel

  • Exportador de consola de OpenTelemetry

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

Creación de una aplicación sencilla con kernel semántico

En el directorio del proyecto, abra el Program.cs archivo con su editor favorito. Vamos a crear una aplicación sencilla que use kernel semántico para enviar un mensaje a un modelo de finalización de chat. Reemplace el contenido existente por el código siguiente y rellene los valores necesarios para deploymentName, endpointy 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);
        }
    }
}

Adición de telemetría

Si ejecuta la aplicación de consola ahora, debería esperar ver una frase que explique por qué el cielo es azul. Para observar el kernel mediante telemetría, reemplace el // Telemetry setup code goes here comentario por el código siguiente:

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

Por último, quite la marca de comentario de la línea // builder.Services.AddSingleton(loggerFactory); para agregar el generador del registrador al generador.

Consulte este artículo para obtener más información sobre el código de configuración de telemetría. La única diferencia aquí es que estamos usando AddOtlpExporter para exportar datos de telemetría al panel Aspire.

Creación de un nuevo entorno virtual de Python

python -m venv telemetry-aspire-dashboard-quickstart

Active el entorno virtual.

telemetry-aspire-dashboard-quickstart\Scripts\activate

Instalación de los paquetes requeridos

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

Creación de un script de Python sencillo con kernel semántico

Cree un nuevo script de Python y ábralo con su editor favorito.

New-Item -Path telemetry_aspire_dashboard_quickstart.py -ItemType file

Vamos a crear un script de Python sencillo que use kernel semántico para enviar un mensaje a un modelo de finalización de chat. Reemplace el contenido existente por el código siguiente y rellene los valores necesarios para deployment_name, endpointy 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())

Adición de telemetría

Variables de entorno

Consulte este artículo para obtener más información sobre cómo configurar las variables de entorno necesarias para permitir que el kernel emita intervalos para los conectores de IA.

Código

Si ejecuta el script ahora, debería esperar ver una frase que explique por qué el cielo es azul. Para observar el kernel mediante telemetría, reemplace el # Telemetry setup code goes here comentario por el código siguiente:

# 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 artículo para obtener más información sobre el código de configuración de telemetría. La única diferencia aquí es que estamos usando OTLP[Span|Metric|Log]Exporter para exportar datos de telemetría al panel Aspire.

Nota:

La observabilidad semántica del kernel aún no está disponible para Java.

Iniciar el panel de Aspire

Siga las instrucciones que se indican aquí para iniciar el panel. Una vez que el panel se esté ejecutando, abra un explorador y vaya a http://localhost:18888 para acceder al panel.

Ejecutar

Ejecute la aplicación de consola con el siguiente comando:

dotnet run

Ejecute el script de Python con el siguiente comando:

python telemetry_aspire_dashboard_quickstart.py

Nota:

La observabilidad semántica del kernel aún no está disponible para Java.

Inspección de los datos de telemetría

Después de ejecutar la aplicación, diríjase al panel para inspeccionar los datos de telemetría.

Sugerencia

Siga esta guía para explorar la interfaz del panel aspire.

Traces

Si esta es la primera vez que ejecuta la aplicación después de iniciar el panel, debería ver que un seguimiento es la Traces pestaña. Haga clic en el seguimiento para ver más detalles.

TracesOverview

En los detalles del seguimiento, puede ver el intervalo que representa la función prompt y el intervalo que representa el modelo de finalización del chat. Haga clic en el intervalo de finalización del chat para ver detalles sobre la solicitud y la respuesta.

Sugerencia

Puede filtrar los atributos de los intervalos para encontrar el que le interesa.

TracesDetails

Registros

Vaya a la Structured pestaña para ver los registros emitidos por la aplicación. Consulte esta guía sobre cómo trabajar con registros estructurados en el panel.

Pasos siguientes

Ahora que ha generado correctamente datos de telemetría en el panel aspire, puede explorar más características del kernel semántico que pueden ayudarle a supervisar y diagnosticar la aplicación:

Telemetría avanzada con kernel semántico