Lägga till spårning på klientsidan i Foundry-agenter (förhandsversion)

Viktigt

Objekt markerade (förhandsversion) i den här artikeln är för närvarande i offentlig förhandsversion. Den här förhandsversionen tillhandahålls utan ett serviceavtal och vi rekommenderar det inte för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller har begränsade funktioner. Mer information finns i Supplemental Terms of Use for Microsoft Azure Previews.

Microsoft Foundry samlar automatiskt in serverloggar för agenter som körs i portalen. Spårning på klientsidan utökar den insynen i din egen programkod. Genom att instrumentera agentprogrammet med OpenTelemetry kan du samla in intervall för modellanrop, verktygsanrop och anpassad logik– och sedan exportera dem till Azure Monitor Application Insights, konsolen eller eventuella observerbarhetsservrar som stöder OpenTelemetry-protokollet (OTLP), till exempel Datadog, Grafana Tempo, Jaeger eller Honeycomb.

I den här artikeln lär du dig att:

Installera nödvändiga OpenTelemetry-spårningspaket.
Aktivera GenAI-spårningsinstrumentation för agentprogram.
Exportera spårningar till Azure Monitor, konsolen eller en OTLP-kompatibel serverdel.
Aktivera innehållsinspelning för att samla in meddelandeinnehåll.
Aktivera spårningskontextspridning för distribuerad spårning (Python).
Spåra anpassade funktioner.

Förutsättningar

Ett Foundry-projekt med en Application Insights-resurs ansluten.
En AI-modell som har distribuerats till projektet. Observera distributionsnamnet.
Azure CLI är installerat. Logga in genom att köra az login.
Deltagare eller högre roll i Foundry-projektet. Om du vill visa spårningar behöver du även Log Analytics Reader på den anslutna Application Insights-resursen. Mer information finns i Rollbaserad åtkomstkontroll i Foundry.

Följande miljövariabler anges med dina egna värden:

Variabel	Beskrivning
`FOUNDRY_PROJECT_ENDPOINT`	Slutpunkts-URL för Ditt Foundry-projekt. Hitta den på projektöversiktssidan i Foundry-portalen.
`FOUNDRY_MODEL_NAME`	Distribueringsnamnet för en AI-modell i ditt projekt. Hitta den under Modeller i Foundry-portalen.

Python 3.9 eller senare.
Paketversion azure-ai-projects 2.0.0 eller senare.

Installera spårningspaket

Python
C#

Installera Microsoft Foundry SDK, OpenTelemetry och Azure Monitor-exportören:

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

Installera OTLP-exportören för endast konsol- eller OTLP-export (till exempel Aspire Dashboard):

pip install opentelemetry-exporter-otlp

Lägg till nödvändiga NuGet-paket:

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

För ASP.NET Core program är Azure.Monitor.OpenTelemetry.AspNetCore det föredragna paketet. Paketet Azure.Monitor.OpenTelemetry.Exporter som visas här fungerar för alla .NET programtyper.

Aktivera GenAI-spårning

GenAI-spårningsinstrumentation är en experimentell förhandsversionsfunktion. Intervall, attribut och händelser kan ändras i framtida versioner. Du måste uttryckligen anmäla dig innan spårningen är aktiv.

Python
C#

AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING Ange miljövariabeln till trueinnan du anropar AIProjectInstrumentor().instrument():

import os

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

from azure.ai.projects.telemetry import AIProjectInstrumentor

# Enable instrumentation
AIProjectInstrumentor().instrument()

Om variabeln inte har angetts eller inte true är (skiftlägesokänslig) aktiveras inte spårningsinstrumentationen och en varning loggas.

Använd en AppContext växel eller samma miljövariabel:

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

När du aktiverar Azure.Experimental.EnableGenAITracing aktiverar SDK automatiskt flaggan Azure.Experimental.EnableActivitySource, vilket krävs för att OpenTelemetry-instrumentation ska fungera.

Om både växeln AppContext och miljövariabeln har angetts prioriteras växeln AppContext .

Observera

I C# accepterar alla spårningsrelaterade miljövariabler true (skiftlägesokänsliga) eller 1 som motsvarande aktiveringsvärden.

Exportera spårningar till Azure Monitor

Skicka spårningar till Azure Application Insights så att de visas i vyn Traces i Azure Monitor.

Python
C#

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)

Referens: AIProjectClient, DefaultAzureCredential, configure_azure_monitor

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

var projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
var modelName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL_NAME");

// 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."
    };
    AgentVersion agent = await projectClient.Agents.CreateAgentVersionAsync(
        agentName: "myAgent",
        options: new(agentDefinition));
    Console.WriteLine(
        $"Agent created (id: {agent.Id}, name: {agent.Name})");

    // Clean up
    projectClient.Agents.DeleteAgentVersion(
        agentName: agent.Name, agentVersion: agent.Version);
}

Referens: AIProjectClient, DefaultAzureCredential, Sdk.CreateTracerProviderBuilder

Observera

