Поделиться через

Проверка данных телеметрии с помощью консоли

Хотя консоль не рекомендуется проверять данные телеметрии, это простой и быстрый способ приступить к работе. В этой статье показано, как выводить данные телеметрии в консоль для проверки с минимальными параметрами ядра.

Экспортер

Экспортеры отвечают за отправку данных телеметрии в место назначения. Дополнительные сведения о экспортерах см. здесь. В этом примере мы используем экспортер консоли для вывода данных телеметрии в консоль.

Необходимые компоненты

  • Развертывание завершения чата Azure OpenAI.
  • Последний пакет SDK для .Net для операционной системы.
  • Развертывание завершения чата Azure OpenAI.
  • Python 3.10, 3.11 или 3.12 , установленный на компьютере.

Примечание.

Наблюдаемость семантического ядра пока недоступна для Java.

Настройка

Создание нового консольного приложения

В терминале выполните следующую команду, чтобы создать консольное приложение в C#:

dotnet new console -n TelemetryConsoleQuickstart

Перейдите в только что созданный каталог проекта после завершения команды.

Установка необходимых пакетов

  • Семантическое ядро

    dotnet add package Microsoft.SemanticKernel

  • Экспортер консоли OpenTelemetry

    dotnet add package OpenTelemetry.Exporter.Console

Создание простого приложения с помощью семантического ядра

В каталоге проекта откройте Program.cs файл с любимым редактором. Мы создадим простое приложение, использующее семантические ядра для отправки запроса в модель завершения чата. Замените существующее содержимое следующим кодом и введите необходимые значения для deploymentName, endpointи 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);
        }
    }
}

Добавление телеметрии

Если вы запускаете консольное приложение сейчас, вы должны увидеть предложение, объясняющее, почему небо синее. Чтобы наблюдать за ядром с помощью телеметрии, замените // Telemetry setup code goes here комментарий следующим кодом:

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);
});

Наконец, раскомментируйте строку // builder.Services.AddSingleton(loggerFactory); , чтобы добавить фабрику ведения журнала в построитель.

В приведенном выше фрагменте кода мы сначала создадим построитель ресурсов для создания экземпляров ресурсов. Ресурс представляет сущность, которая создает данные телеметрии. Дополнительные сведения о ресурсах см. здесь. Построитель ресурсов для поставщиков необязателен. Если это не указано, используется ресурс по умолчанию с атрибутами по умолчанию.

Затем мы включите диагностика с конфиденциальными данными. Это экспериментальная функция, которая позволяет включить диагностика для служб ИИ в семантическом ядре. При этом вы увидите дополнительные данные телеметрии, такие как запросы, отправленные и полученные от моделей ИИ ответы, которые считаются конфиденциальными данными. Если вы не хотите включать конфиденциальные данные в данные телеметрии, можно использовать другой параметр Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnostics для включения диагностика с нечувствительными данными, такими как имя модели, имя операции и использование маркеров и т. д.

Затем мы создадим построитель поставщиков трассировки и построитель поставщиков счетчиков. Поставщик отвечает за обработку данных телеметрии и передачу ее экспортерам. Мы подписываемся на Microsoft.SemanticKernel* источник для получения данных телеметрии из пространств имен семантического ядра. Мы добавим экспортер консоли как к поставщику трассировки, так и к поставщику счетчиков. Экспортер консоли отправляет данные телеметрии в консоль.

Наконец, мы создадим фабрику средства ведения журнала и добавим OpenTelemetry в качестве поставщика ведения журнала, который отправляет данные журнала в консоль. Мы устанавливаем минимальный уровень Information журнала и включаем форматированные сообщения и области в выходные данные журнала. Затем фабрика средства ведения журнала добавляется в построитель.

Внимание

Поставщик должен быть одним и должен быть жив в течение всего времени существования приложения. Поставщик должен быть удален при завершении работы приложения.

Создание виртуальной среды Python

python -m venv telemetry-console-quickstart

Включите виртуальную среду.

telemetry-console-quickstart\Scripts\activate

Установка необходимых пакетов

pip install semantic-kernel

Создание простого скрипта Python с помощью семантического ядра

Создайте скрипт Python и откройте его с помощью избранного редактора.

New-Item -Path telemetry_console_quickstart.py -ItemType file

Мы создадим простой скрипт Python, использующий семантический ядро для отправки запроса в модель завершения чата. Замените существующее содержимое следующим кодом и введите необходимые значения для deployment_name, endpointи 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())

