Přidání a úprava OpenTelemetry pro aplikace .NET, Java, Node.js a Python

Poznámka:

Pro aplikace .NET, Node.js a Python:

Pro Java aplikace použijte Azure Monitor OpenTelemetry Distro.

Pokyny k instrumentaci s asistencí umělé inteligence najdete v dovednosti Instrumentace Application Insights. Informace o řízeném nastavení a analýze stávajících instrumentací Application Insights najdete v nástrojích serveru Azure MCP pro Azure Monitor.

Tato příručka obsahuje pokyny k integraci a přizpůsobení instrumentace OpenTelemetry (OTel) v rámci Azure Monitor Application Insights.

Použijte distribuci Microsoft OpenTelemetry pro .NET, Node.js a Python. Java nadále používá Azure Monitor OpenTelemetry Distro a jeho agenta nebo integrace nativních imagí. Nejprve povolte OpenTelemetry pro váš jazyk. Nahraďte základní inicializaci příslušným příkladem; neinicializujte druhou distribuci nebo poskytovatele pro stejný signál.

Identifikátory balíčků Microsoft OpenTelemetry Distro a příkazy k instalaci jsou:

Jazyk Package Instalační příkaz
Python microsoft-opentelemetry pip install microsoft-opentelemetry
Node.js @microsoft/opentelemetry npm install @microsoft/opentelemetry
platforma .NET Microsoft.OpenTelemetry dotnet add package Microsoft.OpenTelemetry

Nastavte APPLICATIONINSIGHTS_CONNECTION_STRING před spuštěním příkladů, které ho nenastaví v kódu. Udržujte poskytovatele naživu po celou dobu běhu aplikace a při vypnutí vyprázdněte telemetrii do úložiště. Inicializujte instrumentaci Node.js před načtením knihoven aplikace; aplikace ESM musí předem načíst zavaděč Microsoft OpenTelemetry Distro.

Další informace o konceptech OpenTelemetry najdete v přehledu OpenTelemetry.

Poznámka:

Pro aplikace funkcí Azure viz Použití OpenTelemetry s Azure Functions.

Přidat knihovnu instrumentace komunity

Knihovny zahrnuté v jednotlivých distribucích najdete v tématu Automatické shromažďování dat a detektory prostředků.

Pokud zahrnete knihovny instrumentace z komunity OpenTelemetry, můžete automaticky shromažďovat další data.

Upozornění

Nepodporujeme ani nezaručujeme kvalitu komunitních instrumentačních knihoven. Pokud ho chcete navrhnout pro naši distribuci, publikujte nebo hlasujte v naší komunitě pro zpětnou vazbu. Mějte na paměti, že některé jsou založené na experimentálních specifikacích OpenTelemetry a můžou představovat budoucí zásadní změny.

Pokud chcete přidat knihovnu komunity, po přidání balíčku NuGet pro knihovnu použijte metody ConfigureOpenTelemetryMeterProvider nebo ConfigureOpenTelemetryTracerProvider.

Následující příklad ukazuje, jak přidat instrumentaci modulu runtime pro shromažďování dalších metrik:

dotnet add package OpenTelemetry.Instrumentation.Runtime

// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry.Metrics;

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add runtime instrumentation.
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) =>
    builder.AddRuntimeInstrumentation());

// Configure the Microsoft OpenTelemetry Distro.
// Export collected telemetry to Azure Monitor.
builder.Services.AddOpenTelemetry().UseMicrosoftOpenTelemetry(options =>
    options.Exporters = ExportTarget.AzureMonitor);

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Shromažďování vlastních telemetrických dat

Tato část vysvětluje, jak shromažďovat vlastní telemetrická data z vaší aplikace.

V závislosti na vašem jazyce a typu signálu existují různé způsoby shromažďování vlastních telemetrických dat, mezi které patří:

  • OpenTelemetry API
  • Knihovny protokolování/metrik pro specifické jazyky

Poznámka:

Rozhraní pro trasování API Micrometer pro Javu není podporováno.

Následující tabulka představuje aktuálně podporované vlastní typy telemetrie:

Jazyk Vlastní události Vlastní metriky Závislosti Výjimky Zobrazení stránek Žádosti Trasování
ASP.NET Core
   OpenTelemetry API Ano Ano Ano Ano
    ILogger Rozhraní api Ano Ano
Java
   OpenTelemetry API Ano Ano Ano Ano Ano
   Logback, Log4j, JUL Ano Ano
   Metriky v mikrometrech Ano
