Dodawanie śledzenia po stronie klienta do agentów usługi Foundry (wersja zapoznawcza)

Ważne

Elementy oznaczone (wersja zapoznawcza) w tym artykule są obecnie dostępne w publicznej wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie zalecamy korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Wygólne warunki użytkowania Microsoft Azure Previews.

Microsoft Foundry automatycznie przechwytuje ślady po stronie serwera dla agentów działających w portalu. Śledzenie po stronie klienta rozszerza ten wgląd w własny kod aplikacji. Instrumentując aplikację agenta przy użyciu OpenTelemetry, można przechwytywać przedziały dla wywołań modelu, wywołań narzędzi i logiki niestandardowej, a następnie eksportować je do Azure Monitor Application Insights, konsoli lub dowolnego systemu do monitorowania obsługującego protokół OpenTelemetry (OTLP), takich jak Datadog, Grafana Tempo, Jaeger lub Honeycomb.

Z tego artykułu dowiesz się, jak wykonywać następujące działania:

Zainstaluj wymagane pakiety śledzenia OpenTelemetry.
Włącz instrumentację śledzenia GenAI dla aplikacji agenta.
Eksportuj ślady do Azure Monitor, konsoli lub zaplecza zgodnego z OTLP.
Włącz nagrywanie zawartości, aby przechwycić zawartość wiadomości.
Włącz propagację kontekstu śledzenia dla śledzenia rozproszonego (Python).
Śledzenie funkcji własnych.

Wymagania wstępne

Projekt Foundry z połączonym zasobem usługi Application Insights.
Model sztucznej inteligencji wdrożony w projekcie. Zanotuj nazwę wdrożenia.
Azure CLI zainstalowany. Zaloguj się, uruchamiając polecenie az login.
Współautor lub wyższa rola w projekcie Foundry. Aby wyświetlić ślady, potrzebujesz również Log Analytics Reader w połączonym zasobie usługi Application Insights. Jeśli te tabele usługi Log Analytics są chronione, przypisz również rolę Privileged Monitoring Data Reader. Aby uzyskać więcej informacji, zobacz Kontrola dostępu oparta na rolach w narzędziu Foundry.

Następujące zmienne środowiskowe ustawione przy użyciu własnych wartości:

Zmienna	Opis
`FOUNDRY_PROJECT_ENDPOINT`	Adres URL punktu końcowego projektu Foundry. Znajdź go na stronie Przegląd projektu w portalu Foundry.
`FOUNDRY_MODEL_NAME`	Nazwa wdrożenia modelu AI w projekcie. Znajdź go w obszarze Modele w portalu Foundry.

Wymagania wstępne specyficzne dla języka

Python 3.10 lub nowszy.
Pakiet azure-ai-projects w wersji 2.0.0 lub nowszej.

Instalowanie pakietów śledzenia

Zainstaluj Microsoft Foundry SDK, OpenTelemetry i eksportera Azure Monitor:

pip install azure-ai-projects azure-identity opentelemetry-sdk azure-core-tracing-opentelemetry azure-monitor-opentelemetry

W przypadku eksportu tylko do konsoli lub OTLP (na przykład Aspire Dashboard) zainstaluj eksporter OTLP:

pip install opentelemetry-exporter-otlp

Dodaj wymagane pakiety NuGet:

dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.Identity
dotnet add package Azure.Monitor.OpenTelemetry.Exporter
dotnet add package OpenTelemetry.Exporter.Console

W przypadku aplikacji ASP.NET Core preferowany jest pakiet Azure.Monitor.OpenTelemetry.AspNetCore. Pakiet Azure.Monitor.OpenTelemetry.Exporter pokazany tutaj działa dla wszystkich typów aplikacji .NET.

Zainstaluj Microsoft Foundry SDK, OpenTelemetry i eksportera Azure Monitor:

npm install @azure/ai-projects @azure/identity @azure/monitor-opentelemetry @opentelemetry/api dotenv

W przypadku eksportowania tylko do konsoli potrzebne są również pakiety zestawu SDK OpenTelemetry:

npm install @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base

Włącz śledzenie GenAI

Instrumentacja śledzenia GenAI to eksperymentalna funkcja w wersji zapoznawczej. Zakresy, atrybuty i zdarzenia mogą ulec zmianie w przyszłych wersjach. Przed włączeniem śledzenia należy jawnie wyrazić zgodę.

