Inspectie van telemetriegegevens met Application Insights

Application Insights maakt deel uit van Azure Monitor, een uitgebreide oplossing voor het verzamelen, analyseren en uitvoeren van telemetriegegevens uit uw cloud- en on-premises omgevingen. Met Application Insights kunt u de prestaties van uw toepassing bewaken, problemen detecteren en problemen diagnosticeren.

In dit voorbeeld leert u hoe u telemetriegegevens naar Application Insights exporteert en de gegevens in de Application Insights-portal inspecteert.

Waarschuwing

Semantische kernel maakt gebruik van een .NET 8-functie die sleutelservices wordt genoemd. Application Insights heeft een probleem met serviceregistratie, waardoor deze niet compatibel is met sleutelservices. Als u Semantische kernel met sleutelservices gebruikt en onverwachte fouten ondervindt met betrekking tot Application Insights-afhankelijkheidsinjectie, moet u Application Insights registreren voordat sleutelservices dit probleem kunnen oplossen. Zie microsoft/ApplicationInsights-dotnet#2879 voor meer informatie

Exportfunctie

Exporteurs zijn verantwoordelijk voor het verzenden van telemetriegegevens naar een bestemming. Lees hier meer over exporteurs. In dit voorbeeld gebruiken we de Azure Monitor-exporteur om telemetriegegevens uit te voeren naar een Application Insights-exemplaar.

Vereisten

• Een voltooiingsimplementatie van een Azure OpenAI-chat.
• Een Application Insights-exemplaar. Volg de instructies hier om een resource te maken als u er geen hebt. Kopieer de verbindingsreeks voor later gebruik.
• De nieuwste .Net SDK voor uw besturingssysteem.

• Een voltooiingsimplementatie van een Azure OpenAI-chat.
• Een Application Insights-exemplaar. Volg de instructies hier om een resource te maken als u er geen hebt. Kopieer de verbindingsreeks voor later gebruik.
• Python 3.10, 3.11 of 3.12 geïnstalleerd op uw computer.

Notitie

Waarneembaarheid van Semantische kernel is nog niet beschikbaar voor Java.

Instellingen

Een nieuwe consoletoepassing maken

Voer in een terminal de volgende opdracht uit om een nieuwe consoletoepassing te maken in C#:

dotnet new console -n TelemetryApplicationInsightsQuickstart

Navigeer naar de zojuist gemaakte projectmap nadat de opdracht is voltooid.

De vereiste pakketten installeren

• Semantic Kernel

  dotnet add package Microsoft.SemanticKernel
  

• OpenTelemetry Console Exporter

  dotnet add package Azure.Monitor.OpenTelemetry.Exporter
  

Een eenvoudige toepassing maken met Semantische kernel

Open het Program.cs bestand vanuit de projectmap met uw favoriete editor. We gaan een eenvoudige toepassing maken die gebruikmaakt van Semantische kernel om een prompt naar een voltooiingsmodel voor een chat te verzenden. Vervang de bestaande inhoud door de volgende code en vul de vereiste waarden voor deploymentName, endpointen apiKey:

using Azure.Monitor.OpenTelemetry.Exporter;

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 TelemetryApplicationInsightsQuickstart
{
    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);
        }
    }
}

Telemetrie toevoegen

Als u de console-app nu uitvoert, ziet u een zin waarin wordt uitgelegd waarom de lucht blauw is. Vervang de // Telemetry setup code goes here opmerking door de volgende code om de kernel via telemetrie te observeren:

// Replace the connection string with your Application Insights connection string
var connectionString = "your-application-insights-connection-string";

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

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

using var traceProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource("Microsoft.SemanticKernel*")
    .AddAzureMonitorTraceExporter(options => options.ConnectionString = connectionString)
    .Build();

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddMeter("Microsoft.SemanticKernel*")
    .AddAzureMonitorMetricExporter(options => options.ConnectionString = connectionString)
    .Build();

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

Verwijder ten slotte de opmerking bij de lijn // builder.Services.AddSingleton(loggerFactory); om de loggerfactory toe te voegen aan de opbouwfunctie.

Raadpleeg dit artikel voor meer informatie over de code voor het instellen van telemetriegegevens. Het enige verschil hier is dat we AddAzureMonitor[Trace|Metric|Log]Exporter telemetriegegevens exporteren naar Application Insights.

Een nieuwe virtuele Python-omgeving maken

python -m venv telemetry-application-insights-quickstart

Activeer de virtuele omgeving.

telemetry-application-insights-quickstart\Scripts\activate

De vereiste pakketten installeren

pip install semantic-kernel azure-monitor-opentelemetry-exporter

Een eenvoudig Python-script maken met Semantische kernel

Maak een nieuw Python-script en open het met uw favoriete editor.

Powershell

New-Item -Path telemetry_application_insights_quickstart.py -ItemType file

Bash

touch telemetry_application_insights_quickstart.py

We gaan een eenvoudig Python-script maken dat gebruikmaakt van Semantic Kernel om een prompt naar een voltooiingsmodel voor een chat te verzenden. Vervang de bestaande inhoud door de volgende code en vul de vereiste waarden voor deployment_name, endpointen api_key:

import asyncio
import logging

from azure.monitor.opentelemetry.exporter import (
    AzureMonitorLogExporter,
    AzureMonitorMetricExporter,
    AzureMonitorTraceExporter,
)

from opentelemetry._logs import set_logger_provider
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())

Telemetrie toevoegen

