使用 Application Insights 檢查遙測數據

發行項
01/14/2025

Application Insights 是 Azure 監視器的一部分，這是收集、分析及處理來自雲端和內部部署環境的遙測數據的完整解決方案。透過 Application Insights，您可以監視應用程式的效能、偵測問題，以及診斷問題。

在此範例中，我們將瞭解如何將遙測數據導出至 Application Insights，並在 Application Insights 入口網站中檢查數據。

警告

語意核心會利用稱為索引鍵服務的 .NET 8 功能。 Application Insights 與服務註冊有問題，使其與密鑰服務不相容。如果您正在使用語意核心搭配索引鍵服務，並遇到與 Application Insights 的依賴注入相關的非預期錯誤，您應先註冊 Application Insights，再註冊任何索引鍵服務來解決此問題。如需詳細資訊，請參閱 microsoft/ApplicationInsights-dotnet#2879

Exporter

匯出者負責將遙測數據傳送至目的地。在這裡深入了解導出者。在此範例中，我們使用 Azure 監視器匯出工具將遙測數據輸出至 Application Insights 實例。

必要條件

Azure OpenAI 聊天完成部署。
Application Insights 執行個體。如果您沒有資源，請遵循這裡的指示來建立資源。複製連接字串以供稍後使用。
您作業系統的最新 .Net SDK 。

Azure OpenAI 聊天完成部署。
Application Insights 執行個體。如果您沒有資源，請遵循這裡的指示來建立資源。複製連接字串以供稍後使用。
計算機上安裝 Python 3.10、3.11 或 3.12 。

注意

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

設定

建立新的主控台應用程式

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

dotnet new console -n TelemetryApplicationInsightsQuickstart

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

安裝必要的套件

語意核心

dotnet add package Microsoft.SemanticKernel

OpenTelemetry 控制台導出工具

dotnet add package Azure.Monitor.OpenTelemetry.Exporter

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

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

