Inspekcja danych telemetrycznych za pomocą konsoli
Chociaż konsola nie jest zalecanym sposobem inspekcji danych telemetrycznych, jest to prosty i szybki sposób rozpoczęcia pracy. W tym artykule przedstawiono sposób wyprowadzania danych telemetrycznych do konsoli w celu przeprowadzenia inspekcji przy użyciu minimalnej konfiguracji jądra.
Eksporter
Eksporterzy są odpowiedzialni za wysyłanie danych telemetrycznych do miejsca docelowego. Przeczytaj więcej na temat eksporterów tutaj. W tym przykładzie używamy eksportera konsoli do wyprowadzania danych telemetrycznych do konsoli.
Wymagania wstępne
- Wdrożenie uzupełniania czatu usługi Azure OpenAI.
- Najnowszy zestaw .Net SDK dla systemu operacyjnego.
- Wdrożenie uzupełniania czatu usługi Azure OpenAI.
- Na maszynie jest zainstalowany język Python 3.10, 3.11 lub 3.12 .
Uwaga
Możliwość obserwowania jądra semantycznego nie jest jeszcze dostępna dla języka Java.
Ustawienia
Tworzenie nowej aplikacji konsolowej
W terminalu uruchom następujące polecenie, aby utworzyć nową aplikację konsolową w języku C#:
dotnet new console -n TelemetryConsoleQuickstart
Przejdź do nowo utworzonego katalogu projektu po zakończeniu wykonywania polecenia.
Instalowanie wymaganych pakietów
Jądro semantyczne
dotnet add package Microsoft.SemanticKernelEksporter konsoli OpenTelemetry
dotnet add package OpenTelemetry.Exporter.Console
Tworzenie prostej aplikacji za pomocą jądra semantycznego
W katalogu projektu otwórz plik za pomocą ulubionego Program.cs edytora. Utworzymy prostą aplikację, która używa jądra semantycznego do wysyłania monitu do modelu uzupełniania czatu. Zastąp istniejącą zawartość następującym kodem i wypełnij wymagane wartości dla deploymentName, endpointi 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);
}
}
}
Dodawanie telemetrii
Jeśli teraz uruchomisz aplikację konsolową, należy oczekiwać zdania wyjaśniającego, dlaczego niebo jest niebieskie. Aby obserwować jądro za pośrednictwem telemetrii, zastąp // Telemetry setup code goes here komentarz następującym kodem:
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);
});
Na koniec usuń komentarz z wiersza // builder.Services.AddSingleton(loggerFactory); , aby dodać fabrykę rejestratora do konstruktora.
W powyższym fragmencie kodu najpierw utworzymy konstruktora zasobów na potrzeby tworzenia wystąpień zasobów. Zasób reprezentuje jednostkę, która generuje dane telemetryczne. Więcej informacji o zasobach można znaleźć tutaj. Konstruktor zasobów dla dostawców jest opcjonalny. Jeśli nie zostanie podany, zostanie użyty domyślny zasób z atrybutami domyślnymi.
Następnie włączamy diagnostykę z danymi poufnymi. Jest to funkcja eksperymentalna, która umożliwia włączenie diagnostyki dla usług sztucznej inteligencji w semantycznym jądrze. Po włączeniu tej funkcji zostaną wyświetlone dodatkowe dane telemetryczne, takie jak monity wysyłane do i odpowiedzi odebrane z modeli sztucznej inteligencji, które są uznawane za poufne dane. Jeśli nie chcesz uwzględniać poufnych danych w telemetrii, możesz użyć innego przełącznika Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnostics , aby włączyć diagnostykę z danymi niewrażliwymi, takimi jak nazwa modelu, nazwa operacji i użycie tokenu itp.
Następnie utworzymy konstruktor dostawcy śledzenia i konstruktor dostawcy miernika. Dostawca jest odpowiedzialny za przetwarzanie danych telemetrycznych i potokowanie ich do eksporterów. Subskrybujemy źródło w Microsoft.SemanticKernel* celu odbierania danych telemetrycznych z przestrzeni nazw jądra semantycznego. Dodamy eksportera konsoli zarówno do dostawcy tracer, jak i dostawcy miernika. Eksporter konsoli wysyła dane telemetryczne do konsoli.
Na koniec utworzymy fabrykę rejestratora i dodamy usługę OpenTelemetry jako dostawcę rejestrowania, który wysyła dane dziennika do konsoli. Ustawiamy minimalny poziom dziennika na Information i uwzględniamy sformatowane komunikaty i zakresy w danych wyjściowych dziennika. Fabryka rejestratora jest następnie dodawana do konstruktora.
Ważne
Dostawca powinien być pojedynczy i powinien być aktywny przez cały okres istnienia aplikacji. Dostawca powinien być usuwany po zamknięciu aplikacji.
Tworzenie nowego środowiska wirtualnego języka Python
python -m venv telemetry-console-quickstart
Aktywuj środowisko wirtualne.
telemetry-console-quickstart\Scripts\activate
Instalowanie wymaganych pakietów
pip install semantic-kernel
Tworzenie prostego skryptu języka Python za pomocą jądra semantycznego
Utwórz nowy skrypt języka Python i otwórz go za pomocą ulubionego edytora.
New-Item -Path telemetry_console_quickstart.py -ItemType file
Utworzymy prosty skrypt języka Python, który używa jądra semantycznego do wysyłania monitu do modelu uzupełniania czatu. Zastąp istniejącą zawartość następującym kodem i wypełnij wymagane wartości dla deployment_name, endpointi 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())
Dodawanie telemetrii
Zmienne środowiskowe
Domyślnie jądro nie emituje zakresów dla łączników sztucznej inteligencji, ponieważ obejmują one atrybuty gen_ai , które są uznawane za eksperymentalne. Aby włączyć tę funkcję, ustaw zmienną środowiskową SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS lub SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE na truewartość .
Ważne
Monity i zakończenia są uznawane za poufne dane. Semantyczne jądro nie będzie emitować tych danych z łączników sztucznej inteligencji, chyba że zmienna SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE środowiskowa jest ustawiona na truewartość . Ustawienie SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS na będzie true emitować tylko dane niewrażliwe, takie jak nazwa modelu, nazwa operacji i użycie tokenu.
Utwórz nowy plik o nazwie .env w tym samym katalogu co skrypt i dodaj następującą zawartość:
SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE=true
Kod
Jeśli teraz uruchomisz skrypt, należy oczekiwać zdania wyjaśniającego, dlaczego niebo jest niebieskie. Aby obserwować jądro za pośrednictwem telemetrii, zastąp # Telemetry setup code goes here komentarz następującym kodem:
# 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()
W powyższym fragmencie kodu najpierw utworzymy zasób reprezentujący usługę. Zasób reprezentuje jednostkę, która generuje dane telemetryczne. Więcej informacji o zasobach można znaleźć tutaj. Następnie utworzymy trzy funkcje, aby skonfigurować rejestrowanie, śledzenie i metryki. Każda funkcja tworzy dostawcę odpowiednich danych telemetrycznych i dodaje eksportera konsoli do dostawcy.
Na koniec wywołujemy trzy funkcje, aby skonfigurować rejestrowanie, śledzenie i metryki. Należy to zrobić przed wszelkimi innymi wywołaniami telemetrii.
Uwaga
Możliwość obserwowania jądra semantycznego nie jest jeszcze dostępna dla języka Java.
Uruchom
Uruchom aplikację konsolową za pomocą następującego polecenia:
dotnet run
Uruchom skrypt języka Python za pomocą następującego polecenia:
python telemetry_console_quickstart.py
Uwaga
Możliwość obserwowania jądra semantycznego nie jest jeszcze dostępna dla języka Java.
Inspekcja danych telemetrycznych
Rekordy dziennika
W danych wyjściowych konsoli powinien zostać wyświetlonych wiele rekordów dziennika. Wyglądają one podobnie do następujących:
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
Istnieją dwie części do każdego rekordu dziennika:
- Sam rekord dziennika: zawiera sygnaturę czasową i przestrzeń nazw, w której został wygenerowany rekord dziennika, ważność i treść rekordu dziennika oraz wszelkie atrybuty skojarzone z rekordem dziennika.
- Zasób skojarzony z rekordem dziennika: zawiera informacje o usłudze, wystąpieniu i zestawie SDK używanym do generowania rekordu dziennika.
Działania
Uwaga
Działania na platformie .Net są podobne do zakresów w technologii OpenTelemetry. Są one używane do reprezentowania jednostki pracy w aplikacji.
W danych wyjściowych konsoli powinien zostać wyświetlonych wiele działań. Wyglądają one podobnie do następujących:
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żde działanie obejmuje dwie części:
- Samo działanie: zawiera identyfikator zakresu i identyfikator zakresu nadrzędnego używany przez narzędzia APM do tworzenia śladów, czasu trwania działania oraz wszelkich tagów i zdarzeń skojarzonych z działaniem.
- Zasób skojarzony z działaniem: zawiera informacje o usłudze, wystąpieniu i zestawie SDK używanym do generowania działania.
Ważne
Atrybuty, które należy zwrócić szczególną uwagę, to te, które zaczynają się od gen_ai. Są to atrybuty określone w konwencjach semantycznych GenAI.
Metryki
W danych wyjściowych konsoli powinien zostać wyświetlonych wiele rekordów metryk. Wyglądają one podobnie do następujących:
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
W tym miejscu można zobaczyć nazwę, opis, jednostkę, zakres czasu, typ, wartość metryki i miernik, do którego należy metryka.
Uwaga
Powyższa metryka jest metryką Licznik. Aby uzyskać pełną listę typów metryk, zobacz tutaj. W zależności od typu metryki dane wyjściowe mogą się różnić.
Dzienniki
W danych wyjściowych konsoli powinien zostać wyświetlonych wiele rekordów dziennika. Wyglądają one podobnie do następujących:
{
"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": ""
}
}
Obejmuje
W danych wyjściowych konsoli powinien zostać wyświetlonych wiele zakresów. Wyglądają one podobnie do następujących:
{
"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": ""
}
}
Zwróć uwagę na atrybuty rozpoczynające się od gen_ai. Są to atrybuty określone w konwencjach semantycznych GenAI. Udostępniają przydatne informacje o żądaniach wysyłanych do i odpowiedzi odebranych z modeli sztucznej inteligencji.
Metryki
W danych wyjściowych konsoli powinien zostać wyświetlonych wiele rekordów metryk. Wyglądają one podobnie do następujących:
{
"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": ""
}
]
}
Miara pokazana powyżej jest metryką histogramu. Aby uzyskać pełną listę typów metryk, zobacz tutaj.
Uwaga
Możliwość obserwowania jądra semantycznego nie jest jeszcze dostępna dla języka Java.
Następne kroki
Teraz, gdy dane telemetryczne zostały pomyślnie wyjściowe do konsoli, możesz dowiedzieć się więcej na temat używania narzędzi APM do wizualizacji i analizowania danych telemetrycznych.