Ustaw zmienną środowiskową AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING na wartość trueprzed wywołaniem metody AIProjectInstrumentor().instrument():

import os

os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"

from azure.ai.projects.telemetry import AIProjectInstrumentor

# Enable instrumentation
AIProjectInstrumentor().instrument()

Jeśli zmienna nie jest ustawiona lub nie jest równa true (niezależnie od wielkości liter), instrumentacja śledzenia nie jest włączona i jest rejestrowane ostrzeżenie.

Użyj przełącznika AppContext lub tej samej zmiennej środowiskowej:

// Enable GenAI tracing
AppContext.SetSwitch("Azure.Experimental.EnableGenAITracing", true);

Po włączeniu Azure.Experimental.EnableGenAITracing zestaw SDK automatycznie włącza flagę Azure.Experimental.EnableActivitySource, która jest wymagana do działania instrumentacji OpenTelemetry.

Jeśli zarówno przełącznik AppContext jak i zmienna środowiskowa są ustawione, przełącznik AppContext ma priorytet.

Uwaga

W języku C# wszystkie zmienne środowiskowe związane ze śledzeniem akceptują true (bez uwzględniania wielkości liter) lub 1 jako równoważne wartości włączające.

Przekaż experimental: true podczas tworzenia AIProjectClient w tracingOptions. W przeciwieństwie do zestawów SDK Python i C# zestaw SDK języka JavaScript/TypeScript umożliwia śledzenie poszczególnych wystąpień klienta zamiast za pomocą oddzielnego wywołania instrumentacji:

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
  {
    tracingOptions: {
      experimental: true,
    },
  },
);

Można również ustawić zmienną AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING środowiskową na true zamiast przekazywać tę opcję. Właściwość tracingOptions ma pierwszeństwo przed zmienną środowiskową. Aby uzyskać pełny przykład, zobacz Eksportowanie śladów do Azure Monitor.

Eksportowanie śladów do Azure Monitor

Wysyłaj ślady do aplikacja systemu Azure Insights, aby były wyświetlane w widoku Traces oraz w systemie Azure Monitor i w portalu Foundry.

import os

os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
from azure.identity import DefaultAzureCredential
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project,
):
    # Get the Application Insights connection string from the project
    connection_string = project.telemetry.get_application_insights_connection_string()
    configure_azure_monitor(connection_string=connection_string)

    tracer = trace.get_tracer(__name__)

    with tracer.start_as_current_span("agent-tracing-scenario"):
        with project.get_openai_client() as openai:
            # Create an agent
            agent = project.agents.create_version(
                agent_name="MyAgent",
                definition=PromptAgentDefinition(
                    model=os.environ["FOUNDRY_MODEL_NAME"],
                    instructions="You are a helpful assistant.",
                ),
            )
            print(f"Agent created (id: {agent.id}, name: {agent.name})")

            # Create a conversation and get a response
            conversation = openai.conversations.create()
            response = openai.responses.create(
                conversation=conversation.id,
                extra_body={"agent_reference": {"name": agent.name, "id": agent.id, "type": "agent_reference"}},
                input="What is the largest city in France?",
            )
            print(f"Response: {response.output_text}")

            # Clean up
            openai.conversations.delete(conversation_id=conversation.id)
            project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)

Dokumentacja: AIProjectClient, , DefaultAzureCredentialconfigure_azure_monitor

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using OpenAI.Responses;

var projectEndpoint = Environment.GetEnvironmentVariable(
    "FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException(
        "FOUNDRY_PROJECT_ENDPOINT isn't set.");
var modelName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL_NAME")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL_NAME isn't set.");

// Enable GenAI tracing
AppContext.SetSwitch("Azure.Experimental.EnableGenAITracing", true);

AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Get the Application Insights connection string from the project
var connectionString = await projectClient.Telemetry
    .GetApplicationInsightsConnectionStringAsync();

// The Azure Monitor exporter reads this environment variable automatically
Environment.SetEnvironmentVariable(
    "APPLICATIONINSIGHTS_CONNECTION_STRING", connectionString);

