アスパイアダッシュボードを使用したテレメトリデータの検査

[アーティクル]
11/03/2024

アスパイアダッシュボードは、 .NET のオファリングの一部です。ダッシュボードを使用すると、開発者は分散アプリケーションを監視および検査できます。

この例では、 standalone モードを使用しテレメトリデータをアスパイアダッシュボードにエクスポートし、そこでデータを検査する方法について説明します。

輸出者

エクスポーターは、テレメトリデータを送信先に送信する役割を担います。エクスポーターの詳細については、こちらを参照してください。この例では、 OpenTelemetry Protocol (OTLP) エクスポーターを使用して、テレメトリデータをアスパイアダッシュボードに送信します。

前提条件

Azure OpenAI チャット完了のデプロイ。
Docker
オペレーティングシステム用の最新の .Net SDK 。

Azure OpenAI チャット完了のデプロイ。
Docker
Python 3.10、3.11、または 3.12 コンピューターにインストールされています。

Note

セマンティックカーネルの可観測性は、Java ではまだ使用できません。

セットアップ

新しいコンソールアプリケーションを作成する

ターミナルで次のコマンドを実行して、C# で新しいコンソールアプリケーションを作成します。

dotnet new console -n TelemetryAspireDashboardQuickstart

コマンドの完了後、新しく作成されたプロジェクトディレクトリに移動します。

必要なパッケージをインストールする

セマンティックカーネル

dotnet add package Microsoft.SemanticKernel

OpenTelemetry コンソールエクスポーター

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

セマンティックカーネルを使用して単純なアプリケーションを作成する

プロジェクトディレクトリから、お気に入りのエディターで 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 TelemetryAspireDashboardQuickstart
{
    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 コメントを次のコードに置き換えます。

// Endpoint to the Aspire Dashboard
var endpoint = "http://localhost:4317";

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService("TelemetryAspireDashboardQuickstart");

// Enable model diagnostics with sensitive data.
AppContext.SetSwitch("Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnosticsSensitive", true);

using var traceProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource("Microsoft.SemanticKernel*")
    .AddOtlpExporter(options => options.Endpoint = new Uri(endpoint))
    .Build();

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddMeter("Microsoft.SemanticKernel*")
    .AddOtlpExporter(options => options.Endpoint = new Uri(endpoint))
    .Build();

using var loggerFactory = LoggerFactory.Create(builder =>
{
    // Add OpenTelemetry as a logging provider
    builder.AddOpenTelemetry(options =>
    {
        options.SetResourceBuilder(resourceBuilder);
        options.AddOtlpExporter(options => options.Endpoint = new Uri(endpoint));
        // Format log messages. This is default to false.
        options.IncludeFormattedMessage = true;
        options.IncludeScopes = true;
    });
    builder.SetMinimumLevel(LogLevel.Information);
});

最後に、行 // builder.Services.AddSingleton(loggerFactory); のコメントを解除して、ロガーファクトリをビルダーに追加します。

テレメトリのセットアップコードの詳細については、この article を参照してください。ここでの唯一の違いは、 AddOtlpExporter を使用してテレメトリデータをアスパイアダッシュボードにエクスポートしていることです。

新しい Python 仮想環境を作成する

python -m venv telemetry-aspire-dashboard-quickstart

仮想環境をアクティブにします。

telemetry-aspire-dashboard-quickstart\Scripts\activate

必要なパッケージをインストールする

pip install semantic-kernel opentelemetry-exporter-otlp-proto-grpc

セマンティックカーネルを使用して単純な Python スクリプトを作成する

新しい Python スクリプトを作成し、お気に入りのエディターで開きます。

Powershell
Bash

New-Item -Path telemetry_aspire_dashboard_quickstart.py -ItemType file

touch telemetry_aspire_dashboard_quickstart.py

セマンティックカーネルを使用してチャット完了モデルにプロンプトを送信する単純な Python スクリプトを作成します。既存のコンテンツを次のコードに置き換え、 deployment_name、 endpoint、および api_keyに必要な値を入力します。

import asyncio
import logging

from opentelemetry._logs import set_logger_provider
from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.metrics import set_meter_provider
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import 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
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())

テレメトリを追加する

環境変数

カーネルが AI コネクタのスパンを出力できるようにするために必要な環境変数を設定する方法の詳細については、この article を参照してください。