Добавление телеметрии

Переменные среды

По умолчанию ядро не выдает диапазоны соединителей ИИ, так как эти диапазоны несут gen_ai атрибуты, которые считаются экспериментальными. Чтобы включить эту функцию, задайте переменную SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS среды или SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE значение true.

Внимание

Запросы и завершения считаются конфиденциальными данными. Семантические ядра не будут выдавать эти данные из соединителей ИИ, если SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE переменная среды не задана true. Параметр SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS будет true выдавать только не конфиденциальные данные, такие как имя модели, имя операции и использование маркеров.

Создайте файл с именем .env в том же каталоге, что и сценарий, и добавьте следующее содержимое:

SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE=true

Код

Если вы запускаете скрипт сейчас, вы должны ожидать, чтобы увидеть предложение, объясняющее, почему небо синее. Чтобы наблюдать за ядром с помощью телеметрии, замените # Telemetry setup code goes here комментарий следующим кодом:

# 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()

В приведенном выше фрагменте кода сначала создадим ресурс для представления службы. Ресурс представляет сущность, которая создает данные телеметрии. Дополнительные сведения о ресурсах см. здесь. Затем мы создадим три функции для настройки ведения журнала, трассировки и метрик. Каждая функция создает поставщика для соответствующих данных телеметрии и добавляет экспортер консоли к поставщику.

Наконец, мы вызываем три функции для настройки ведения журнала, трассировки и метрик. Это необходимо сделать до любых других вызовов телеметрии.

Примечание.

Наблюдаемость семантического ядра пока недоступна для Java.

Выполнить

Запустите консольное приложение с помощью следующей команды:

dotnet run

Запустите скрипт Python со следующей командой:

python telemetry_console_quickstart.py

Примечание.

Наблюдаемость семантического ядра пока недоступна для Java.

Проверка данных телеметрии

Записи журнала

В выходных данных консоли должно отображаться несколько записей журнала. Они выглядят примерно так:

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

Для каждой записи журнала существует две части:

  • Сама запись журнала: содержит метку времени и пространство имен, в котором была создана запись журнала, серьезность и текст записи журнала, а также любые атрибуты, связанные с записью журнала.
  • Ресурс, связанный с записью журнала: содержит сведения о службе, экземпляре и пакете SDK, используемом для создания записи журнала.

Процедуры

Примечание.

Действия в .Net похожи на диапазоны в OpenTelemetry. Они используются для представления единицы работы в приложении.

В выходных данных консоли должно отображаться несколько действий. Они выглядят примерно так:

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

Для каждого действия существует две части:

  • Само действие: содержит идентификатор диапазона и родительский идентификатор диапазона, используемые средствами APM для создания трассировок, длительности действия и любых тегов и событий, связанных с действием.
  • Ресурс, связанный с действием: содержит сведения о службе, экземпляре и пакете SDK, используемом для создания действия.

Внимание

Атрибуты, которые следует обратить на дополнительное внимание, — это те, с которых начинаются gen_ai. Это атрибуты, указанные в семантических соглашениях GenAI.

Метрики

В выходных данных консоли должно отображаться несколько записей метрик. Они выглядят примерно так:

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

Здесь можно увидеть имя, описание, единицу, диапазон времени, тип, значение метрики и счетчик, к которому принадлежит метрика.

Примечание.

Выше приведенная выше метрика — это метрика счетчика. Полный список типов метрик см . здесь. В зависимости от типа метрики выходные данные могут отличаться.

Журналы

В выходных данных консоли должно отображаться несколько записей журнала. Они выглядят примерно так:

{
    "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": ""
    }
}

Диапазоны

В выходных данных консоли должно отображаться несколько диапазонов. Они выглядят примерно так:

{
    "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": ""
    }
}

Обратите внимание на атрибуты, начинающиеся с gen_ai. Это атрибуты, указанные в семантических соглашениях GenAI. Они предоставляют полезную информацию о отправленных запросах и ответах, полученных от моделей ИИ.

Метрики

В выходных данных консоли должно отображаться несколько записей метрик. Они выглядят примерно так:

{
    "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": ""
        }
    ]
}

Показанное выше измерение является метрикой гистограммы. Полный список типов метрик см . здесь.

Примечание.

Наблюдаемость семантического ядра пока недоступна для Java.

Следующие шаги

Теперь, когда вы успешно выводите данные телеметрии в консоль, вы можете узнать больше о том, как использовать средства APM для визуализации и анализа данных телеметрии.

Аналитика приложений