using Azure.Monitor.OpenTelemetry.Exporter;

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 TelemetryApplicationInsightsQuickstart
{
    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 批注：

// Replace the connection string with your Application Insights connection string
var connectionString = "your-application-insights-connection-string";

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

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

using var traceProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource("Microsoft.SemanticKernel*")
    .AddAzureMonitorTraceExporter(options => options.ConnectionString = connectionString)
    .Build();

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddMeter("Microsoft.SemanticKernel*")
    .AddAzureMonitorMetricExporter(options => options.ConnectionString = connectionString)
    .Build();

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

最後取消批注將 // builder.Services.AddSingleton(loggerFactory); 記錄器處理站新增至產生器。

如需遙測設定程式碼的詳細資訊，請參閱這篇文章。這裡唯一的差異在於，我們用來 AddAzureMonitor[Trace|Metric|Log]Exporter 將遙測數據導出至 Application Insights。

建立新的 Python 虛擬環境

python -m venv telemetry-application-insights-quickstart

啟用虛擬環境。

telemetry-application-insights-quickstart\Scripts\activate

安裝必要的套件

pip install semantic-kernel azure-monitor-opentelemetry-exporter

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

建立新的 Python 腳本，並使用您慣用的編輯器加以開啟。

Powershell
Bash

New-Item -Path telemetry_application_insights_quickstart.py -ItemType file

touch telemetry_application_insights_quickstart.py

我們將建立使用語意核心將提示傳送至聊天完成模型的簡單 Python 腳本。以下列程式代碼取代現有的內容，並填入、 deployment_name和 endpoint的必要值api_key：

import asyncio
import logging

from azure.monitor.opentelemetry.exporter import (
    AzureMonitorLogExporter,
    AzureMonitorMetricExporter,
    AzureMonitorTraceExporter,
)

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
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 批注：

# Replace the connection string with your Application Insights connection string
connection_string = "your-application-insights-connection-string"

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


def set_up_logging():
    exporter = AzureMonitorLogExporter(connection_string=connection_string)

    # 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 = AzureMonitorTraceExporter(connection_string=connection_string)

    # 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 = AzureMonitorMetricExporter(connection_string=connection_string)

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

如需遙測設定程式碼的詳細資訊，請參閱這篇文章。這裡唯一的差異在於，我們用來 AzureMonitor[Trace|Metric|Log]Exporter 將遙測數據導出至 Application Insights。

注意

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

Run

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

dotnet run

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

python telemetry_application_insights_quickstart.py

注意

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

檢查遙測數據

執行應用程式之後，請前往ApplicationInsights入口網站來檢查遙測數據。可能需要幾分鐘的時間，數據才會出現在入口網站中。

交易搜尋

流覽至 [ 交易搜尋] 索引標籤，以檢視已記錄的交易。

點擊重新整理以查看最新的交易。出現結果時，按兩下其中一個以查看更多詳細數據。

在 [ 檢視所有 ] 和 [檢視時程表 ] 按鈕之間切換，以查看不同檢視中交易的所有追蹤和相依性。

重要

追蹤代表傳統的記錄專案和 OpenTelemetry 跨事件。它們與分散式追蹤不同。相依性代表對（內部和外部）元件的呼叫。如需 Application Insights 中數據模型的詳細資訊，請參閱這篇文章。

在此特定範例中，您應該會看到兩個相依性和多個追蹤。第一個相依性代表從提示建立的核心函式。第二個相依性代表對 Azure OpenAI 聊天完成模型的呼叫。當您展開 chat.completion {your-deployment-name} 相依性時，應該會看到呼叫的詳細數據。一組 gen_ai 屬性會附加至相依性，以提供呼叫的其他內容。

GenAI 屬性

如果您已將參數 Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnosticsSensitive 設定為 true，您也會看到兩個追蹤，其中包含提示的敏感數據和完成結果。

GenAI 敏感性屬性

按兩下它們，您會看到 [自訂屬性] 區段底下的提示和完成結果。

如果您將環境變數 SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE 設定為 true，您也會看到兩個追蹤，其中包含提示的敏感數據和完成結果。

GenAI 敏感性屬性

按兩下它們，您會看到 [自訂屬性] 區段底下的提示和完成結果。

Log Analytics

交易搜尋並不是檢查遙測數據的唯一方式。您也可以使用 Log Analytics 來查詢和分析數據。流覽至 [監視] 底下的 [記錄] 以啟動。

請遵循此文件，開始探索Log Analytics 介面。

以下是可用於此範例的一些範例查詢：

// Retrieves the total number of completion and prompt tokens used for the model if you run the application multiple times.
dependencies
| where name startswith "chat"
| project model = customDimensions["gen_ai.request.model"], completion_token = toint(customDimensions["gen_ai.response.completion_tokens"]), prompt_token = toint(customDimensions["gen_ai.response.prompt_tokens"])
| where model == "gpt-4o"
| project completion_token, prompt_token
| summarize total_completion_tokens = sum(completion_token), total_prompt_tokens = sum(prompt_token)

// Retrieves all the prompts and completions and their corresponding token usage.
dependencies
| where name startswith "chat"
| project timestamp, operation_Id, name, completion_token = customDimensions["gen_ai.response.completion_tokens"], prompt_token = customDimensions["gen_ai.response.prompt_tokens"]
| join traces on operation_Id
| where message startswith "gen_ai"
|project timestamp, messages = customDimensions, token=iff(customDimensions contains "gen_ai.prompt", prompt_token, completion_token)

查詢結果

下一步

現在，您已成功將遙測數據輸出至 Application Insights，您可以探索更多語意核心功能，以協助您監視和診斷應用程式：

使用語意核心的進階遙測

共用方式為

使用 Application Insights 檢查遙測數據

Exporter

必要條件

設定

建立新的主控台應用程式

安裝必要的套件

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

新增遙測

建立新的 Python 虛擬環境

安裝必要的套件

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

新增遙測

環境變數

代碼

Run

檢查遙測數據

交易搜尋

Log Analytics

下一步

其他資源