Om du vill korrelera spårningar med en specifik agent i Foundry-portalen inkluderar du agent_reference med både name och id i ditt responses.create()-anrop (som du ser i Python exemplet ovan). Spårningar visas vanligtvis inom 2–5 minuter.

Exportera spårningar till konsolen

Konsolexport är användbart för lokal felsökning. Spårningar skrivs ut direkt till standardutdata.

Python
C#

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__)

Du kan också använda Aspire Dashboard som ett lokalt OTLP-kompatibelt visningsprogram. Installera OTLP-exportören (pip install opentelemetry-exporter-otlp) och konfigurera den som exportör istället för ConsoleSpanExporter.

Referens: AIProjectInstrumentor, ConsoleSpanExporter

using Azure.AI.Projects;
using Azure.Identity;
using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

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

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

using (tracerProvider)
{
    // Agent operations emit traces to the console
}

Aktivera innehållsinspelning

Innehållsinspelning samlar in meddelandeinnehåll och verktygsanropsargument i spårningar. Dessa data kan innehålla känslig användarinformation.

Försiktighet

Innehållsinspelning samlar in användarmeddelanden, argument för verktygsanrop och modellutdata. Aktivera endast den här inställningen i utvecklingsmiljöer. Aktivera inte innehållsinspelning i produktion om inte dina efterlevnads- och sekretesskrav tillåter det.

Python
C#

Ange miljövariabeln före instrumentering:

import os

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

Viktigt

Den här variabeln styr inspelning endast för inbyggda spårningar. När du använder dekoratören @trace_function på dina egna funktioner spåras alltid alla parametrar och returvärden oavsett den här inställningen.

Använd en AppContext växel eller miljövariabeln:

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

Eller ange OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT miljövariabeln till true. Om både växeln AppContext och miljövariabeln har angetts prioriteras växeln AppContext .

Inaktivera automatisk instrumentering (Python)

Python SDK instrumenterar automatiskt OpenAI-svars- och konversations-API-anrop. Om du vill inaktivera den här automatiska instrumenteringen anger du AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API till false innan du anropar AIProjectInstrumentor().instrument(). När det är inaktiverat registreras endast explicita anpassade intervall.

import os

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

Spåra binära data (Python)

När innehållsinspelning är aktiverat spårar SDK fil-ID:t och filnamnen som standard. Om du vill inkludera fullständiga avbildnings-URL:er (inklusive base64-data-URI:er) och fildata i intervall anger du AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA till true.

import os

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

Varning

Aktivering AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA kan avsevärt öka spårningsnyttolastens storlek. Vissa spårningsserverdelar har begränsningar för den maximala storleken på span-data. Kontrollera att din observerbarhetsserverdel stöder de förväntade nyttolaststorlekarna innan du aktiverar den här inställningen.

Aktivera spårningskontextspridning (Python)

Med spårningskontextspridning kan klientsidans intervall korrelera med serversidans intervall från Azure OpenAI och andra Azure tjänster. När det är aktiverat matar SDK automatiskt in W3C Trace Context-huvuden (traceparent och tracestate) i HTTP-begäranden som görs av OpenAI-klienter som hämtas via get_openai_client().

Spårningskontextspridning aktiveras som standard när spårning är aktiverat. Om du vill inaktivera den anger du AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION miljövariabeln till falseeller skickar parametern direkt:

from azure.ai.projects.telemetry import AIProjectInstrumentor

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

Ändringar i den här inställningen påverkar endast OpenAI-klienter som hämtas via get_openai_client()efter ändringen. Tidigare förvärvade klienter påverkas inte.

Kontrollbagagespridning (Python)

Endast traceparent och tracestate rubriker sprids som standard. Om du även vill inkludera baggage rubriken anger du AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE till true.

Viktigt

Rubriken baggage kan innehålla godtyckliga nyckel/värde-par, inklusive användaridentifierare, sessionsinformation eller andra potentiellt känsliga data. Innan du aktiverar bagagespridning:

Granska vilka data som ditt program och bibliotek från tredje part lägger till i OpenTelemetry-bagaget.
Förstå att bagage skickas till Azure OpenAI och kan loggas av Azure tjänster.
Lägg aldrig till känslig information i bagaget när spridning är aktiverat.

Observera

C# SDK förlitar sig på standard .NET-propagering System.Diagnostics.Activity. Explicit spårningskontextinmatning per begäran exponeras inte som en separat SDK-funktion.

Spåra anpassade funktioner

Python – använd `@trace_function` dekoratör

Dekoratören trace_function skapar ett OpenTelemetry-intervall för varje anrop till din funktion. Parametrar registreras som code.function.parameter.<name> och returvärdet som 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"

Om du vill använda ett anpassat spannnamn i stället för funktionsnamnet skickar du det som en parameter:

@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"

Dekoratören registrerar:

Parametrar som code.function.parameter.<name> span-attribut.
Returnera värden som code.function.return.value.
Typer som stöds: str, int, float, booloch samlingar (list, dict, tuple, set). Objekttyper utelämnas.

