使用 Aspire 儀錶板檢查遙測數據

發行項
11/03/2024

Aspire 儀錶板是 .NET Aspire 供應專案的一部分。儀錶板可讓開發人員監視及檢查其分散式應用程式。

在此範例中，我們將使用獨立模式，並瞭解如何將遙測數據導出至 Aspire 儀錶板，並檢查該處的數據。

Exporter

匯出者負責將遙測數據傳送至目的地。在這裡深入了解導出者。在此範例中，我們使用 OpenTelemetry 通訊協定（OTLP）導出工具將遙測數據傳送至 Aspire 儀錶板。

必要條件

Azure OpenAI 聊天完成部署。
Docker
您作業系統的最新 .Net SDK 。

Azure OpenAI 聊天完成部署。
Docker
計算機上安裝 Python 3.10、3.11 或 3.12 。

注意

Java 尚未提供語意核心可觀察性。

設定

建立新的主控台應用程式

在終端機中，執行下列命令以在 C# 中建立新的控制台應用程式：

dotnet new console -n TelemetryAspireDashboardQuickstart

在命令完成之後，流覽至新建立的項目目錄。

安裝必要的套件

語意核心

dotnet add package Microsoft.SemanticKernel

OpenTelemetry 控制台導出工具

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

使用語意核心建立簡單的應用程式

從項目目錄，使用您慣用的編輯器開啟 Program.cs 檔案。我們將建立使用 Semantic Kernel 將提示傳送至聊天完成模型的簡單應用程式。以下列程式代碼取代現有的內容，並填入、 endpoint和 apiKey的必要值deploymentName：

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); 記錄器處理站新增至產生器。

如需遙測設定程式碼的詳細資訊，請參閱這篇文章。這裡唯一的差別在於，我們用來 AddOtlpExporter 將遙測數據導出至 Aspire 儀錶板。

建立新的 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 腳本。以下列程式代碼取代現有的內容，並填入、 endpoint和 api_key的必要值deployment_name：

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 連接器範圍的詳細資訊，請參閱這篇文章。

代碼

如果您現在執行腳本，您應該會看到一個句子，說明天空為何為藍色。若要透過遙測觀察核心，請使用下列程式代碼取代 # 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()

如需遙測設定程式碼的詳細資訊，請參閱這篇文章。這裡唯一的差別在於，我們用來 OTLP[Span|Metric|Log]Exporter 將遙測數據導出至 Aspire 儀錶板。

注意

Java 尚未提供語意核心可觀察性。

啟動 Aspire 儀錶板

請遵循這裡的指示來啟動儀錶板。儀錶板執行之後，請開啟瀏覽器並流覽至 http://localhost:18888 以存取儀錶板。

Run

使用下列命令執行主控台應用程式：

dotnet run

使用下列命令執行 Python 文稿：

python telemetry_aspire_dashboard_quickstart.py

注意

Java 尚未提供語意核心可觀察性。

檢查遙測數據

執行應用程式之後，請前往儀錶板來檢查遙測數據。

提示

請遵循本指南來探索 Aspire 儀錶板介面。

追蹤

如果這是您在啟動儀錶板之後第一次執行應用程式，您應該會看到一個追蹤是 Traces 索引卷標。按兩下追蹤以檢視更多詳細數據。

TracesOverview

在追蹤詳細數據中，您可以看到代表提示函式的跨度，以及代表聊天完成模型的範圍。按兩下聊天完成範圍，以查看要求和回應的詳細數據。

提示

您可以篩選範圍的屬性，以尋找您感興趣的屬性。

TracesDetails

記錄

前往索引 Structured 標籤，以檢視應用程式發出的記錄。請參閱本指南，以瞭解如何在儀錶板中使用結構化記錄。

下一步

既然您已順利將遙測數據輸出至 Aspire 儀錶板，您可以探索更多語意核心功能，以協助您監視和診斷應用程式：

使用語意核心的進階遙測

共用方式為

使用 Aspire 儀錶板檢查遙測數據

Exporter

必要條件

設定

建立新的主控台應用程式

安裝必要的套件

使用語意核心建立簡單的應用程式

新增遙測

建立新的 Python 虛擬環境

安裝必要的套件

使用語意核心建立簡單的 Python 腳本

新增遙測

環境變數

代碼

啟動 Aspire 儀錶板

Run

檢查遙測數據

追蹤

記錄

下一步

其他資源