Inspectie van telemetriegegevens met de console
Hoewel de console geen aanbevolen manier is om telemetriegegevens te inspecteren, is het een eenvoudige en snelle manier om aan de slag te gaan. In dit artikel leest u hoe u telemetriegegevens naar de console kunt uitvoeren voor inspectie met een minimale kernelinstallatie.
Exportfunctie
Exporteurs zijn verantwoordelijk voor het verzenden van telemetriegegevens naar een bestemming. Lees hier meer over exporteurs. In dit voorbeeld gebruiken we de consoleexporteur om telemetriegegevens naar de console uit te voeren.
Vereisten
- Een voltooiingsimplementatie van een Azure OpenAI-chat.
- De nieuwste .Net SDK voor uw besturingssysteem.
- Een voltooiingsimplementatie van een Azure OpenAI-chat.
- 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 TelemetryConsoleQuickstart
Navigeer naar de zojuist gemaakte projectmap nadat de opdracht is voltooid.
De vereiste pakketten installeren
Semantic Kernel
dotnet add package Microsoft.SemanticKernelOpenTelemetry Console Exporter
dotnet add package OpenTelemetry.Exporter.Console
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 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 TelemetryConsoleQuickstart
{
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:
var resourceBuilder = ResourceBuilder
.CreateDefault()
.AddService("TelemetryConsoleQuickstart");
// Enable model diagnostics with sensitive data.
AppContext.SetSwitch("Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnosticsSensitive", true);
using var traceProvider = Sdk.CreateTracerProviderBuilder()
.SetResourceBuilder(resourceBuilder)
.AddSource("Microsoft.SemanticKernel*")
.AddConsoleExporter()
.Build();
using var meterProvider = Sdk.CreateMeterProviderBuilder()
.SetResourceBuilder(resourceBuilder)
.AddMeter("Microsoft.SemanticKernel*")
.AddConsoleExporter()
.Build();
using var loggerFactory = LoggerFactory.Create(builder =>
{
// Add OpenTelemetry as a logging provider
builder.AddOpenTelemetry(options =>
{
options.SetResourceBuilder(resourceBuilder);
options.AddConsoleExporter();
// 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.
In het bovenstaande codefragment maken we eerst een resourcebouwer voor het bouwen van resource-exemplaren. Een resource vertegenwoordigt de entiteit die telemetriegegevens produceert. Hier vindt u meer informatie over resources. De opbouwfunctie voor resources voor de providers is optioneel. Als deze niet is opgegeven, wordt de standaardresource met standaardkenmerken gebruikt.
Vervolgens schakelen we diagnostische gegevens in met gevoelige gegevens. Dit is een experimentele functie waarmee u diagnostische gegevens voor de AI-services in de Semantische kernel kunt inschakelen. Als dit is ingeschakeld, ziet u aanvullende telemetriegegevens, zoals de prompts die worden verzonden naar en de antwoorden die zijn ontvangen van de AI-modellen, die als gevoelige gegevens worden beschouwd. Als u geen gevoelige gegevens in uw telemetrie wilt opnemen, kunt u een andere schakeloptie Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnostics gebruiken om diagnostische gegevens in te schakelen met niet-gevoelige gegevens, zoals de modelnaam, de bewerkingsnaam en het gebruik van tokens, enzovoort.
Vervolgens maken we een tracerproviderbouwer en een meterproviderbouwer. Een provider is verantwoordelijk voor het verwerken van telemetriegegevens en het doorsluizen naar exporteurs. We abonneren ons op de Microsoft.SemanticKernel* bron om telemetriegegevens te ontvangen van de Semantische Kernel-naamruimten. We voegen een consoleexporteur toe aan zowel de tracerprovider als de meterprovider. De consoleexporteur verzendt telemetriegegevens naar de console.
Ten slotte maken we een logger factory en voegen we OpenTelemetry toe als een logboekprovider waarmee logboekgegevens naar de console worden verzonden. We stellen het minimale logboekniveau Information in op opgemaakte berichten en bereiken in de logboekuitvoer. De loggerfabriek wordt vervolgens toegevoegd aan de opbouwfunctie.
Belangrijk
Een provider moet een singleton zijn en moet actief zijn voor de hele levensduur van de toepassing. De provider moet worden verwijderd wanneer de toepassing wordt afgesloten.
Een nieuwe virtuele Python-omgeving maken
python -m venv telemetry-console-quickstart
Activeer de virtuele omgeving.
telemetry-console-quickstart\Scripts\activate
De vereiste pakketten installeren
pip install semantic-kernel
Een eenvoudig Python-script maken met Semantische kernel
Maak een nieuw Python-script en open het met uw favoriete editor.
New-Item -Path telemetry_console_quickstart.py -ItemType file
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 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, ConsoleLogExporter
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import ConsoleMetricExporter, 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, ConsoleSpanExporter
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
Standaard verzendt de kernel geen spanten voor de AI-connectors, omdat deze bereiken kenmerken bevatten gen_ai die als experimenteel worden beschouwd. Als u de functie wilt inschakelen, stelt u de omgevingsvariabele SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS in of SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE op true.
Belangrijk
Prompts en voltooiingen worden beschouwd als gevoelige gegevens. Semantische kernel verzendt deze gegevens niet van de AI-connectors, tenzij de SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE omgevingsvariabele is ingesteld op true. Als u dit true insteltSEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS, worden alleen niet-gevoelige gegevens verzonden, zoals de modelnaam, de naam van de bewerking en het tokengebruik.
Maak een nieuw bestand met de naam .env in dezelfde map als uw script en voeg de volgende inhoud toe:
SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE=true
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:
# Create a resource to represent the service/sample
resource = Resource.create({ResourceAttributes.SERVICE_NAME: "telemetry-console-quickstart"})
def set_up_logging():
exporter = ConsoleLogExporter()
# 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 = ConsoleSpanExporter()
# 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 = ConsoleMetricExporter()
# 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()
In het bovenstaande codefragment maken we eerst een resource die de service vertegenwoordigt. Een resource vertegenwoordigt de entiteit die telemetriegegevens produceert. Hier vindt u meer informatie over resources. Vervolgens maken we drie functies voor het instellen van logboekregistratie, tracering en metrische gegevens. Elke functie maakt een provider voor de respectieve telemetriegegevens en voegt een consoleexporteur toe aan de provider.
Ten slotte roepen we de drie functies aan om logboekregistratie, tracering en metrische gegevens in te stellen. Dit moet worden gedaan voordat andere telemetrie-aanroepen worden uitgevoerd.
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_console_quickstart.py
Notitie
Waarneembaarheid van Semantische kernel is nog niet beschikbaar voor Java.
Telemetriegegevens inspecteren
Logboekrecords
U ziet nu meerdere logboekrecords in de console-uitvoer. Ze zien er ongeveer als volgt uit:
LogRecord.Timestamp: 2024-09-12T21:48:35.2295938Z
LogRecord.TraceId: 159d3f07664838f6abdad7af6a892cfa
LogRecord.SpanId: ac79a006da8a6215
LogRecord.TraceFlags: Recorded
LogRecord.CategoryName: Microsoft.SemanticKernel.KernelFunction
LogRecord.Severity: Info
LogRecord.SeverityText: Information
LogRecord.FormattedMessage: Function InvokePromptAsync_290eb9bece084b00aea46b569174feae invoking.
LogRecord.Body: Function {FunctionName} invoking.
LogRecord.Attributes (Key:Value):
FunctionName: InvokePromptAsync_290eb9bece084b00aea46b569174feae
OriginalFormat (a.k.a Body): Function {FunctionName} invoking.
Resource associated with LogRecord:
service.name: TelemetryConsoleQuickstart
service.instance.id: a637dfc9-0e83-4435-9534-fb89902e64f8
telemetry.sdk.name: opentelemetry
telemetry.sdk.language: dotnet
telemetry.sdk.version: 1.9.0
Er zijn twee onderdelen voor elke logboekrecord:
- De logboekrecord zelf: bevat de tijdstempel en naamruimte waarop de logboekrecord is gegenereerd, de ernst en hoofdtekst van de logboekrecord en eventuele kenmerken die zijn gekoppeld aan de logboekrecord.
- De resource die is gekoppeld aan de logboekrecord: bevat informatie over de service, het exemplaar en de SDK die wordt gebruikt om de logboekrecord te genereren.
Activiteiten
Notitie
Activiteiten in .Net zijn vergelijkbaar met spans in OpenTelemetry. Ze worden gebruikt om een werkeenheid in de toepassing weer te geven.
U ziet nu meerdere activiteiten in de console-uitvoer. Ze zien er ongeveer als volgt uit:
Activity.TraceId: 159d3f07664838f6abdad7af6a892cfa
Activity.SpanId: 8c7c79bc1036eab3
Activity.TraceFlags: Recorded
Activity.ParentSpanId: ac79a006da8a6215
Activity.ActivitySourceName: Microsoft.SemanticKernel.Diagnostics
Activity.DisplayName: chat.completions gpt-4o
Activity.Kind: Client
Activity.StartTime: 2024-09-12T21:48:35.5717463Z
Activity.Duration: 00:00:02.3992014
Activity.Tags:
gen_ai.operation.name: chat.completions
gen_ai.system: openai
gen_ai.request.model: gpt-4o
gen_ai.response.prompt_tokens: 16
gen_ai.response.completion_tokens: 29
gen_ai.response.finish_reason: Stop
gen_ai.response.id: chatcmpl-A6lxz14rKuQpQibmiCpzmye6z9rxC
Activity.Events:
gen_ai.content.prompt [9/12/2024 9:48:35 PM +00:00]
gen_ai.prompt: [{"role": "user", "content": "Why is the sky blue in one sentence?"}]
gen_ai.content.completion [9/12/2024 9:48:37 PM +00:00]
gen_ai.completion: [{"role": "Assistant", "content": "The sky appears blue because shorter blue wavelengths of sunlight are scattered in all directions by the gases and particles in the Earth\u0027s atmosphere more than other colors."}]
Resource associated with Activity:
service.name: TelemetryConsoleQuickstart
service.instance.id: a637dfc9-0e83-4435-9534-fb89902e64f8
telemetry.sdk.name: opentelemetry
telemetry.sdk.language: dotnet
telemetry.sdk.version: 1.9.0
Er zijn twee onderdelen voor elke activiteit:
- De activiteit zelf: bevat de span-id en bovenliggende span-id die APM-hulpprogramma's gebruiken om de traceringen, de duur van de activiteit en eventuele tags en gebeurtenissen die zijn gekoppeld aan de activiteit te bouwen.
- De resource die is gekoppeld aan de activiteit: bevat informatie over de service, het exemplaar en de SDK die wordt gebruikt om de activiteit te genereren.
Belangrijk
De kenmerken waaraan u extra aandacht moet besteden, zijn de kenmerken waarmee u begint gen_ai. Dit zijn de kenmerken die zijn opgegeven in de GenAI Semantic Conventions.
Metrische gegevens
U ziet nu meerdere metrische records in de console-uitvoer. Ze zien er ongeveer als volgt uit:
Metric Name: semantic_kernel.connectors.openai.tokens.prompt, Number of prompt tokens used, Unit: {token}, Meter: Microsoft.SemanticKernel.Connectors.OpenAI
(2024-09-12T21:48:37.9531072Z, 2024-09-12T21:48:38.0966737Z] LongSum
Value: 16
Hier ziet u de naam, de beschrijving, de eenheid, het tijdsbereik, het type, de waarde van de metrische waarde en de meter waartoe de metrische waarde behoort.
Notitie
De bovenstaande metrische waarde is een metrische waarde voor tellers. Zie hier voor een volledige lijst met metrische typen. Afhankelijk van het type metrische waarde kan de uitvoer variëren.
Logboeken
U ziet nu meerdere logboekrecords in de console-uitvoer. Ze zien er ongeveer als volgt uit:
{
"body": "Function SyVCcBjaULqEhItH invoking.",
"severity_number": "<SeverityNumber.INFO: 9>",
"severity_text": "INFO",
"attributes": {
"code.filepath": "C:\\tmp\\telemetry-console-quickstart\\Lib\\site-packages\\semantic_kernel\\functions\\kernel_function_log_messages.py",
"code.function": "log_function_invoking",
"code.lineno": 19
},
"dropped_attributes": 0,
"timestamp": "2024-09-13T17:55:45.504983Z",
"observed_timestamp": "2024-09-13T17:55:45.504983Z",
"trace_id": "0xe23e2c10785ea61ffc9f28be19482a80",
"span_id": "0x686bd592e27661d7",
"trace_flags": 1,
"resource": {
"attributes": {
"telemetry.sdk.language": "python",
"telemetry.sdk.name": "opentelemetry",
"telemetry.sdk.version": "1.27.0",
"service.name": "telemetry-console-quickstart"
},
"schema_url": ""
}
}
Spans
Als het goed is, ziet u meerdere spans in de console-uitvoer. Ze zien er ongeveer als volgt uit:
{
"name": "chat.completions gpt-4o",
"context": {
"trace_id": "0xe23e2c10785ea61ffc9f28be19482a80",
"span_id": "0x8b20e9655610c3c9",
"trace_state": "[]"
},
"kind": "SpanKind.INTERNAL",
"parent_id": "0x686bd592e27661d7",
"start_time": "2024-09-13T17:55:45.515198Z",
"end_time": "2024-09-13T17:55:46.469471Z",
"status": {
"status_code": "UNSET"
},
"attributes": {
"gen_ai.operation.name": "chat.completions",
"gen_ai.system": "openai",
"gen_ai.request.model": "gpt-4o",
"gen_ai.response.id": "chatcmpl-A74oD7WGDjawnZ44SJZrj9fKrEv1B",
"gen_ai.response.finish_reason": "FinishReason.STOP",
"gen_ai.response.prompt_tokens": 16,
"gen_ai.response.completion_tokens": 29
},
"events": [
{
"name": "gen_ai.content.prompt",
"timestamp": "2024-09-13T17:55:45.515198Z",
"attributes": {
"gen_ai.prompt": "[{\"role\": \"user\", \"content\": \"Why is the sky blue in one sentence?\"}]"
}
},
{
"name": "gen_ai.content.completion",
"timestamp": "2024-09-13T17:55:46.469471Z",
"attributes": {
"gen_ai.completion": "[{\"role\": \"assistant\", \"content\": \"The sky appears blue because shorter blue wavelengths of sunlight are scattered in all directions by the molecules and particles in the atmosphere more effectively than other colors.\"}]"
}
}
],
"links": [],
"resource": {
"attributes": {
"telemetry.sdk.language": "python",
"telemetry.sdk.name": "opentelemetry",
"telemetry.sdk.version": "1.27.0",
"service.name": "telemetry-console-quickstart"
},
"schema_url": ""
}
}
Let op de kenmerken waarmee u begint gen_ai. Dit zijn de kenmerken die zijn opgegeven in de GenAI Semantic Conventions. Ze bieden nuttige informatie over de aanvragen die worden verzonden naar en de antwoorden die zijn ontvangen van de AI-modellen.
Metrische gegevens
U ziet nu meerdere metrische records in de console-uitvoer. Ze zien er ongeveer als volgt uit:
{
"resource_metrics": [
{
"resource": {
"attributes": {
"telemetry.sdk.language": "python",
"telemetry.sdk.name": "opentelemetry",
"telemetry.sdk.version": "1.27.0",
"service.name": "telemetry-console-quickstart"
},
"schema_url": ""
},
"scope_metrics": [
{
"scope": {
"name": "semantic_kernel.functions.kernel_function",
"version": null,
"schema_url": "",
"attributes": null
},
"metrics": [
{
"name": "semantic_kernel.function.invocation.duration",
"description": "Measures the duration of a function's execution",
"unit": "s",
"data": {
"data_points": [
{
"attributes": {
"semantic_kernel.function.name": "SyVCcBjaULqEhItH"
},
"start_time_unix_nano": 1726250146470468300,
"time_unix_nano": 1726250146478526600,
"count": 1,
"sum": 0.9650602999900002,
"bucket_counts": [
0,
1,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
"explicit_bounds": [
0.0,
5.0,
10.0,
25.0,
50.0,
75.0,
100.0,
250.0,
500.0,
750.0,
1000.0,
2500.0,
5000.0,
7500.0,
10000.0
],
"min": 0.9650602999900002,
"max": 0.9650602999900002
}
],
"aggregation_temporality": 2
}
}
],
"schema_url": ""
}
],
"schema_url": ""
}
]
}
De bovenstaande meting is een metrische histogram. Zie hier voor een volledige lijst met metrische typen.
Notitie
Waarneembaarheid van Semantische kernel is nog niet beschikbaar voor Java.
Volgende stappen
Nu u telemetriegegevens naar de console hebt uitgevoerd, kunt u meer informatie krijgen over het gebruik van APM-hulpprogramma's voor het visualiseren en analyseren van telemetriegegevens.