使用 Aspire 仪表板检查遥测数据

项目
11/03/2024

Aspire 仪表板是 .NET Aspire 产品/服务的一部分。仪表板允许开发人员监视和检查其分布式应用程序。

在此示例中，我们将使用独立模式，并了解如何将遥测数据导出到 Aspire 仪表板，并检查其中的数据。

出口商

导出程序负责将遥测数据发送到目标。在此处阅读有关出口商的详细信息。在此示例中，我们使用 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 该文件。我们将创建一个简单的应用程序，该应用程序使用语义内核向聊天完成模型发送提示。将现有内容替换为以下代码，并填写所需的值 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); 。

有关遥测设置代码的详细信息，请参阅本文。此处的唯一区别在于，我们用于 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 脚本，该脚本使用语义内核向聊天完成模型发送提示。将现有内容替换为以下代码，并填写所需的值 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 连接器跨度的详细信息，请参阅本文。

代码

如果现在运行该脚本，应该会看到一个句子，说明天空为何为蓝色。若要通过遥测观察内核，请将 # 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 访问仪表板。

运行

使用以下命令运行控制台应用程序：

dotnet run

使用以下命令运行 Python 脚本：

python telemetry_aspire_dashboard_quickstart.py

注意

语义内核可观测性尚不适用于 Java。

检查遥测数据

运行应用程序后，转到仪表板以检查遥测数据。

提示

按照本指南了解 Aspire 仪表板界面。

Traces

如果这是在启动仪表板后首次运行应用程序，则应看到一个跟踪是 Traces 选项卡。单击跟踪可查看更多详细信息。

TracesOverview

在跟踪详细信息中，可以看到表示提示函数的跨度和表示聊天完成模型的跨度。单击聊天完成范围以查看有关请求和响应的详细信息。

提示

可以筛选范围的属性，以查找感兴趣的属性。

TracesDetails

日志

转到 Structured 选项卡以查看应用程序发出的日志。请参阅本指南，了解如何在仪表板中使用结构化日志。

后续步骤

成功将遥测数据输出到 Aspire 仪表板后，可以探索语义内核的更多功能，以帮助监视和诊断应用程序：

使用语义内核的高级遥测

通过

使用 Aspire 仪表板检查遥测数据

出口商

先决条件

安装

创建新的控制台应用程序

安装所需程序包

使用语义内核创建简单应用程序

添加遥测

创建新的 Python 虚拟环境

安装所需程序包

使用语义内核创建简单的 Python 脚本

添加遥测

环境变量

代码

启动 Aspire 仪表板

运行

检查遥测数据

Traces

日志

后续步骤

其他资源