コード

ここでスクリプトを実行すると、空が青い理由を説明する文が表示されます。テレメトリを使用してカーネルを観察するには、 # Telemetry setup code goes here コメントを次のコードに置き換えます。

# Endpoint to the Aspire Dashboard
endpoint = "http://localhost:4317"

# Create a resource to represent the service/sample
resource = Resource.create({ResourceAttributes.SERVICE_NAME: "telemetry-aspire-dashboard-quickstart"})


def set_up_logging():
    exporter = OTLPLogExporter(endpoint=endpoint)

    # 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 = OTLPSpanExporter(endpoint=endpoint)

    # 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 = OTLPMetricExporter(endpoint=endpoint)

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

テレメトリのセットアップコードの詳細については、この article を参照してください。ここでの唯一の違いは、 OTLP[Span|Metric|Log]Exporter を使用してテレメトリデータをアスパイアダッシュボードにエクスポートしていることです。

Note

セマンティックカーネルの可観測性は、Java ではまだ使用できません。

アスパイアダッシュボードを開始する

ここに指示に従ってダッシュボードを起動します。ダッシュボードが実行されたら、ブラウザーを開き、 http://localhost:18888 に移動してダッシュボードにアクセスします。

[ファイル名を指定して実行]

次のコマンドを使用してコンソールアプリケーションを実行します。

dotnet run

次のコマンドを使用して Python スクリプトを実行します。

python telemetry_aspire_dashboard_quickstart.py

Note

セマンティックカーネルの可観測性は、Java ではまだ使用できません。

テレメトリデータを検査する

アプリケーションを実行したら、ダッシュボードに進み、テレメトリデータを調べます。

ヒント

この guide に従って、アスパイアダッシュボードインターフェイスを探索します。

トレース

ダッシュボードの起動後にアプリケーションを初めて実行する場合は、1 つのトレースが [ Traces ] タブに表示されます。トレースをクリックすると、詳細が表示されます。

TracesOverview

トレースの詳細では、プロンプト関数を表すスパンと、チャット完了モデルを表すスパンを確認できます。チャット完了スパンをクリックすると、要求と応答に関する詳細が表示されます。

ヒント

スパンの属性をフィルター処理して、関心のある属性を見つけることができます。

TracesDetails

ログ

[ Structured ] タブに移動して、アプリケーションによって出力されたログを表示します。ダッシュボードで構造化されたログを操作する方法については、こちらの guide を参照してください。

次のステップ

テレメトリデータをアスパイアダッシュボードに正常に出力できたので、アプリケーションの監視と診断に役立つセマンティックカーネルのその他の機能を確認できます。

セマンティックカーネルを使用した高度なテレメトリ

次の方法で共有

アスパイアダッシュボードを使用したテレメトリデータの検査

輸出者

前提条件

セットアップ

新しいコンソールアプリケーションを作成する

必要なパッケージをインストールする

セマンティックカーネルを使用して単純なアプリケーションを作成する

テレメトリを追加する

新しい Python 仮想環境を作成する

必要なパッケージをインストールする

セマンティックカーネルを使用して単純な Python スクリプトを作成する

テレメトリを追加する

環境変数

コード

アスパイアダッシュボードを開始する

[ファイル名を指定して実行]

テレメトリデータを検査する

トレース

ログ

次のステップ

その他のリソース

次の方法で共有

アスパイア ダッシュボードを使用したテレメトリ データの検査

輸出者

前提条件

セットアップ

新しいコンソール アプリケーションを作成する

必要なパッケージをインストールする

セマンティック カーネルを使用して単純なアプリケーションを作成する

テレメトリを追加する

新しい Python 仮想環境を作成する

必要なパッケージをインストールする

セマンティック カーネルを使用して単純な Python スクリプトを作成する

テレメトリを追加する

環境変数

コード

アスパイア ダッシュボードを開始する

[ファイル名を指定して実行]

テレメトリ データを検査する

トレース

ログ

次のステップ

その他のリソース

アスパイアダッシュボードを使用したテレメトリデータの検査

新しいコンソールアプリケーションを作成する

セマンティックカーネルを使用して単純なアプリケーションを作成する

セマンティックカーネルを使用して単純な Python スクリプトを作成する

アスパイアダッシュボードを開始する

テレメトリデータを検査する