Node.js
   OpenTelemetry API Ano Ano Ano Ano Ano
Python
   OpenTelemetry API Ano Ano Ano Ano
   Modul protokolování Python Ano
   Rozšíření událostí Ano Ano

Přidání vlastních metrik

V tomto kontextu termín vlastních metrik odkazuje na ruční instrumentaci kódu za účelem shromažďování dalších metrik nad rámec toho, co knihovny Instrumentace OpenTelemetry automaticky shromažďují. Další informace o používání metrik najdete v tématu Metriky v Application Insights.

Rozhraní Api OpenTelemetry nabízí šest "nástrojů" pro pokrytí různých scénářů metrik a při vizualizaci metrik v Průzkumníku metrik musíte vybrat správný typ agregace. Tento požadavek platí při použití rozhraní API metriky OpenTelemetry k odesílání metrik a při použití knihovny instrumentace.

Následující tabulka uvádí doporučené typy agregace pro jednotlivé nástroje metriky OpenTelemetry.

OpenTelemetry nástroj Agregační typ Azure Monitor
Čítač Suma
Asynchronní čítač Suma
Histogram Minimální, Maximální, Průměr, Součet a Počet
Asynchronní měřidlo Průměr
UpDownCounter Suma
Asynchronní čítač nahoru/dolů Suma

Upozornění

Ve většině případů nejsou jiné typy agregace smysluplné.

Specifikace OpenTelemetry popisuje nástroje a poskytuje příklady, kdy je možné jednotlivé použít.

Návod

Histogram je univerzální nástroj metriky OpenTelemetry pro zaznamenávání distribucí. Azure Monitor v současné době zplošťuje histogramový nástroj do pěti podporovaných typů agregace a probíhá práce na podpoře percentilů. I když méně všestranné, jiné nástroje OpenTelemetry mají menší vliv na výkon vaší aplikace.

Příklad histogramu

Spuštění aplikace se musí přihlásit k odběru měřiče podle názvu:

// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry.Metrics;

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named
// "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter(
    "OTel.AzureMonitor.Demo"));

// Configure the Microsoft OpenTelemetry Distro.
// Export collected telemetry to Azure Monitor.
builder.Services.AddOpenTelemetry().UseMicrosoftOpenTelemetry(options =>
    options.Exporters = ExportTarget.AzureMonitor);

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Musí Meter být inicializován pomocí stejného názvu:

using System.Diagnostics.Metrics;

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new histogram metric named "FruitSalePrice".
Histogram<long> myFruitSalePrice = meter.CreateHistogram<long>("FruitSalePrice");

// Create a new Random object.
var rand = new Random();

// Record a few random sale prices for apples and lemons, with different colors.
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "green"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));

Proti příklad

Spuštění aplikace se musí přihlásit k odběru měřiče podle názvu:

// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry.Metrics;

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named
// "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter(
    "OTel.AzureMonitor.Demo"));

// Configure the Microsoft OpenTelemetry Distro.
// Export collected telemetry to Azure Monitor.
builder.Services.AddOpenTelemetry().UseMicrosoftOpenTelemetry(options =>
    options.Exporters = ExportTarget.AzureMonitor);

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Musí Meter být inicializován pomocí stejného názvu:

using System.Diagnostics.Metrics;

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new counter metric named "MyFruitCounter".
Counter<long> myFruitCounter = meter.CreateCounter<long>("MyFruitCounter");