Observera

Miljövariabeln OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT påverkar inte anpassad funktionsspårning. Dekoratören @trace_function spårar alltid parametrar och returnerar värden.

C# – använd `ActivitySource` manuellt

C# SDK innehåller ingen spårningsdekoratör. Använd standard-.NET ActivitySource för att instrumentera dina egna funktioner:

using System.Diagnostics;

// Define a custom activity source
private static readonly ActivitySource s_source = new("MyApp.CustomFunctions");

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

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

Registrera din anpassade källa tillsammans med SDK-källan i spårningsprovidern:

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

Konfigurera instrumentation programmatiskt (Python)

Som ett alternativ till miljövariabler skickar du konfigurationsparametrarna direkt till AIProjectInstrumentor().instrument():

from azure.ai.projects.telemetry import AIProjectInstrumentor

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

Parameter	Motsvarande miljövariabel	Standard
`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`

* Standard är True när spårning är aktiverat.

När både en parameter och dess motsvarande miljövariabel anges prioriteras parametervärdet.

Lägga till anpassade attribut i intervall (Python)

Skapa en anpassad SpanProcessor för att injicera metadata, såsom sessions-ID, i varje span.

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

Registrera processorn med den globala spårningsprovidern:

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

Kontrollera spårningsbeteende med miljövariabler

I följande tabell visas alla miljövariabler som du kan använda för att konfigurera spårningsbeteende:

Variabel	Språk	Standard	Beskrivning
`AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING`	Python, C#	`false`	Aktivera GenAI-spårningsinstrumentation.
`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`	Python, C#	`false`	Avbilda meddelandeinnehåll och verktygsanropsparametrar.
`AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION`	Python	`true`*	Inför W3C Trace Context-huvuden i förfrågningar.
`AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE`	Python	`false`	Inkludera `baggage`-headern i spårkontextutbredning.
`AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API`	Python	`true`	Api:er för autoinstrumentsvar och konversationer.
`AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA`	Python	`false`	Inkludera bild- och fildata i intervall (inte bara fil-ID:t).

* Standard är true när spårning är aktiverat.

En fullständig lista över miljövariabler och deras beteende finns i Spårning i Azure AI Projects SDK README.

Säkerhet och sekretess

Spårning på klientsidan kan samla in känslig information. Följ dessa metoder för att minska risken:

Innehållsinspelning: Samlar in användarindata, modellsvar och argument för verktygsanrop. Inaktivera i produktion om det inte krävs.
Bagagespridning: Kan exponera PII- och sessionsdata. Inaktiverad som standard.
Trace-kontextspridning: Skickar spårnings-ID:n till Azure-tjänster. Om efterlevnadskrav förbjuder delning av spårningsidentifierare inaktiverar du det.
Hemligheter: Lagra inte hemligheter, autentiseringsuppgifter eller token i prompter, verktygsargument eller span-attribut.
Åtkomstkontroll: Behandla spårningsdata som produktionstelemetri. Tillämpa samma åtkomstkontroller och kvarhållningsprinciper som du använder för loggar och mått.

Felsökning

Frågan	Upplösning
Spårning ger inga intervall	Kontrollera att `AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING` är inställt på `true`innan du anropar `AIProjectInstrumentor().instrument()` (Python) eller innan du skapar tracer-providern (C#).
Meddelandeinnehållet visas inte i intervall	Ange `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` till `true`.
Spårningar visas inte i Azure Monitor	Kontrollera att Application Insights-reťazec pripojenia är korrekt och att resursen är tillgänglig. Kontrollera att ditt konto har rollen Log Analytics Reader.
Intervallen på klientsidan och serversidan är inte korrelerade	(Python) Kontrollera att spårningskontextspridning är aktiverat och att OpenAI-klienter hämtas via instrumentationen `get_openai_client()`after.
Spårningar visas med en fördröjning	Spårningar tar vanligtvis 2–5 minuter att visas i Foundry-portalen och Azure Monitor. Vänta och uppdatera.

Feedback

Var den här sidan till hjälp?

Last updated on 2026-04-29

Lägga till spårning på klientsidan i Foundry-agenter (förhandsversion)

Förutsättningar

Språkspecifika krav

Installera spårningspaket

Aktivera GenAI-spårning

Exportera spårningar till Azure Monitor

Exportera spårningar till konsolen

Aktivera innehållsinspelning

Inaktivera automatisk instrumentering (Python)

Spåra binära data (Python)

Aktivera spårningskontextspridning (Python)

Kontrollbagagespridning (Python)

Spåra anpassade funktioner

Python – använd @trace_function dekoratör

C# – använd ActivitySource manuellt

Konfigurera instrumentation programmatiskt (Python)

Lägga till anpassade attribut i intervall (Python)

Kontrollera spårningsbeteende med miljövariabler

Säkerhet och sekretess

Felsökning

Relaterat innehåll

Feedback

Ytterligare resurser

Python – använd `@trace_function` dekoratör

C# – använd `ActivitySource` manuellt