// Configure OpenTelemetry with Azure Monitor exporter
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Azure.AI.Projects.*")
    .SetResourceBuilder(
        ResourceBuilder.CreateDefault().AddService("AgentTracingSample"))
    .AddAzureMonitorTraceExporter()
    .Build();

using (tracerProvider)
{
    // Create an agent
    DeclarativeAgentDefinition agentDefinition = new(model: modelName)
    {
        Instructions = "You are a helpful assistant."
    };
    ProjectsAgentVersion agent = await projectClient.AgentAdministrationClient
        .CreateAgentVersionAsync(
            agentName: $"agent-tracing-{Guid.NewGuid():N}",
            options: new(agentDefinition));
    try
    {
        Console.WriteLine(
            $"Agent created (id: {agent.Id}, name: {agent.Name})");

        // Call the agent to emit GenAI spans
        ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient
            .GetProjectResponsesClientForAgent(agent.Name);
#pragma warning disable OPENAI001
        ResponseItem request = ResponseItem.CreateUserMessageItem(
            "What is the largest city in France?");
        ResponseResult response = await responseClient.CreateResponseAsync(
            [request]);
#pragma warning restore OPENAI001
        Console.WriteLine($"Response: {response.GetOutputText()}");
    }
    finally
    {
        await projectClient.AgentAdministrationClient.DeleteAgentVersionAsync(
            agentName: agent.Name,
            agentVersion: agent.Version);
    }
}

Dokumentacja: AIProjectClient, , DefaultAzureCredentialSdk.CreateTracerProviderBuilder

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import {
  useAzureMonitor,
  shutdownAzureMonitor,
} from "@azure/monitor-opentelemetry";
import { context, trace } from "@opentelemetry/api";
import "dotenv/config";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "";
const modelName = process.env["FOUNDRY_MODEL_NAME"] || "";

// Enable tracing when you create the client. To capture prompt and
// completion content, set contentRecording to true (off by default).
const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
  {
    tracingOptions: { contentRecording: false, experimental: true },
  },
);
const openAIClient = project.getOpenAIClient();

// Get the Application Insights connection string from the project
const connectionString =
  await project.telemetry.getApplicationInsightsConnectionString();

// Configure Azure Monitor tracing
useAzureMonitor({
  azureMonitorExporterOptions: { connectionString },
});

const tracer = trace.getTracer("AgentTracingSample");
const span = tracer.startSpan("agent-tracing-scenario");
const ctx = trace.setSpan(context.active(), span);