Omgevingsvariabelen

Raadpleeg dit artikel voor meer informatie over het instellen van de vereiste omgevingsvariabelen, zodat de kernel spans kan verzenden voor AI-connectors.

Code

Als u het script nu uitvoert, zou u een zin moeten zien waarin wordt uitgelegd waarom de hemel blauw is. Vervang de # Telemetry setup code goes here opmerking door de volgende code om de kernel via telemetrie te observeren:

# Replace the connection string with your Application Insights connection string
connection_string = "your-application-insights-connection-string"

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


def set_up_logging():
    exporter = AzureMonitorLogExporter(connection_string=connection_string)

    # 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 = AzureMonitorTraceExporter(connection_string=connection_string)

    # 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 = AzureMonitorMetricExporter(connection_string=connection_string)

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

Raadpleeg dit artikel voor meer informatie over de code voor het instellen van telemetriegegevens. Het enige verschil hier is dat we AzureMonitor[Trace|Metric|Log]Exporter telemetriegegevens exporteren naar Application Insights.

Notitie

Waarneembaarheid van Semantische kernel is nog niet beschikbaar voor Java.

Uitvoeren

Voer de consoletoepassing uit met de volgende opdracht:

dotnet run

Voer het Python-script uit met de volgende opdracht:

python telemetry_application_insights_quickstart.py

Notitie

Waarneembaarheid van Semantische kernel is nog niet beschikbaar voor Java.

Telemetriegegevens inspecteren

Nadat u de toepassing hebt uitgevoerd, gaat u naar de Application Insights-portal om de telemetriegegevens te controleren. Het kan enkele minuten duren voordat de gegevens worden weergegeven in de portal.

Transactiezoekopdracht

Navigeer naar het tabblad Transactie zoeken om de transacties weer te geven die zijn vastgelegd.

Druk op Vernieuwen om de meest recente transacties weer te geven. Wanneer de resultaten worden weergegeven, klikt u op een van deze resultaten om meer details weer te geven.

Schakelen tussen de knop Alles weergeven en Tijdlijn weergeven om alle traceringen en afhankelijkheden van de transactie in verschillende weergaven weer te geven.

Belangrijk

Traceringen vertegenwoordigen traditionele logboekvermeldingen en OpenTelemetry span-gebeurtenissen. Ze zijn niet hetzelfde als gedistribueerde traceringen. Afhankelijkheden vertegenwoordigen de aanroepen naar (interne en externe) onderdelen. Raadpleeg dit artikel voor meer informatie over het gegevensmodel in Application Insights.

Voor dit specifieke voorbeeld ziet u twee afhankelijkheden en meerdere traceringen. De eerste afhankelijkheid vertegenwoordigt een kernelfunctie die wordt gemaakt op basis van de prompt. De tweede afhankelijkheid vertegenwoordigt de aanroep van het voltooiingsmodel van de Azure OpenAI-chat. Wanneer u de chat.completion {your-deployment-name} afhankelijkheid uitvouwt, ziet u de details van de aanroep. Een set gen_ai kenmerken wordt gekoppeld aan de afhankelijkheid, wat extra context biedt over de aanroep.

Als u de schakeloptie Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnosticsSensitive hebt ingesteld true, ziet u ook twee traceringen die de gevoelige gegevens van de prompt en het voltooiingsresultaat bevatten.

Klik erop en u ziet de prompt en het voltooiingsresultaat onder de sectie aangepaste eigenschappen.

Als u de omgevingsvariabele SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE hebt ingesteld trueop, ziet u ook twee traceringen die de gevoelige gegevens van de prompt en het voltooiingsresultaat bevatten.

Klik erop en u ziet de prompt en het voltooiingsresultaat onder de sectie aangepaste eigenschappen.

Logboekanalyses

Transactiezoekopdrachten zijn niet de enige manier om telemetriegegevens te inspecteren. U kunt Log Analytics ook gebruiken om query's uit te voeren en de gegevens te analyseren. Navigeer naar de logboeken onder Bewaking om te beginnen.

Volg dit document om te beginnen met het verkennen van de Log Analytics-interface.

Hieronder vindt u enkele voorbeeldquery's die u voor dit voorbeeld kunt gebruiken:

// Retrieves the total number of completion and prompt tokens used for the model if you run the application multiple times.
dependencies
| where name startswith "chat"
| project model = customDimensions["gen_ai.request.model"], completion_token = toint(customDimensions["gen_ai.response.completion_tokens"]), prompt_token = toint(customDimensions["gen_ai.response.prompt_tokens"])
| where model == "gpt-4o"
| project completion_token, prompt_token
| summarize total_completion_tokens = sum(completion_token), total_prompt_tokens = sum(prompt_token)

// Retrieves all the prompts and completions and their corresponding token usage.
dependencies
| where name startswith "chat"
| project timestamp, operation_Id, name, completion_token = customDimensions["gen_ai.response.completion_tokens"], prompt_token = customDimensions["gen_ai.response.prompt_tokens"]
| join traces on operation_Id
| where message startswith "gen_ai"
|project timestamp, messages = customDimensions, token=iff(customDimensions contains "gen_ai.prompt", prompt_token, completion_token)

Volgende stappen

Nu u telemetriegegevens naar Application Insights hebt uitgevoerd, kunt u meer functies van Semantische kernel verkennen waarmee u uw toepassing kunt bewaken en diagnosticeren:

Geavanceerde telemetrie met Semantische kernel