Inspeção de dados de telemetria com o Application Insights
O Application Insights faz parte do Azure Monitor, que é uma solução abrangente para coletar, analisar e agir com base em dados de telemetria de seus ambientes locais e de nuvem. Com o Application Insights, você pode monitorar o desempenho do aplicativo, detectar e diagnosticar problemas.
Neste exemplo, aprenderemos a exportar dados de telemetria para o Application Insights e inspecionar os dados no portal do Application Insights.
Aviso
O Kernel Semântico utiliza um recurso do .NET 8 chamado serviços com chave. O Application Insights tem um problema com o registro de serviço, tornando-o incompatível com serviços chaveados. Se você estiver usando o Kernel Semântico com serviços com chave e encontrar erros inesperados relacionados à injeção de dependência do Application Insights, registre o Application Insights antes de qualquer serviço chave para resolver esse problema. Para obter mais informações, consulte microsoft/ApplicationInsights-dotnet#2879
Exportador
Os exportadores são responsáveis por enviar dados de telemetria para um destino. Leia mais sobre exportadores aqui. Neste exemplo, usamos o exportador do Azure Monitor para gerar dados de telemetria para uma instância do Application Insights.
Pré-requisitos
- Uma implantação de conclusão de chat do OpenAI do Azure.
- Uma instância do Application Insights. Siga as instruções aqui para criar um recurso, caso não tenha um. Copie a cadeia de conexão para uso posterior.
- O SDK do .Net mais recente para o seu sistema operacional.
- Uma implantação de conclusão de chat do OpenAI do Azure.
- Uma instância do Application Insights. Siga as instruções aqui para criar um recurso, caso não tenha um. Copie a cadeia de conexão para uso posterior.
- Python 3.10, 3.11 ou 3.12 instalado em sua máquina.
Observação
A observabilidade semântica do kernel ainda não está disponível para Java.
Instalação
Crie 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 TelemetryApplicationInsightsQuickstart
Navegue até o diretório do projeto recém-criado após a conclusão do comando.
Instalar os pacotes necessários
Semantic Kernel
dotnet add package Microsoft.SemanticKernelExportador de console do OpenTelemetry
dotnet add package Azure.Monitor.OpenTelemetry.Exporter
Criar um aplicativo simples com o Semantic Kernel
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 bate-papo. Substitua o conteúdo existente pelo código a seguir e preencha os valores necessários para deploymentName, endpointe 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);
}
}
}
Adicionar telemetria
Se você executar o aplicativo de console agora, deverá 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:
// 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);
});
Por fim, descomente a linha // builder.Services.AddSingleton(loggerFactory); para adicionar a fábrica de loggers ao construtor.
Consulte este artigo para obter mais informações sobre o código de configuração de telemetria. A única diferença aqui é que estamos usando AddAzureMonitor[Trace|Metric|Log]Exporter para exportar dados de telemetria para o Application Insights.
Criar um novo ambiente virtual Python
python -m venv telemetry-application-insights-quickstart
Ative o ambiente virtual.
telemetry-application-insights-quickstart\Scripts\activate
Instalar os pacotes necessários
pip install semantic-kernel azure-monitor-opentelemetry-exporter
Criar um script Python simples com o Semantic Kernel
Crie um novo script Python e abra-o com seu editor favorito.
New-Item -Path telemetry_application_insights_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 bate-papo. 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 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())
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 intervalos para conectores de IA.
Código
Se você executar o script agora, 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:
# 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()
Consulte este artigo para obter mais informações sobre o código de configuração de telemetria. A única diferença aqui é que estamos usando AzureMonitor[Trace|Metric|Log]Exporter para exportar dados de telemetria para o Application Insights.
Observação
A observabilidade semântica do kernel ainda não está disponível para Java.
Executar
Execute o aplicativo de console com o seguinte comando:
dotnet run
Execute o script Python com o seguinte comando:
python telemetry_application_insights_quickstart.py
Observação
A observabilidade semântica do kernel ainda não está disponível para Java.
Inspecionar dados de telemetria
Depois de executar o aplicativo, vá para o portal do Application Insights para inspecionar os dados de telemetria. Pode levar alguns minutos para que os dados apareçam no portal.
Pesquisa de transação
Navegue até a guia Pesquisa de transações para exibir as transações que foram registradas.
Clique em atualizar para ver as transações mais recentes. Quando os resultados aparecerem, clique em um deles para ver mais detalhes.
Alterne entre o botão Exibir tudo e Exibir linha do tempo para ver todos os rastreamentos e dependências da transação em diferentes exibições.
Importante
Os rastreamentos representam entradas de log tradicionais e eventos de intervalo do OpenTelemetry. Eles não são o mesmo que rastreamentos distribuídos. As dependências representam as chamadas para componentes (internos e externos). Consulte este artigo para obter mais informações sobre o modelo de dados no Application Insights.
Para este exemplo específico, você deve ver duas dependências e vários rastreamentos. A primeira dependência representa uma função de kernel que é criada a partir do prompt. A segunda dependência representa a chamada para o modelo de conclusão de chat do OpenAI do Azure. Ao expandir a chat.completion {your-deployment-name} dependência, você deve ver os detalhes da chamada. Um conjunto de gen_ai atributos é anexado à dependência, que fornece contexto adicional sobre a chamada.
Se você tiver a opção Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnosticsSensitive definida como true, também verá dois rastreamentos que carregam os dados confidenciais do prompt e o resultado da conclusão.
Clique neles e você verá o prompt e o resultado da conclusão na seção de propriedades personalizadas.
Se você tiver a variável SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE de ambiente definida como true, também verá dois rastreamentos que carregam os dados confidenciais do prompt e o resultado de conclusão.
Clique neles e você verá o prompt e o resultado da conclusão na seção de propriedades personalizadas.
Log Analytics
A pesquisa de transações não é a única maneira de inspecionar dados de telemetria. Você também pode usar o Log Analytics para consultar e analisar os dados. Navegue até Logs em Monitoramento para iniciar.
Siga este documento para começar a explorar a interface do Log Analytics.
Abaixo estão alguns exemplos de consultas que você pode usar para este exemplo:
// 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)
Próximas etapas
Agora que você enviou dados de telemetria com êxito para o Application Insights, pode explorar mais recursos do Kernel Semântico que podem ajudá-lo a monitorar e diagnosticar seu aplicativo: