Kontrola telemetrických dat pomocí konzoly
I když konzola není doporučeným způsobem kontroly telemetrických dat, je to jednoduchý a rychlý způsob, jak začít. V tomto článku se dozvíte, jak exportovat telemetrická data do konzoly pro kontrolu s minimálním nastavením jádra.
Vývozce
Exportéři zodpovídají za odesílání telemetrických dat do cíle. Přečtěte si další informace o vývozcích zde. V tomto příkladu použijeme exportér konzoly k výstupu telemetrických dat do konzoly.
Požadavky
- Nasazení dokončení chatu Azure OpenAI
- Nejnovější sada .NET SDK pro váš operační systém.
- Nasazení dokončení chatu Azure OpenAI
- Na počítači je nainstalovaný Python 3.10, 3.11 nebo 3.12 .
Poznámka:
Sémantická pozorovatelnost jádra zatím není pro Javu k dispozici.
Nastavení
Vytvoření nové konzolové aplikace
Spuštěním následujícího příkazu v terminálu vytvořte novou konzolovou aplikaci v jazyce C#:
dotnet new console -n TelemetryConsoleQuickstart
Po dokončení příkazu přejděte do nově vytvořeného adresáře projektu.
Instalace požadovaných balíčků
Sémantické jádro
dotnet add package Microsoft.SemanticKernelExportér konzoly OpenTelemetry
dotnet add package OpenTelemetry.Exporter.Console
Vytvoření jednoduché aplikace pomocí sémantického jádra
V adresáři projektu otevřete Program.cs soubor v oblíbeném editoru. Vytvoříme jednoduchou aplikaci, která používá sémantické jádro k odeslání výzvy do modelu dokončování chatu. Nahraďte stávající obsah následujícím kódem a vyplňte požadované hodnoty pro deploymentName, endpointa 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);
}
}
}
Přidání telemetrie
Pokud teď spustíte konzolovou aplikaci, měli byste očekávat větu s vysvětlením, proč je obloha modrá. Pokud chcete sledovat jádro prostřednictvím telemetrie, nahraďte // Telemetry setup code goes here komentář následujícím kódem:
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);
});
Nakonec odkomentujte řádek // builder.Services.AddSingleton(loggerFactory); pro přidání objektu pro protokolování do tvůrce.
Ve výše uvedeném fragmentu kódu nejprve vytvoříme tvůrce prostředků pro vytváření instancí prostředků. Prostředek představuje entitu, která vytváří telemetrická data. Další informace o zdrojích najdete tady. Tvůrce prostředků pro poskytovatele je volitelný. Pokud není zadaný, použije se výchozí prostředek s výchozími atributy.
Dále zapneme diagnostiku s citlivými daty. Toto je experimentální funkce, která umožňuje povolit diagnostiku pro služby AI v sémantickém jádru. Když je tato funkce zapnutá, zobrazí se další telemetrická data, jako jsou výzvy odeslané do modelů AI a odpovědi přijaté z modelů AI, které jsou považovány za citlivá data. Pokud nechcete do telemetrie zahrnout citlivá data, můžete pomocí jiného přepínače Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnostics povolit diagnostiku s necitlivými daty, jako je název modelu, název operace a použití tokenu atd.
Pak vytvoříme tvůrce zprostředkovatele trasování a tvůrce zprostředkovatele měřiče. Poskytovatel zodpovídá za zpracování telemetrických dat a jejich propojení s exportéry. Přihlásíme se ke Microsoft.SemanticKernel* zdroji, abychom mohli přijímat telemetrická data z oborů názvů sémantického jádra. K poskytovateli traceru i poskytovateli měřiče přidáme vývozce konzoly. Exportér konzoly odešle do konzoly telemetrická data.
Nakonec vytvoříme objekt pro protokolování a jako zprostředkovatele protokolování přidáme OpenTelemetry, který do konzoly odesílá data protokolů. Minimální úroveň protokolu nastavíme na Information formátované zprávy a obory a zahrneme do výstupu protokolu. Objekt pro vytváření protokolovacího nástroje se pak přidá do tvůrce.
Důležité
Zprostředkovatel by měl být singleton a měl by být aktivní po celou dobu životnosti aplikace. Poskytovatel by měl být uvolněn při vypnutí aplikace.
Vytvoření nového virtuálního prostředí Pythonu
python -m venv telemetry-console-quickstart
Aktivujte virtuální prostředí.
telemetry-console-quickstart\Scripts\activate
Instalace požadovaných balíčků
pip install semantic-kernel
Vytvoření jednoduchého skriptu Pythonu s sémantickým jádrem
Vytvořte nový skript Pythonu a otevřete ho v oblíbeném editoru.
New-Item -Path telemetry_console_quickstart.py -ItemType file
Vytvoříme jednoduchý skript Pythonu, který používá sémantické jádro k odeslání výzvy do modelu dokončování chatu. Nahraďte stávající obsah následujícím kódem a vyplňte požadované hodnoty pro deployment_name, endpointa 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())
Přidání telemetrie
Proměnné prostředí
Ve výchozím nastavení jádro nevysílají rozsahy pro konektory AI, protože tyto rozsahy obsahují gen_ai atributy, které jsou považovány za experimentální. Chcete-li tuto funkci povolit, nastavte proměnnou SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS prostředí nebo SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE na truehodnotu .
Důležité
Výzvy a dokončení se považují za citlivá data. Sémantické jádro nebude generovat tato data z konektorů AI, pokud SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE není proměnná prostředí nastavena na truehodnotu . Nastavení SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS , které true bude generovat pouze necitlivá data, jako je název modelu, název operace a použití tokenu.
Vytvořte nový soubor s názvem .env ve stejném adresáři jako váš skript a přidejte následující obsah:
SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE=true
Kód
Pokud skript spustíte teď, měli byste očekávat, že uvidíte větu s vysvětlením, proč je obloha modrá. Pokud chcete sledovat jádro prostřednictvím telemetrie, nahraďte # Telemetry setup code goes here komentář následujícím kódem:
# 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()
Ve výše uvedeném fragmentu kódu nejprve vytvoříme prostředek, který bude představovat službu. Prostředek představuje entitu, která vytváří telemetrická data. Další informace o zdrojích najdete tady. Pak vytvoříme tři funkce pro nastavení protokolování, trasování a metrik. Každá funkce vytvoří zprostředkovatele pro příslušná telemetrická data a přidá do poskytovatele vývozce konzoly.
Nakonec zavoláme tři funkce, které nastaví protokolování, trasování a metriky. To se musí provést před všemi dalšími voláními telemetrie.
Poznámka:
Sémantická pozorovatelnost jádra zatím není pro Javu k dispozici.
Spustit
Spusťte konzolovou aplikaci pomocí následujícího příkazu:
dotnet run
Spusťte skript Pythonu pomocí následujícího příkazu:
python telemetry_console_quickstart.py
Poznámka:
Sémantická pozorovatelnost jádra zatím není pro Javu k dispozici.
Kontrola telemetrických dat
Záznamy protokolu
Ve výstupu konzoly by se mělo zobrazit více záznamů protokolu. Vypadají nějak takto:
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
Každý záznam protokolu má dvě části:
- Samotný záznam protokolu: obsahuje časové razítko a obor názvů, ve kterém byl záznam protokolu generován, závažnost a tělo záznamu protokolu a všechny atributy přidružené k záznamu protokolu.
- Prostředek přidružený k záznamu protokolu: obsahuje informace o službě, instanci a sadě SDK použité k vygenerování záznamu protokolu.
Aktivity
Poznámka:
Aktivity v .Net se podobají rozsahům v OpenTelemetry. Slouží k reprezentaci jednotky práce v aplikaci.
Ve výstupu konzoly by se mělo zobrazit více aktivit. Vypadají nějak takto:
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
Každá aktivita má dvě části:
- Samotná aktivita obsahuje ID rozsahu a ID nadřazeného rozsahu, které nástroje APM používají k sestavení trasování, doby trvání aktivity a všech značek a událostí přidružených k aktivitě.
- Prostředek přidružený k aktivitě: obsahuje informace o službě, instanci a sadě SDK použité k vygenerování aktivity.
Důležité
Atributy, které je třeba věnovat zvláštní pozornost, jsou ty, které začínají gen_ai. Jedná se o atributy zadané v sémantických konvencích GenAI.
Metriky
Ve výstupu konzoly by se mělo zobrazit více záznamů metrik. Vypadají nějak takto:
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
Tady můžete vidět název, popis, jednotku, časový rozsah, typ, hodnotu metriky a měřič, ke kterému metrika patří.
Poznámka:
Výše uvedená metrika je metrika čítače. Úplný seznam typů metrik najdete tady. Výstup se může lišit v závislosti na typu metriky.
Protokoly
Ve výstupu konzoly by se mělo zobrazit více záznamů protokolu. Vypadají nějak takto:
{
"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": ""
}
}
Rozpětí
Ve výstupu konzoly by se mělo zobrazit více rozsahů. Vypadají nějak takto:
{
"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": ""
}
}
Věnujte pozornost atributům, které začínají gen_ai. Jedná se o atributy zadané v sémantických konvencích GenAI. Poskytují užitečné informace o požadavcích odeslaných do modelů AI a odpovědích přijatých z modelů AI.
Metriky
Ve výstupu konzoly by se mělo zobrazit více záznamů metrik. Vypadají nějak takto:
{
"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": ""
}
]
}
Měření zobrazené výše je metrika histogramu. Úplný seznam typů metrik najdete tady.
Poznámka:
Sémantická pozorovatelnost jádra zatím není pro Javu k dispozici.
Další kroky
Teď, když máte úspěšně výstupní telemetrická data do konzoly, můžete se dozvědět více o tom, jak pomocí nástrojů APM vizualizovat a analyzovat telemetrická data.