// Record the number of fruits sold, grouped by name and color.
myFruitCounter.Add(1, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(2, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(1, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(2, new("name", "apple"), new("color", "green"));
myFruitCounter.Add(5, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(4, new("name", "lemon"), new("color", "yellow"));

Příklad měřidla

Spuštění aplikace se musí přihlásit k odběru měřiče podle názvu:

// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry.Metrics;

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named
// "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter(
    "OTel.AzureMonitor.Demo"));

// Configure the Microsoft OpenTelemetry Distro.
// Export collected telemetry to Azure Monitor.
builder.Services.AddOpenTelemetry().UseMicrosoftOpenTelemetry(options =>
    options.Exporters = ExportTarget.AzureMonitor);

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Musí Meter být inicializován pomocí stejného názvu:

using System.Diagnostics;
using System.Diagnostics.Metrics;

// Get the current process.
var process = Process.GetCurrentProcess();

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new observable gauge metric named "Thread.State".
// This metric will track the state of each thread in the current process.
ObservableGauge<int> myObservableGauge = meter.CreateObservableGauge("Thread.State", (
    ) => GetThreadState(process));

static IEnumerable<Measurement<int>> GetThreadState(Process process)
{
    // Iterate over all threads in the current process.
    foreach (ProcessThread thread in process.Threads)
    {
        // Create a measurement for each thread, including the thread state, process ID,
        // and thread ID.
        yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new(
            "ThreadId", thread.Id));
    }
}

Přidání vlastních výjimek

Výběr knihoven instrumentace automaticky hlásí výjimky do Application Insights. Můžete ale chtít ručně hlásit výjimky nad rámec toho, co reportují knihovny instrumentace. Například výjimky zachycené vaším kódem nejsou obvykle hlášeny. Můžete je chtít nahlásit, aby upoutaly pozornost v relevantních zkušenostech, včetně části selhání a zobrazení end-to-end transakcí.

Příklady .NET jsou fragmenty pro již instrumentovanou aplikaci. V příkladech aktivit použijte zaregistrovaný activitySource z Přidat vlastní spany. Pro příklady protokolování použijte ILoggerFactory nakonfigurované v aplikaci jako loggerFactory.

  • Protokolovat výjimku pomocí aktivity:

    using System.Diagnostics;
using OpenTelemetry.Trace;

// Start a new activity named "ExceptionExample".
using (var activity = activitySource.StartActivity("ExceptionExample"))
{
    // Try to execute some code.
    try
    {
        throw new Exception("Test exception");
    }
    // If an exception is thrown, catch it and set the activity status to "Error".
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error);
        activity?.RecordException(ex);
    }
}

  • Protokolování výjimky pomocí ILogger:

    // Create a logger using the logger factory. The logger category name is used to filter
// and route log messages.
var logger = loggerFactory.CreateLogger("ExceptionExample");

// Try to execute some code.
try
{
    throw new Exception("Test Exception");
}
catch (Exception ex)
{
    // Log an error message with the exception. The log level is set to "Error" and the
    // event ID is set to 0.
    // The log message includes a template and a parameter. The template will be replaced
    // with the value of the parameter when the log message is written.
    logger.Log(
        logLevel: LogLevel.Error,
        eventId: 0,
        exception: ex,
        message: "Hello {name}.",
        args: new object[] { "World" });
}

Přidejte vlastní rozsahy

Můžete chtít přidat vlastní rozsah ve dvou scénářích. Za prvé, pokud knihovna instrumentace ještě nesbírala závislostní požadavek. Za druhé, pokud chcete modelovat proces aplikace jako úsek v rámci zobrazení end-to-end transakcí.

Poznámka:

Třídy Activity a ActivitySource z oboru názvů System.Diagnostics představují v uvedeném pořadí koncepty Span a Tracer OpenTelemetry. Vytváříte ActivitySource přímo pomocí jeho konstruktoru místo pomocí .TracerProvider Každá třída ActivitySource musí být explicitně připojena k TracerProvider pomocí AddSource(). Je to proto, že části rozhraní API pro trasování OpenTelemetry jsou začleněny přímo do modulu runtime .NET. Další informace najdete v tématu Introduction k rozhraní OPENTelemetry .NET Tracing API.

Přidání vlastních spanů 
// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using System.Diagnostics;
using OpenTelemetry.Trace;

// Define an activity source named "ActivitySourceName". This activity source will be used
// to create activities for all requests to the application.
using var activitySource = new ActivitySource("ActivitySourceName");

// Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a source named "ActivitySourceName".
// This will ensure that all activities created by the activity source are traced.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) =>
    builder.AddSource("ActivitySourceName"));

// Configure the Microsoft OpenTelemetry Distro. This service will collect
// and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseMicrosoftOpenTelemetry(options =>
    options.Exporters = ExportTarget.AzureMonitor);

// Build the ASP.NET Core application.
var app = builder.Build();

// Map a GET request to the root path ("/") to the specified action.
app.MapGet("/", () =>
{
    // Start a new activity named "CustomActivity". This activity will be traced and the
    // trace data will be sent to Azure Monitor.
    using (var activity = activitySource.StartActivity("CustomActivity"))
    {
        // your code here
    }

    // Return a response message.
    return $"Hello World!";
});

// Start the ASP.NET Core application.
app.Run();

