Überprüfung von Telemetriedaten mit der Konsole
Obwohl die Konsole keine empfohlene Methode zum Überprüfen von Telemetriedaten ist, ist dies eine einfache und schnelle Methode für die ersten Schritte. In diesem Artikel erfahren Sie, wie Sie Telemetriedaten zur Überprüfung mit einem minimalen Kernelsetup an die Konsole ausgeben.
Exporteur
Exporteure sind für das Senden von Telemetriedaten an ein Ziel verantwortlich. Weitere Informationen zu Exporteuren finden Sie hier. In diesem Beispiel verwenden wir den Konsolenexporteur, um Telemetriedaten an die Konsole auszugeben.
Voraussetzungen
- Bereitstellung eines Azure OpenAI-Chats.
- Das neueste .Net SDK für Ihr Betriebssystem.
- Bereitstellung eines Azure OpenAI-Chats.
- Python 3.10, 3.11 oder 3.12 auf Ihrem Computer installiert.
Hinweis
Die semantische Kernel-Observability ist für Java noch nicht verfügbar.
Setup
Erstellen einer neuen Konsolenanwendung
Führen Sie in einem Terminal den folgenden Befehl aus, um eine neue Konsolenanwendung in C# zu erstellen:
dotnet new console -n TelemetryConsoleQuickstart
Navigieren Sie nach Abschluss des Befehls zum neu erstellten Projektverzeichnis.
Installieren erforderlicher Pakete
Semantischer Kernel
dotnet add package Microsoft.SemanticKernelOpenTelemetry Console Exporter
dotnet add package OpenTelemetry.Exporter.Console
Erstellen einer einfachen Anwendung mit semantischem Kernel
Öffnen Sie die Program.cs Datei im Projektverzeichnis mit Ihrem bevorzugten Editor. Wir werden eine einfache Anwendung erstellen, die semantischen Kernel verwendet, um eine Eingabeaufforderung an ein Chatabschlussmodell zu senden. Ersetzen Sie den vorhandenen Inhalt durch den folgenden Code, und füllen Sie die erforderlichen Werte für deploymentName, endpointund 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 hinzufügen
Wenn Sie die Konsolen-App jetzt ausführen, sollten Sie einen Satz sehen, der erklärt, warum der Himmel blau ist. Um den Kernel über Telemetrie zu beobachten, ersetzen Sie den // Telemetry setup code goes here Kommentar durch den folgenden Code:
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);
});
Entfernen Sie abschließend die Auskommentierung der Zeile // builder.Services.AddSingleton(loggerFactory); , um dem Generator die Loggerfabrik hinzuzufügen.
Im obigen Codeausschnitt erstellen wir zuerst einen Ressourcen-Generator zum Erstellen von Ressourceninstanzen. Eine Ressource stellt die Entität dar, die Telemetriedaten erzeugt. Weitere Informationen zu Ressourcen finden Sie hier. Der Ressourcen-Generator für die Anbieter ist optional. Wenn nicht angegeben, wird die Standardressource mit Standardattributen verwendet.
Als Nächstes aktivieren wir die Diagnose mit vertraulichen Daten. Dies ist ein experimentelles Feature, mit dem Sie die Diagnose für die KI-Dienste im semantischen Kernel aktivieren können. Wenn diese Option aktiviert ist, werden zusätzliche Telemetriedaten angezeigt, z. B. die an die GESENDETen Eingabeaufforderungen und die antworten, die von den KI-Modellen empfangen werden, die als vertrauliche Daten betrachtet werden. Wenn Sie keine vertraulichen Daten in Ihre Telemetrie einbeziehen möchten, können Sie einen anderen Schalter Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnostics verwenden, um diagnosen mit nicht vertraulichen Daten wie dem Modellnamen, dem Vorgangsnamen und der Tokenverwendung usw. zu aktivieren.
Anschließend erstellen wir einen Tracer-Anbieter-Generator und einen Meter-Anbieter-Generator. Ein Anbieter ist für die Verarbeitung von Telemetriedaten und die Weitergabe an Exporteure verantwortlich. Wir abonnieren die Microsoft.SemanticKernel* Quelle, um Telemetriedaten aus den Namespaces des semantischen Kernels zu empfangen. Wir fügen sowohl dem Traceranbieter als auch dem Meteranbieter einen Konsolenexporteur hinzu. Der Konsolenexporteur sendet Telemetriedaten an die Konsole.
Schließlich erstellen wir eine Loggerfactory und fügen OpenTelemetry als Protokollierungsanbieter hinzu, der Protokolldaten an die Konsole sendet. Wir legen die minimale Protokollebene auf Information und enthalten formatierte Nachrichten und Bereiche in die Protokollausgabe. Die Loggerfabrik wird dann dem Generator hinzugefügt.
Wichtig
Ein Anbieter sollte ein Singleton sein und für die gesamte Anwendungslebensdauer aktiv sein. Der Anbieter sollte gelöscht werden, wenn die Anwendung heruntergefahren wird.
Erstellen einer neuen virtuellen Python-Umgebung
python -m venv telemetry-console-quickstart
Aktivieren Sie die virtuelle Umgebung.
telemetry-console-quickstart\Scripts\activate
Installieren erforderlicher Pakete
pip install semantic-kernel
Erstellen eines einfachen Python-Skripts mit semantischem Kernel
Erstellen Sie ein neues Python-Skript, und öffnen Sie es mit Ihrem bevorzugten Editor.
New-Item -Path telemetry_console_quickstart.py -ItemType file
Wir werden ein einfaches Python-Skript erstellen, das semantic Kernel verwendet, um eine Eingabeaufforderung an ein Chatabschlussmodell zu senden. Ersetzen Sie den vorhandenen Inhalt durch den folgenden Code, und füllen Sie die erforderlichen Werte für deployment_name, endpointund 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 hinzufügen
Umgebungsvariablen
Standardmäßig gibt der Kernel keine Spanne für die KI-Connectors aus, da diese Spanne Attribute tragen gen_ai , die als experimentell betrachtet werden. Um das Feature zu aktivieren, legen Sie die Umgebungsvariable SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS oder SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE auf .true
Wichtig
Aufforderungen und Vervollständigungen gelten als vertrauliche Daten. Der semantische Kernel gibt diese Daten nicht von den KI-Connectors aus, es sei denn, die SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE Umgebungsvariable ist auf truefestgelegt. Die Einstellung SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS auf true gibt nur nicht vertrauliche Daten aus, z. B. den Modellnamen, den Vorgangsnamen und die Tokenverwendung.
Erstellen Sie eine neue Datei, die im selben Verzeichnis wie Ihr Skript benannt .env ist, und fügen Sie den folgenden Inhalt hinzu:
SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE=true
Code
Wenn Sie das Skript jetzt ausführen, sollten Sie erwarten, dass sie einen Satz sehen, der erklärt, warum der Himmel blau ist. Um den Kernel über Telemetrie zu beobachten, ersetzen Sie den # Telemetry setup code goes here Kommentar durch den folgenden Code:
# 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()
Im obigen Codeausschnitt erstellen wir zuerst eine Ressource, die den Dienst darstellt. Eine Ressource stellt die Entität dar, die Telemetriedaten erzeugt. Weitere Informationen zu Ressourcen finden Sie hier. Anschließend erstellen wir drei Funktionen zum Einrichten von Protokollierung, Ablaufverfolgung und Metriken. Jede Funktion erstellt einen Anbieter für die jeweiligen Telemetriedaten und fügt dem Anbieter einen Konsolenexporteur hinzu.
Schließlich rufen wir die drei Funktionen auf, um Protokollierung, Ablaufverfolgung und Metriken einzurichten. Dies muss vor anderen Telemetrieanrufen erfolgen.
Hinweis
Die semantische Kernel-Observability ist für Java noch nicht verfügbar.
Ausführung
Führen Sie die Konsolenanwendung mit dem folgenden Befehl aus:
dotnet run
Führen Sie das Python-Skript mit dem folgenden Befehl aus:
python telemetry_console_quickstart.py
Hinweis
Die semantische Kernel-Observability ist für Java noch nicht verfügbar.
Überprüfen von Telemetriedaten
Protokolldatensätze
In der Konsolenausgabe sollten mehrere Protokolleinträge angezeigt werden. Sie sehen ähnlich wie folgt aus:
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
Es gibt zwei Teile für jeden Protokolldatensatz:
- Der Protokolldatensatz selbst: enthält den Zeitstempel und den Namespace, bei dem der Protokolldatensatz generiert wurde, den Schweregrad und den Text des Protokolldatensatzes sowie alle Attribute, die dem Protokolldatensatz zugeordnet sind.
- Die dem Protokolldatensatz zugeordnete Ressource enthält Informationen zum Dienst, zur Instanz und zum SDK zum Generieren des Protokolldatensatzes.
Aktivitäten
Hinweis
Aktivitäten in .Net ähneln sich in OpenTelemetry. Sie werden verwendet, um eine Arbeitseinheit in der Anwendung darzustellen.
In der Konsolenausgabe sollten mehrere Aktivitäten angezeigt werden. Sie sehen ähnlich wie folgt aus:
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
Es gibt zwei Teile für jede Aktivität:
- Die Aktivität selbst: enthält die Span-ID und die übergeordnete Span-ID, die APM-Tools verwenden, um die Ablaufverfolgungen, die Dauer der Aktivität und alle Tags und Ereignisse zu erstellen, die der Aktivität zugeordnet sind.
- Die ressource, die der Aktivität zugeordnet ist: enthält Informationen über den Dienst, die Instanz und das SDK, die zum Generieren der Aktivität verwendet werden.
Wichtig
Die Attribute, denen sie besondere Aufmerksamkeit schenken sollen, sind die Attribute, die mit gen_ai. Dies sind die Attribute, die in den GenAI-Semantikkonventionen angegeben sind.
Metriken
In der Konsolenausgabe sollten mehrere Metrikdatensätze angezeigt werden. Sie sehen ähnlich wie folgt aus:
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 sehen Sie den Namen, die Beschreibung, die Einheit, den Zeitbereich, den Typ, den Wert der Metrik und den Zähler, zu dem die Metrik gehört.
Protokolle
In der Konsolenausgabe sollten mehrere Protokolleinträge angezeigt werden. Sie sehen ähnlich wie folgt aus:
{
"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": ""
}
}
Span-Eigenschaften
In der Konsolenausgabe sollten mehrere Spannen angezeigt werden. Sie sehen ähnlich wie folgt aus:
{
"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": ""
}
}
Achten Sie auf die Attribute, die mit gen_ai. Dies sind die Attribute, die in den GenAI-Semantikkonventionen angegeben sind. Sie liefern nützliche Informationen zu den Anforderungen, die an die KI-Modelle gesendet werden, und die Antworten, die von den KI-Modellen erhalten wurden.
Metriken
In der Konsolenausgabe sollten mehrere Metrikdatensätze angezeigt werden. Sie sehen ähnlich wie folgt aus:
{
"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": ""
}
]
}
Die oben gezeigte Messung ist eine Histogrammmetrik. Eine vollständige Liste der Metriktypen finden Sie hier.
Hinweis
Die semantische Kernel-Observability ist für Java noch nicht verfügbar.
Nächste Schritte
Nachdem Sie nun Telemetriedaten erfolgreich an die Konsole ausgegeben haben, erfahren Sie mehr darüber, wie Sie APM-Tools zum Visualisieren und Analysieren von Telemetriedaten verwenden.