await context.with(ctx, async () => {
  // Create an agent
  const agent = await project.agents.createVersion("MyAgent", {
    kind: "prompt",
    model: modelName,
    instructions: "You are a helpful assistant.",
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name})`);

  // Create a conversation and get a response
  const conversation = await openAIClient.conversations.create({});
  const response = await openAIClient.responses.create(
    {
      conversation: conversation.id,
      input: "What is the largest city in France?",
    },
    {
      body: {
        agent_reference: { name: agent.name, type: "agent_reference" },
      },
    },
  );
  console.log(`Response: ${response.output_text}`);

  // Clean up
  await openAIClient.conversations.delete(conversation.id);
  await project.agents.deleteVersion(agent.name, agent.version);
});

span.end();

// Shut down Azure Monitor to flush all pending traces before exit
await shutdownAzureMonitor();

Dokumentacja: klasa AIProjectClient, telemetry.getApplicationInsightsConnectionString

Uwaga

Aby skorelować ślady z określonym agentem w portalu Foundry, dołącz agent_reference zarówno z name, jak i id w wywołaniu responses.create() (jak pokazano w przykładzie Python powyżej). Ślady zwykle pojawiają się w ciągu 2–5 minut.

Eksportowanie śladów do konsoli

Eksportowanie konsoli jest przydatne do debugowania lokalnego. Ślady są bezpośrednio drukowane na wyjście standardowe.

import os

os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"

from azure.ai.projects.telemetry import AIProjectInstrumentor
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

# Set up console tracing
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(
    SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(tracer_provider)

# Enable instrumentation
AIProjectInstrumentor().instrument()

tracer = trace.get_tracer(__name__)

Możesz również użyć Aspire Dashboard jako lokalnej przeglądarki zgodnej z OTLP. Zainstaluj eksportera OTLP (pip install opentelemetry-exporter-otlp) i skonfiguruj go jako eksportera zamiast ConsoleSpanExporter.

Dokumentacja: AIProjectInstrumentor, ConsoleSpanExporter

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using OpenAI.Responses;

var projectEndpoint = Environment.GetEnvironmentVariable(
    "FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException(
        "FOUNDRY_PROJECT_ENDPOINT isn't set.");
var modelName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL_NAME")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL_NAME isn't set.");

// Enable GenAI tracing
AppContext.SetSwitch("Azure.Experimental.EnableGenAITracing", true);

AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Configure OpenTelemetry with console exporter
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Azure.AI.Projects.*")
    .SetResourceBuilder(
        ResourceBuilder.CreateDefault().AddService("AgentTracingSample"))
    .AddConsoleExporter()
    .Build();

using (tracerProvider)
{
    DeclarativeAgentDefinition agentDefinition = new(model: modelName)
    {
        Instructions = "You are a helpful assistant."
    };
    ProjectsAgentVersion agent = await projectClient.AgentAdministrationClient
        .CreateAgentVersionAsync(
            agentName: $"agent-tracing-{Guid.NewGuid():N}",
            options: new(agentDefinition));
    try
    {
        ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient
            .GetProjectResponsesClientForAgent(agent.Name);
#pragma warning disable OPENAI001
        ResponseItem request = ResponseItem.CreateUserMessageItem(
            "What is the largest city in France?");
        ResponseResult response = await responseClient.CreateResponseAsync(
            [request]);
#pragma warning restore OPENAI001
        Console.WriteLine($"Response: {response.GetOutputText()}");
    }
    finally
    {
        await projectClient.AgentAdministrationClient.DeleteAgentVersionAsync(
            agentName: agent.Name,
            agentVersion: agent.Version);
    }
}

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import { context, trace } from "@opentelemetry/api";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import {
  ConsoleSpanExporter,
  SimpleSpanProcessor,
} from "@opentelemetry/sdk-trace-base";
import "dotenv/config";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "";
const modelName = process.env["FOUNDRY_MODEL_NAME"] || "";

// Set up console tracing
const provider = new NodeTracerProvider({
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
});
provider.register();

const tracer = trace.getTracer("AgentTracingConsoleSample");

// Enable tracing when you create the client
const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
  {
    tracingOptions: { contentRecording: false, experimental: true },
  },
);
const openAIClient = project.getOpenAIClient();

const span = tracer.startSpan("agent-tracing-console-scenario");
const ctx = trace.setSpan(context.active(), span);

await context.with(ctx, async () => {
  // Agent operations emit traces to the console
  const agent = await project.agents.createVersion("MyAgent", {
    kind: "prompt",
    model: modelName,
    instructions: "You are a helpful assistant.",
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name})`);
  await project.agents.deleteVersion(agent.name, agent.version);
});

span.end();
await provider.shutdown();

Odwołanie: klasa AIProjectClient

Włączanie rejestrowania zawartości

Nagrywanie zawartości przechwytuje zawartość wiadomości i argumenty wywołania narzędzia w śladach. Te dane mogą obejmować poufne informacje o użytkowniku.

Ostrożność

Nagrywanie zawartości przechwytuje komunikaty użytkowników, argumenty wywołania narzędzia i dane wyjściowe modelu. Włącz to ustawienie tylko w środowiskach deweloperskich. Nie włączaj rejestrowania zawartości w środowisku produkcyjnym, chyba że zezwalają na to wymagania dotyczące zgodności i prywatności.

Ustaw zmienną środowiskową przed instrumentowaniem:

import os

os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "true"

Ważne

Ta zmienna steruje rejestrowaniem tylko dla wbudowanych śladów. W przypadku używania dekoratora @trace_function we własnych funkcjach wszystkie parametry i wartości zwracane są zawsze śledzone niezależnie od tego ustawienia.

Użyj przełącznika AppContext lub zmiennej środowiskowej:

// Enable content recording
AppContext.SetSwitch("Azure.Experimental.TraceGenAIMessageContent", true);

Możesz też ustawić zmienną środowiskową OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT na true. Jeśli zarówno przełącznik AppContext jak i zmienna środowiskowa są ustawione, przełącznik AppContext ma priorytet.

Ustaw contentRecording: true w tracingOptions podczas tworzenia AIProjectClient:

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
  {
    tracingOptions: { contentRecording: true, experimental: true },
  },
);