StartActivity je nastaveno na ActivityKind.Internal, ale můžete poskytnout jakékoli jiné ActivityKind. ActivityKind.Client, ActivityKind.Producera ActivityKind.Internal jsou mapovány na Application Insights dependencies. ActivityKind.Server a ActivityKind.Consumer jsou mapovány na application Insights requests.

Odesílání vlastních událostí

Application Insights ukládá vlastní události v customEvents tabulce. Jedním ze způsobů, jak je analyzovat, filtrovat a vizualizovat, je použití Application Insights.

Pokud chcete automatizovat kolekci událostí interakce na straně klienta, můžete použít modul plug-in v sadě JavaScript SDK.

Distro Microsoft OpenTelemetry pro .NET odesílá vlastní události prostřednictvím exportéru protokolování Azure Monitor.

Pokud chcete odeslat CustomEvent pomocí ILogger, nastavte atribut "microsoft.custom_event.name" v šabloně zprávy.

// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;

// Create the application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the Microsoft OpenTelemetry Distro.
builder.UseMicrosoftOpenTelemetry(options =>
{
    options.Exporters = ExportTarget.AzureMonitor;
});

// Build the application with the configured telemetry services.
var app = builder.Build();

// Use the message-template attribute to name the custom event.
app.Logger.LogInformation("{microsoft.custom_event.name} {additional_attrs}",
    "test-event-name", "val1");

// Run the application and its telemetry providers.
app.Run();

Úprava telemetrie

Tato část vysvětluje, jak upravit telemetrii.

Přidání atributů span

Mezi tyto atributy může patřit přidání vlastní vlastnosti do telemetrie. Pomocí atributů můžete také nastavit volitelná pole ve schématu Application Insights, jako je IP adresa klienta.

Přidejte vlastní vlastnost do "spanu"

Všechny atributy , které přidáte do rozsahů, se exportují jako vlastní vlastnosti. Naplní pole customDimensions v tabulce požadavků, závislostí, trasování nebo výjimek.

Pokud chcete přidat atributy span, použijte jeden z následujících dvou způsobů:

  • Použijte možnosti poskytované knihovnami instrumentace.
  • Přidejte vlastní span processor

Návod

Výhodou použití možností poskytovaných knihovnami instrumentace, pokud jsou k dispozici, je, že je k dispozici celý kontext. V důsledku toho mohou uživatelé vybrat přidání nebo filtrování dalších atributů. Možnost obohacení v knihovně instrumentace HttpClient například uživatelům poskytuje přístup k HttpRequestMessage a samotnému HttpResponseMessage. Můžou z něj vybrat cokoli a uložit ho jako atribut.

  1. Mnoho nástrojových knihoven nabízí funkci obohacení. Pokyny najdete v souborech readme jednotlivých knihoven instrumentace:

  2. Použití vlastního procesoru:

    Návod

    Přidejte procesor zobrazený tady před přidáním Azure Monitor.

    // Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry.Trace;

// Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a new processor named
// ActivityEnrichingProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) =>
    builder.AddProcessor(new ActivityEnrichingProcessor()));

// Configure the Microsoft OpenTelemetry Distro. This service will collect
// and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseMicrosoftOpenTelemetry(options =>
    options.Exporters = ExportTarget.AzureMonitor);

// Build the ASP.NET Core application.
var app = builder.Build();

// Start the ASP.NET Core application.
app.Run();

    Do project přidejte ActivityEnrichingProcessor.cs následujícím kódem:

    using System.Diagnostics;
using OpenTelemetry;

public class ActivityEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        // The updated activity will be available to all processors which are called after
        // this processor.
        activity.DisplayName = "Updated-" + activity.DisplayName;
        activity.SetTag("CustomDimension1", "Value1");
        activity.SetTag("CustomDimension2", "Value2");
    }
}

Nastavení IP adresy uživatele

Pole client_IP pro požadavky můžete naplnit nastavením atributu na spanu. Application Insights používá IP adresu k vygenerování atributů umístění uživatele a ve výchozím nastavení ji zahodí.

Použijte ukázku vlastní vlastnosti, ale nahraďte následující řádky kódu v ActivityEnrichingProcessor.cs:

// Add the client IP address to the activity as a tag.
// only applicable in case of activity.Kind == Server
activity.SetTag("client.address", "<IpAddress>");

Nastavení ID uživatele nebo ověřeného ID uživatele

