コンソールを使用したテレメトリ データの検査
コンソールは、テレメトリ データを検査するための推奨される方法ではありませんが、簡単かつ迅速に開始できます。 この記事では、最小限のカーネル セットアップで検査のためにテレメトリ データをコンソールに出力する方法について説明します。
輸出者
エクスポーターは、テレメトリ データを送信先に送信する役割を担います。 エクスポーターの詳細については、 こちらを参照してください。 この例では、コンソール エクスポーターを使用して、テレメトリ データをコンソールに出力します。
前提条件
- Azure OpenAI チャット完了のデプロイ。
- オペレーティング システム用の最新の .Net SDK 。
- Azure OpenAI チャット完了のデプロイ。
- Python 3.10、3.11、または 3.12 コンピューターにインストールされています。
Note
セマンティック カーネルの可観測性は、Java ではまだ使用できません。
セットアップ
新しいコンソール アプリケーションを作成する
ターミナルで次のコマンドを実行して、C# で新しいコンソール アプリケーションを作成します。
dotnet new console -n TelemetryConsoleQuickstart
コマンドの完了後、新しく作成されたプロジェクト ディレクトリに移動します。
必要なパッケージをインストールする
セマンティック カーネル
dotnet add package Microsoft.SemanticKernelOpenTelemetry コンソール エクスポーター
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); のコメントを解除して、ロガー ファクトリをビルダーに追加します。
上記のコード スニペットでは、最初にリソース インスタンスを構築するためのリソース ビルダーを作成します。 リソースは、テレメトリ データを生成するエンティティを表します。 リソースの詳細については、 こちらを参照してください。 プロバイダーへのリソース ビルダーは省略可能です。 指定しない場合は、既定の属性を持つ既定のリソースが使用されます。
次に、機密データを使用して診断を有効にします。 これは、セマンティック カーネルで AI サービスの診断を有効にできる実験的な機能です。 これを有効にすると、送信されたプロンプトや AI モデルから受信した応答など、機密データと見なされる追加のテレメトリ データが表示されます。 テレメトリに機密データを含めない場合は、別の切り替え 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())
テレメトリを追加する
環境変数
既定では、カーネルは AI コネクタのスパンを出力しません。これらのスパンには試験段階と見なされる属性 gen_ai 含まれているためです。 この機能を有効にするには、環境変数の SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS または SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE を trueに設定します。
重要
プロンプトと入力候補は機密データと見なされます。 セマンティック カーネルは、 SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE 環境変数が true に設定されていない限り、これらのデータを AI コネクタから出力しません。 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()
上記のコード スニペットでは、最初にサービスを表すリソースを作成します。 リソースは、テレメトリ データを生成するエンティティを表します。 リソースの詳細については、 こちらを参照してください。 次に、ログ記録、トレース、メトリックを設定する 3 つの関数を作成します。 各関数は、それぞれのテレメトリ データのプロバイダーを作成し、プロバイダーにコンソール エクスポーターを追加します。
最後に、3 つの関数を呼び出して、ログ記録、トレース、メトリックを設定します。 これは、他のテレメトリ呼び出しの前に行う必要があります。
Note
セマンティック カーネルの可観測性は、Java ではまだ使用できません。
[ファイル名を指定して実行]
次のコマンドを使用してコンソール アプリケーションを実行します。
dotnet run
次のコマンドを使用して Python スクリプトを実行します。
python telemetry_console_quickstart.py
Note
セマンティック カーネルの可観測性は、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
各ログ レコードには、次の 2 つの部分があります。
- ログ レコード自体: ログ レコードが生成されたタイムスタンプと名前空間、ログ レコードの重大度と本文、およびログ レコードに関連付けられている属性が含まれます。
- ログ レコードに関連付けられているリソース: ログ レコードの生成に使用されるサービス、インスタンス、SDK に関する情報が含まれます。
アクティビティ
Note
.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
各アクティビティには、次の 2 つの部分があります。
- アクティビティ自体: APM ツールがトレースの構築に使用するスパン ID と親スパン ID、アクティビティの期間、およびアクティビティに関連付けられているすべてのタグとイベントが含まれます。
- アクティビティに関連付けられているリソース: アクティビティの生成に使用されるサービス、インスタンス、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
ここでは、名前、説明、単位、時間範囲、種類、メトリックの値、メトリックが属しているメーターを確認できます。
Note
上記のメトリックはカウンター メトリックです。 メトリックの種類の完全な一覧については、 こちらを参照してください。 メトリックの種類によっては、出力が異なる場合があります。
ログ
コンソール出力に複数のログ レコードが表示されます。 これらは次のようになります。
{
"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 セマンティック規則で指定された属性です。 送信された要求と、AI モデルから受信した応答に関する有用な情報を提供します。
メトリック
コンソール出力に複数のメトリック レコードが表示されます。 これらは次のようになります。
{
"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": ""
}
]
}
上記の測定値はヒストグラム メトリックです。 メトリックの種類の完全な一覧については、 こちらを参照してください。
Note
セマンティック カーネルの可観測性は、Java ではまだ使用できません。
次のステップ
テレメトリ データをコンソールに正常に出力できたので、APM ツールを使用してテレメトリ データを視覚化および分析する方法の詳細を学習できます。