Można również ustawić zmienną OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT środowiskową na true zamiast przekazywać tę opcję. Właściwość tracingOptions ma pierwszeństwo przed zmienną środowiskową.

Wyłączanie instrumentacji automatycznej (Python)

Zestaw SDK dla Python automatycznie obsługuje wywołania interfejsu API dotyczące odpowiedzi i konwersacji OpenAI. Aby wyłączyć tę automatyczną instrumentację, ustaw wartość AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API na false przed wywołaniem metody AIProjectInstrumentor().instrument(). Po wyłączeniu rejestrowane są tylko wyraźnie określone zakresy niestandardowe.

import os

os.environ["AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API"] = "false"

Śledzenie danych binarnych (Python)

pl-PL: Gdy rejestrowanie zawartości jest włączone, zestaw SDK domyślnie zapisuje identyfikatory plików oraz nazwy plików. Aby uwzględnić pełne adresy URL obrazów (w tym identyfikatory URI danych base64) oraz dane plików w sekcjach, ustaw AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA na true.

import os

os.environ["AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA"] = "true"

Ostrzeżenie

AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA Włączenie może znacznie zwiększyć rozmiar ładunku śledzenia. Niektóre zaplecza śledzenia mają ograniczenia dotyczące maksymalnego rozmiaru danych. Przed włączeniem tego ustawienia sprawdź, czy zaplecze do obserwacji obsługuje oczekiwane rozmiary ładunków.

Włączanie propagacji kontekstu śledzenia (Python)

Propagacja kontekstu śledzenia umożliwia korelowanie odcinków po stronie klienta z odcinkami po stronie serwera z Azure OpenAI i innych usług Azure. Po włączeniu, zestaw SDK automatycznie wprowadza nagłówki kontekstu śledzenia W3C (traceparent i tracestate) do żądań HTTP wysyłanych przez klientów OpenAI uzyskanych za pośrednictwem get_openai_client().

Propagacja kontekstu śledzenia jest domyślnie włączona po włączeniu śledzenia. Aby ją wyłączyć, ustaw zmienną AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION środowiskową na false, lub przekaż parametr bezpośrednio:

from azure.ai.projects.telemetry import AIProjectInstrumentor

# Disable trace context propagation
AIProjectInstrumentor().instrument(enable_trace_context_propagation=False)

Zmiany tego ustawienia dotyczą tylko klientów OpenAI pozyskanych get_openai_client()po zmianie. Nie ma to wpływu na wcześniej nabytych klientów.

Propagacja bagażu kontrolnego (Python)

Domyślnie tylko nagłówki traceparent i tracestate są propagowane. Aby również dołączyć nagłówek baggage, ustaw AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE na true.

Ważne

Nagłówek baggage może zawierać dowolne pary klucz-wartość, w tym identyfikatory użytkowników, informacje o sesji lub inne potencjalnie poufne dane. Przed włączeniem propagacji bagażu:

Przeprowadź audyt danych, jakie Twoja aplikacja oraz biblioteki innych firm dodają do kontekstu OpenTelemetry.
Dowiedz się, że bagaż jest wysyłany do Azure OpenAI i może być rejestrowany przez usługi Azure.
Nigdy nie dodawaj poufnych informacji do bagażu po włączeniu propagacji.

Uwaga

Zestaw SDK C# wykorzystuje standardową propagację .NET System.Diagnostics.Activity. Jawne wstrzyknięcie kontekstu śledzenia dla każdego żądania nie jest przedstawiane jako oddzielna funkcja w zestawie SDK.

Śledzenie funkcji niestandardowych

Python — użyj dekoratora `@trace_function`

Dekorator trace_function tworzy zakres OpenTelemetry dla każdego wywołania funkcji. Parametry są rejestrowane jako code.function.parameter.<name> i zwracana wartość jako code.function.return.value.

from azure.ai.projects.telemetry import trace_function

@trace_function
def fetch_weather(location: str) -> str:
    """Get the current weather for a location."""
    return f"Weather in {location}: sunny, 72°F"

Aby użyć niestandardowej nazwy zakresu zamiast nazwy funkcji, przekaż ją jako parametr:

@trace_function("get-current-weather")
def fetch_weather(location: str) -> str:
    """Get the current weather for a location."""
    return f"Weather in {location}: sunny, 72°F"

Dekorator rejestruje:

Parametry jako atrybuty w ramach zakresu.
Wartości zwracane jako code.function.return.value.
Obsługiwane typy: str, , intfloat, booli kolekcje (list, dict, tuple, set). Pominięto typy obiektów.

Uwaga

Zmienna OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT środowiskowa nie ma wpływu na śledzenie funkcji niestandardowych. @trace_function Dekorator zawsze śledzi parametry i wartości zwracane.

C# — użyj `ActivitySource` ręcznie

Zestaw SDK języka C# nie zawiera dekoratora śledzenia. Użyj standardowego .NET ActivitySource do instrumentowania własnych funkcji:

using System.Diagnostics;

using ActivitySource source = new("MyApp.CustomFunctions");

string FetchWeather(string location)
{
    using var activity = source.StartActivity("FetchWeather");
    activity?.SetTag("input.location", location);

    var result = $"Weather in {location}: sunny, 72°F";
    activity?.SetTag("output", result);
    return result;
}

Zarejestruj źródło niestandardowe obok źródła zestawu SDK u dostawcy śledzenia:

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Azure.AI.Projects.*")
    .AddSource("MyApp.CustomFunctions")
    .SetResourceBuilder(
        ResourceBuilder.CreateDefault().AddService("MyApp"))
    .AddConsoleExporter()
    .Build();

Programowe konfigurowanie instrumentacji (Python)

Alternatywą dla zmiennych środowiskowych jest przekazywanie parametrów konfiguracji bezpośrednio do elementu AIProjectInstrumentor().instrument():

from azure.ai.projects.telemetry import AIProjectInstrumentor

AIProjectInstrumentor().instrument(
    enable_content_recording=True,
    enable_trace_context_propagation=True,
    enable_baggage_propagation=False,
)

Parametr	Odpowiednik zmiennej środowiskowej	Domyślny
`enable_content_recording`	`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`	`False`
`enable_trace_context_propagation`	`AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION`	`True`*
`enable_baggage_propagation`	`AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE`	`False`

* Ustawieniem domyślnym jest True, gdy śledzenie jest włączone.

Gdy ustawiono zarówno parametr, jak i odpowiadającą mu zmienną środowiskową, wartość parametru ma priorytet.

Dodawanie atrybutów niestandardowych do zakresów

Python
C#

Utwórz niestandardowy element SpanProcessor do wstrzykiwania metadanych, takich jak identyfikatory sesji, do każdego zakresu:

from opentelemetry.sdk.trace import SpanProcessor, ReadableSpan
from opentelemetry.trace import Span

class CustomAttributeSpanProcessor(SpanProcessor):
    def on_start(self, span: Span, parent_context=None):
        span.set_attribute("session.id", "user-session-abc")

    def on_end(self, span: ReadableSpan):
        pass

Zarejestruj procesor za pomocą globalnego dostawcy śledzenia:

from typing import cast
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider

provider = cast(TracerProvider, trace.get_tracer_provider())
provider.add_span_processor(CustomAttributeSpanProcessor())

CustomAttributeProcessor.cs Utwórz plik z procesorem, który dodaje atrybuty po uruchomieniu każdego działania:

using System.Diagnostics;
using OpenTelemetry;

sealed class CustomAttributeProcessor : BaseProcessor<Activity>
{
    public override void OnStart(Activity activity)
    {
        activity.SetTag("session.id", "user-session-abc");
    }
}

Zarejestruj procesor w elemencie Program.cs, gdy tworzysz dostawcę modułu śledzenia:

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Azure.AI.Projects.*")
    .AddProcessor(new CustomAttributeProcessor())
    .AddConsoleExporter()
    .Build();

Odwołanie: BaseProcessor<T>

Kontroluj zachowanie śledzenia za pomocą zmiennych środowiskowych

W poniższej tabeli wymieniono wszystkie zmienne środowiskowe, których można użyć do skonfigurowania zachowania śledzenia:

Zmienna	Język	Domyślny	Opis
`AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING`	Python, C#	`false`	Włącz instrumentację śledzenia GenAI.
`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`	Python, C#	`false`	Przechwyć zawartość wiadomości i parametry wywołania narzędzia.
`AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION`	Python	`true`*	Wstrzykiwanie nagłówków kontekstu śledzenia W3C do żądań.
`AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE`	Python	`false`	Uwzględnij nagłówek `baggage` w propagacji kontekstu śledzenia.
`AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API`	Python	`true`	Automatyczne instrumentowanie odpowiedzi i interfejsów API konwersacji.
`AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA`	Python	`false`	Uwzględnij dane obrazów i plików w przedziałach (nie tylko identyfikatory plików).

* Ustawieniem domyślnym jest true, gdy śledzenie jest włączone.

Aby uzyskać pełną listę zmiennych środowiskowych i ich zachowań, zobacz funkcję śledzenia w pliku README zestawu SDK projektów Azure AI.

Bezpieczeństwo i prywatność

Śledzenie po stronie klienta może przechwytywać poufne informacje. Postępuj zgodnie z tymi rozwiązaniami, aby zmniejszyć ryzyko:

Nagrywanie zawartości: przechwytuje dane wejściowe użytkownika, odpowiedzi modelu i argumenty wywołania narzędzia. Wyłącz w środowisku produkcyjnym, chyba że jest to wymagane.
Propagacja bagażu: może ujawniać dane osobowe i dane sesji. Domyślnie wyłączone.
Propagacja kontekstu śledzenia: wysyła identyfikatory śledzenia do usług Azure. Jeśli wymagania dotyczące zgodności uniemożliwiają udostępnianie identyfikatorów śledzenia, wyłącz je.
Tajne: nie przechowuj tajnych danych, poświadczeń ani tokenów w promptach, argumentach narzędzia lub atrybutach zakresu.
Kontrola dostępu: Traktuj dane śledzenia jako produkcyjne dane telemetryczne. Zastosuj te same zasady kontroli dostępu i przechowywania, które są używane dla dzienników i metryk.

Rozwiązywanie problemów

Kwestia	Rozdzielczość
Śledzenie nie generuje żadnych zakresów	Sprawdź, czy `AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING` jest ustawiona na `true`before wywołując `AIProjectInstrumentor().instrument()` (Python) lub przed utworzeniem dostawcy śledzenia (C#).
Zawartość wiadomości nie pojawia się w sekcjach	Ustaw `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` na `true`.
Ślady nie są wyświetlane w Azure Monitor	Sprawdź, czy ciąg połączenia usługi Application Insights jest poprawny, a zasób jest dostępny. Sprawdź, czy twoje konto ma rolę Log Analytics Reader. Jeśli tabele są chronione, przypisz również rolę Uprzywilejowany czytelnik danych monitorowania.
Zakresy po stronie klienta i po stronie serwera nie są skorelowane	(Python) Sprawdź, czy propagacja kontekstu śledzenia jest włączona i czy klienci OpenAI są uzyskiwani za pośrednictwem `get_openai_client()`after instrumentacji.
Ślady pojawiają się z opóźnieniem	Ślady zwykle pojawiają się w ciągu od 2 do 5 minut w portalu Foundry oraz Azure Monitor. Poczekaj i odśwież.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-09-03

Dodawanie śledzenia po stronie klienta do agentów usługi Foundry (wersja zapoznawcza)

Wymagania wstępne

Wymagania wstępne specyficzne dla języka

Instalowanie pakietów śledzenia

Włącz śledzenie GenAI

Eksportowanie śladów do Azure Monitor

Eksportowanie śladów do konsoli

Włączanie rejestrowania zawartości

Wyłączanie instrumentacji automatycznej (Python)

Śledzenie danych binarnych (Python)

Włączanie propagacji kontekstu śledzenia (Python)

Propagacja bagażu kontrolnego (Python)

Śledzenie funkcji niestandardowych

Python — użyj dekoratora @trace_function

C# — użyj ActivitySource ręcznie

Programowe konfigurowanie instrumentacji (Python)

Dodawanie atrybutów niestandardowych do zakresów

Kontroluj zachowanie śledzenia za pomocą zmiennych środowiskowych

Bezpieczeństwo i prywatność

Rozwiązywanie problemów

Powiązana zawartość

Opinia

Dodatkowe zasoby

Python — użyj dekoratora `@trace_function`

C# — użyj `ActivitySource` ręcznie