Můžete vyplnit pole user_AuthenticatedId nebo user_Id pro požadavky pomocí následujících pokynů. ID uživatele je anonymní identifikátor uživatele. Ověřené ID uživatele je známý identifikátor uživatele.

Důležité

Než nastavíte ID ověřeného uživatele, obraťte se na příslušné zákony o ochraně osobních údajů.

Použijte příklad vlastní vlastnosti:

// Add the user ID to the activity as a tag, but only if the activity is not null.
activity?.SetTag("enduser.id", "<UserId>");

Přidání atributů protokolu

OpenTelemetry používá .NET ILogger. Připojení vlastních dimenzí k protokolům lze provést pomocí šablony zprávy.

Úprava stavu chyby požadavku pro odpovědi HTTP 4xx

Můžete zabránit tomu, aby Application Insights počítalo odpovědi 4xx jako chyby.

Následující kód ukazuje vlastní procesor aktivity, který označí odpovědi HTTP 4xx jako úspěšné.

Procesor:

using System.Diagnostics;
using OpenTelemetry;

public class Http4xxSuccessProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        if (activity.Kind == ActivityKind.Server)
        {
            var statusCodeTag = activity.GetTagItem("http.response.status_code");
            if (statusCodeTag is int statusCode && statusCode >= 400 && statusCode < 500)
            {
                // Set status to Ok to bypass the Azure Monitor exporter's default logic
                // which treats any HTTP 4xx as failure when status is Unset.
                // The response code tag (e.g., 400) remains unchanged — only the
                // success field in Application Insights is affected.
                activity.SetStatus(ActivityStatusCode.Ok);
            }
        }

        base.OnEnd(activity);
    }
}

Registrace:

// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry.Trace;

// Create the application builder.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing.AddProcessor<Http4xxSuccessProcessor>())

    // Configure the Microsoft OpenTelemetry Distro.
    .UseMicrosoftOpenTelemetry(options =>
    {
        options.Exporters = ExportTarget.AzureMonitor;

        // Set the connection string for Azure Monitor export.
        options.AzureMonitor.ConnectionString = "<ConnectionString>";
    });

// Build the application with the configured telemetry services.
var app = builder.Build();

// Run the application and its telemetry providers.
app.Run();

Získejte ID trasování nebo ID úseku

Pomocí následujícího postupu získejte Trace ID a Span ID pro aktuálně aktivní rozsah.

Poznámka:

Třídy Activity a ActivitySource z oboru názvů System.Diagnostics představují v uvedeném pořadí koncepty Span a Tracer OpenTelemetry. Je to proto, že části rozhraní API pro trasování OpenTelemetry jsou začleněny přímo do modulu runtime .NET. Další informace najdete v tématu Introduction k rozhraní OPENTelemetry .NET Tracing API.

using System.Diagnostics;

// Get the current activity.
Activity activity = Activity.Current;
// Get the trace ID of the activity.
string traceId = activity?.TraceId.ToHexString();
// Get the span ID of the activity.
string spanId = activity?.SpanId.ToHexString();

Zachycení zpětné vazby koncových uživatelů pro agenty GenAI

Zachyťte zpětnou vazbu koncového uživatele, například palec nahoru nebo palec dolů v odpovědi agenta, a odešlete ji do Application Insights jako vlastní událost. Odešlete zpětnou vazbu jako záznam logu OpenTelemetry s vyhrazeným názvem události gen_ai.evaluation.result.

Atributy události zpětné vazby

Attribute Povinné Description Example
microsoft.custom_event.name Ano Směruje záznam protokolu do customEvents tabulky. Použijte název rezervované události. gen_ai.evaluation.result
gen_ai.evaluation.name Ano Identifikuje metriku vyhodnocení. Pomocí task_completion můžete odeslat zpětnou vazbu pomocí palce nahoru nebo palce dolů. task_completion
gen_ai.evaluation.score.value Ano Zaznamenává číselné skóre. Používá se 1.0 pro palec nahoru nebo 0.0 pro palec dolů. 1.0
gen_ai.evaluation.score.label Ano Ukládá srozumitelný popisek skóre; přijímají se pouze dvě hodnoty. pass nebo fail jsou jediné přijatelné hodnoty.
gen_ai.evaluation.explanation No Poskytuje volitelný bezplatný textový komentář. Helpful response
gen_ai.response.id Doporučený Koreluje zpětnou vazbu s odpovědí agenta. resp-123
microsoft.gen_ai.human_evaluation.source Ano pro poznámky Foundry Identifikuje poskytovatele zpětné vazby. end_user nebo builder
microsoft.gen_ai.evaluation.actor.type Ano pro poznámky Foundry Identifikuje hodnocení jako odeslané člověkem. human

Upozornění

Odstraňte osobní identifikační údaje (PII) a další citlivá data z gen_ai.evaluation.explanation, nebo k ochraně dat použijte funkce zabezpečení Log Analytics, jako je zabezpečení na úrovni řádků nebo přístup na úrovni tabulky.

Odeslat názory

Následující příklady používají Microsoft OpenTelemetry Distro k odeslání pozitivního task_completion hodnocení. Vyvolejte událost z obslužné rutiny požadavku nebo z jiného kódu, který má stále k dispozici kontext trasování původní interakce agenta.

Odeslat událost zpětné vazby agenta 
using System.Text.Json;

// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry;

// Create the application builder.
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()

    // Configure the Microsoft OpenTelemetry Distro.
    .UseMicrosoftOpenTelemetry(options =>
    {
        options.Exporters = ExportTarget.AzureMonitor;

        // Read the environment setting before the application configuration.
        options.AzureMonitor.ConnectionString =
            builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"];
    });

// Build the application with the configured telemetry services.
var app = builder.Build();

app.MapPost("/feedback", (ILoggerFactory loggerFactory) =>
{
    var logger = loggerFactory.CreateLogger("genai-eval");
    var attributes = new List<KeyValuePair<string, object?>>
    {
        new("microsoft.custom_event.name", "gen_ai.evaluation.result"),
        new("gen_ai.evaluation.name", "task_completion"),
        new("gen_ai.evaluation.score.value", 1.0),
        new("gen_ai.evaluation.score.label", "pass"),
        new("gen_ai.evaluation.explanation", "Helpful response"),
        new("gen_ai.response.id", "resp-123"),
        new("microsoft.gen_ai.human_evaluation.source", "end_user"),
        new("microsoft.gen_ai.evaluation.actor.type", "human"),
        new("internal_properties", JsonSerializer.Serialize(new Dictionary<string, string>
        {
            ["gen_ai.evaluation.type"] = "boolean",
            ["gen_ai.evaluation.min_value"] = "0.0",
            ["gen_ai.evaluation.max_value"] = "1.0",
            ["gen_ai.evaluation.threshold"] = "1.0",
            ["gen_ai.evaluation.desirable_direction"] = "increase",
        })),
    };

    logger.Log(
        LogLevel.Information,
        eventId: default,
        state: attributes,
        exception: null,
        formatter: static (_, _) => "Human evaluation submitted");

    return Results.Ok();
});

// Run the application and its telemetry providers.
app.Run();

Zpětná vazba k dotazům ve službě Application Insights

Události zpětné vazby se zobrazují v tabulce customEvents s názvem události gen_ai.evaluation.result. Atributy GenAI jsou k dispozici jako vlastní dimenze. Pomocí gen_ai.response.id připojte zpětnou vazbu k odpovídající odpovědi agenta, trasování, požadavku a telemetrii závislostí.

customEvents
| where name == "gen_ai.evaluation.result"
| extend
    responseId = tostring(customDimensions["gen_ai.response.id"]),
    score = todouble(customDimensions["gen_ai.evaluation.score.value"]),
    label = tostring(customDimensions["gen_ai.evaluation.score.label"]),
    source = tostring(customDimensions["microsoft.gen_ai.human_evaluation.source"]),
    internalProperties = parse_json(tostring(customDimensions["internal_properties"]))
| extend evaluationType = tostring(internalProperties["gen_ai.evaluation.type"])
| project timestamp, responseId, score, label, source, evaluationType
| order by timestamp desc

Další informace najdete tady:

Řešení potíží, zpětná vazba a podpora

Návod

Následující části jsou k dispozici ve všech článcích o distribuci OpenTelemetry.

Troubleshooting

Zpětná vazba k OpenTelemetry

Poskytnutí zpětné vazby:

Podpora

Vyberte kartu pro jazyk podle vašeho výběru a objevte možnosti podpory.

  • V případě problémů s podporou Azure otevřete tiket Azure.
  • V případě problémů s OpenTelemetry kontaktujte přímo komunitu OpenTelemetry .NET.
  • Seznam otevřených problémů souvisejících s vývozcem Azure Monitor najdete na stránce GitHub Problémy.

Další kroky

  • Poslední aktualizace v