Samla in och inspektera spårningar i Microsoft Foundry Toolkit

Använd Microsoft Foundry Toolkit för Visual Studio Code för att samla in lokala spårningar eller visa telemetri för agenter som distribuerats till Microsoft Foundry. En trace grupperar registrerade åtgärder för en begäran. Varje åtgärd är ett span med tidsinformation, status och eventuella attribut eller händelser som tillhandahålls av instrumentationen.

Den här artikeln beskriver först lokal samling och sedan molnspårning för driftsatta agenter. Välj den datakälla som matchar din utredning:

Approach	Använd den för	Data och ansvarsområden
Agentinspektör	Skicka en lokal begäran, granska livesvar och verktygshändelser eller pausa kod vid en brytpunkt.	Servern tillhandahåller protokollhändelser och utvecklingsdiagnostik. Den här metoden kräver inte OTLP-insamlaren och skapar inte molnspårningshistorik.
Lokal spårning	Jämför registrerade modell-, verktygs- och agentspann under utvecklingen.	Ditt program exporterar telemetri till Toolkits lokala insamlare. Du konfigurerar instrumentering och hanterar lagrade lokala data.
Spårning av värdhanterad agent	Undersök begäranden som hanteras av en agent som driftsatts till Foundry.	Spårningar finns i projektets anslutna Application Insights-resurs. Åtkomst, kvarhållning och avgifter följer Azure resurskonfiguration.

En hostad agent kör din anpassade kod i Foundry Agent Service. Foundry hanterar värdtjänster, men du är fortfarande ansvarig för koden och beroendena. Spårning ersätter inte skapande och driftsättning av agenten.

Prerequisites

Visual Studio Code med det aktuella offentliga Foundry Toolkit-tillägget. Se Installera Foundry Toolkit.
Ett program som du kan köra lokalt, med dess modell- och verktygsanslutningar konfigurerade.
För det första exemplet ett Python Microsoft Agent Framework-program och dess valda Python miljö. För andra SDK:er använder du Python-konfigurationen eller JavaScript och TypeScript-konfigurationen.
För molnspårning krävs en installerad agent och en Application Insights-resurs som är ansluten till Foundry-projektet, eller behörighet att ansluta till eller skapa en.
För molnfrågor krävs Log Analytics Reader-role på den anslutna Application Insights-resursen. För skyddade tabeller tilldelar du även rollen Privilegierad övervakningsdataläsare. Se förhandskraven för Foundry-spårning.

Lokal samling kräver inte Application Insights- eller molntelemetribehörigheter. Modellanrop och verktygskörning kan fortfarande använda fjärrtjänster och medföra avgifter.

Samla in lokala spår

Den lokala insamlaren tar emot telemetri via OpenTelemetry Protocol (OTLP). Det instrumenterar inte ett program automatiskt. Ditt ramverk eller ett instrumentationsbibliotek måste skapa spanar och exportera dem till kollektorn.

SDK och språkkonfiguration

SDK:er med inbyggd instrumentering behöver fortfarande en exportör. Andra SDK:er använder ett separat instrumentationspaket.

SDK eller ramverk	Python	JavaScript och TypeScript (Node.js)
Microsoft Agent Framework	Inbyggd OpenTelemetry-instrumentation.	Ingen vägledning för konfiguration av dedikerad Toolkit.
Azure AI Inference SDK (förhandsversion)	Azure SDKs instrumentor.	Azure SDKs instrumentation.
Foundry Projects SDK	Instrumentering på klientsidan (förhandsversion).	Instrumentera den underliggande OpenAI- eller Azure-SDK-klienten.
Foundry classic Agents SDK	Azure SDKs instrumentor.	Inga särskilda anvisningar för att konfigurera Toolkit.
Anthropic	OpenLLMetry instrumenteringsverktyg.	Traceloop-instrumentering.
Google GenAI (Gemini)	Google GenAI OpenTelemetry instrumentor.	Ingen särskild vägledning för konfiguration av Toolkit.
LangChain	OpenLLMetry-instrumentor.	Traceloop instrumentering.
OpenAI SDK, inklusive Azure OpenAI-klienter	OpenLLMetry instrumenterare.	Traceloop-instrumentering.
OpenAI Agents SDK	OpenLLMetry-spårprocessor.	Ingen särskild vägledning för konfiguration av Toolkit.

"Ingen dedikerad vägledning för konfiguration av Toolkit" innebär att det inte finns någon SDK-specifik konfigurationsväg här för det aktuella språket, inte att insamlaren avvisar telemetri från det språket. Collector tar emot OTLP-data. Instrumenteringen avgör vilka operationer och meddelandedetaljer som ska samlas in.

De här exemplen använder ett urval av instrumenteringsalternativ och är inte en uttömmande lista över kompatibla bibliotek. OpenLLMetry- och Traceloop-instrumentation är bibliotek som inte kommer från Microsoft.

Konfigurera telemetri

Använd den här proceduren med en befintlig Python Agent Framework-applikation. Behåll agenten och collectorn i samma lokala miljö för den här genomgången.

Välj Foundry Toolkit i aktivitetsfältet och sedan Utvecklarverktyg>Övervaka>spårning.
Välj Start Collector innan du kör programmet.
Installera gRPC-exportören i programmets Python miljö om den inte redan har deklarerats i dina beroenden:
```
python -m pip install opentelemetry-exporter-otlp-proto-grpc
```
Referens: OpenTelemetry Python OTLP-exportörer.
Konfigurera OpenTelemetry en gång vid programstart, innan du instansierar eller kör agenten:
```
import os

os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://localhost:4317"
os.environ["OTEL_EXPORTER_OTLP_PROTOCOL"] = "grpc"

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_sensitive_data=False)
```
Referens: Observerbarhet för Agent Framework.

Om ditt program eller värdbibliotek redan konfigurerar OpenTelemetry-leverantörer konfigurerar du dess befintliga exportörer i stället för att lägga till en annan leverantörskonfiguration. Signalspecifika OTEL_EXPORTER_OTLP_*_ENDPOINT variabler kan åsidosätta grundslutpunkten. Kontrollera om det finns befintliga inställningar för spårning, loggning eller mätvärden som pekar mot någon annan plats.
Kör programmet med dess normala startpunkt och skicka en begäran som aktiverar agenten. Låt förfrågan slutföras och ge exportören tid att skicka telemetri innan processen stoppas.
I Spårning väljer du Uppdatera och sedan den nya spårningen för att inspektera dess spann.

Agent Framework stöder modellklienter, agenter och arbetsflödesåtgärder. Andra ramverk kan kräva ett instrumentationsbibliotek. OTLP-kompatibilitet gör att insamlaren kan ta emot data, medan utgivna attribut och generativa AI-semantiska konventioner avgör vad visningsprogrammet visar.

För ett annat SDK eller språk använder du konfigurationen nedan i stället för Agent Framework-konfigurationen. Starta insamlaren först, konfigurera instrumentering innan du skapar klienter, kör sedan programmet och uppdatera spårningslistan.

Collector-slutpunkter

Anpassa exportörens protokoll till kollektorns slutpunkt. Toolkit lyssnar på localhost med följande standardvärden:

Exportör	Endpoint
OTLP gRPC	`http://localhost:4317`
OTLP HTTP-spår-exportör	`http://localhost:4318/v1/traces`
OTLP HTTP-loggexportör	`http://localhost:4318/v1/logs`

Vissa HTTP-exportörer accepterar http://localhost:4318 och lägger själva till signalens sökväg. Följ exportörens konfiguration i stället för att lägga till sökvägen två gånger. Vissa instrumentationsbibliotek skickar meddelandeinnehåll som loggposter, så export av enbart spann kanske inte ger information om indata och utdata.

Dessa portar är inte relaterade till agentens HTTP-server och felsökningsportar. I en container eller fjärrutvecklingsmiljö avser localhost den miljön. Upprätta lämplig anslutning till kollektorn i stället för att anta att den syftar på skrivbordet.

Python SDK-konfiguration

Följande exempel förutsätter att ditt program redan har sin modell-SDK, sina autentiseringsuppgifter och modellkonfigurationen. Installera de delade beroendena och det ytterligare paketet för SDK:t från följande tabell:

python -m pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

Referens: OpenTelemetry Python SDK, OTLP-exportörer.

Lägg till den här delade konfigurationen en gång vid programstart, följt av instrumenteringen från en tabellrad. Kombinera den inte med konfigurationen för ett annat biblioteks provider.

import os

os.environ["TRACELOOP_TRACE_CONTENT"] = "false"
os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "false"
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "false"

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
    OTLPSpanExporter,
)

provider = TracerProvider(
    resource=Resource.create({"service.name": "my-agent"})
)
provider.add_span_processor(BatchSpanProcessor(
    OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
))
trace.set_tracer_provider(provider)

Referens: TracerProvider och spanprocessorer, OTLPSpanExporter.

Installera paketet i den valda raden med python -m pip install <package>. OpenAI, Anthropic, LangChain och separata OpenAI Agents-exempel använder icke-Microsoft OpenLLMetry-instrumentation. SDK-versioner och modell-API:er kan ge olika detaljer.

SDK	Ytterligare paket	Instrumentation efter den gemensamma konfigurationen
OpenAI, inklusive Azure OpenAI-klienter	`opentelemetry-instrumentation-openai`	`from opentelemetry.instrumentation.openai import OpenAIInstrumentor` `OpenAIInstrumentor().instrument()`
Anthropic	`opentelemetry-instrumentation-anthropic`	`from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor` `AnthropicInstrumentor().instrument()`
LangChain	`opentelemetry-instrumentation-langchain`	`from opentelemetry.instrumentation.langchain import LangchainInstrumentor` `LangchainInstrumentor().instrument()`
Google GenAI	`opentelemetry-instrumentation-google-genai`	`os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "NO_CONTENT"` `from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor` `GoogleGenAiSdkInstrumentor().instrument()`
Klientsidespårning för Foundry Projects (förhandsversion)	`azure-core-tracing-opentelemetry`, tillsammans med `azure-ai-projects`	`os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"` `from azure.ai.projects.telemetry import AIProjectInstrumentor` `AIProjectInstrumentor().instrument(enable_content_recording=False)`
Foundry classic Agents SDK	`azure-core-tracing-opentelemetry`, tillsammans med `azure-ai-agents`	`os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry"` `from azure.ai.agents.telemetry import AIAgentsInstrumentor` `AIAgentsInstrumentor().instrument()`
Azure AI Inference SDK (förhandsversion)	`azure-core-tracing-opentelemetry`, tillsammans med `azure-ai-inference`	`os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry"` `from azure.ai.inference.tracing import AIInferenceInstrumentor` `AIInferenceInstrumentor().instrument()`

För Foundry Projects, följ vägledningen för spårning på klientsidan och skapa dess OpenAI-klient efter instrumentering. Den här vägledningen skiljer sig från det klassiska Agents SDK:t. Instrumentera inte samma OpenAI-anrop med både AIProjectInstrumentor och en separat OpenAI-instrumentor.

För OpenAI Agents SDK, installera opentelemetry-instrumentation-openai-agents och lägg till den här koden efter den delade konfigurationen:

from agents import set_trace_processors
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor

set_trace_processors([])
OpenAIAgentsInstrumentor().instrument()

Referens: OpenAI Agents-instrumentation, OpenAI-agentspårning.

Det här exemplet ersätter befintliga spårningsprocessorer innan OpenTelemetry-processorn läggs till. Utan den ersättningen kan SDK:et också exportera spårningar till standardbakände. Om du behöver använda befintliga processorer granskar du spårningsmålen innan du ändrar dem. Behåll SDK-spårning aktiverat så att OpenTelemetry-processorn tar emot händelser.

När ett kortlivat program har slutfört sina begäranden, anropa provider.force_flush() innan du avslutar för att skicka buffrade spaner. Om du vill ha hjälp med att anpassa de här kodfragmenten använder du verktyget Tracing Code Gen i Toolkit.

Exportera posterna i meddelandeloggen

Vissa instrumentorer avger meddelandeinnehåll som OpenTelemetry-loggposter i stället för span-attribut. Om du väljer att logga innehållet i ett kontrollerat utvecklingstest lägger du till den här konfigurationen en gång tillsammans med föregående Python spårningsprovider:

from opentelemetry import _logs
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

logger_provider = LoggerProvider(resource=provider.resource)
logger_provider.add_log_record_processor(BatchLogRecordProcessor(
    OTLPLogExporter(endpoint="http://localhost:4318/v1/logs")
))
_logs.set_logger_provider(logger_provider)

Referens: OpenTelemetrys loggnings-SDK för Python, OTLPLogExporter.

Anropa logger_provider.force_flush() innan du avslutar ett kortlivat program. En loggexportör aktiverar inte innehållsinsamlingen av sig själv. Följ instrumentets innehållsinställningar och vägledningen för datahantering.

Konfiguration av JavaScript- och TypeScript-SDK

För Node.js program delar du en spårningsprovider och registrerar instrumentationen för ditt SDK. I det här exemplet används CommonJS och OpenTelemetry JavaScript 2.x-providerkonfigurationen. TypeScript-program som kompilerats till CommonJS kan använda samma initieringsordning.

Ditt program måste redan ha sin modell-SDK, autentiseringsuppgifter och modellkonfiguration. Installera de delade beroendena och OpenAI-instrumentorn:

npm install @opentelemetry/api @opentelemetry/sdk-trace-node \
  @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/instrumentation @traceloop/instrumentation-openai

Referens: OpenTelemetry JavaScript-exportörer, OpenAI-instrumentation.

Skapa tracing.cjs:

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const {
  OTLPTraceExporter
} = require('@opentelemetry/exporter-trace-otlp-proto');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { OpenAIInstrumentation } = require('@traceloop/instrumentation-openai');

const provider = new NodeTracerProvider({
  spanProcessors: [
    new BatchSpanProcessor(new OTLPTraceExporter({
      url: 'http://localhost:4318/v1/traces'
    }))
  ]
});
provider.register();

registerInstrumentations({
  instrumentations: [new OpenAIInstrumentation({ traceContent: false })]
});

module.exports = provider;

Referens: NodeTracerProvider, OpenAI-instrumentation.

Läs in den här filen innan du importerar eller använder require för din modell-SDK. Kör till exempel kommandot node --require ./tracing.cjs app.cjs för ett CommonJS-program. För en annan SDK ersätter du OpenAI-paketet, importen och posten för registrering med den matchande raden:

SDK	Instrumentpaket	Import- och registreringsregistrering
OpenAI, inklusive Azure OpenAI-klienter	`@traceloop/instrumentation-openai`	`const { OpenAIInstrumentation } = require('@traceloop/instrumentation-openai');` `new OpenAIInstrumentation({ traceContent: false })`
Anthropic	`@traceloop/instrumentation-anthropic`	`const { AnthropicInstrumentation } = require('@traceloop/instrumentation-anthropic');` `new AnthropicInstrumentation({ traceContent: false })`
LangChain	`@traceloop/instrumentation-langchain`	`const { LangChainInstrumentation } = require('@traceloop/instrumentation-langchain');` `new LangChainInstrumentation({ traceContent: false })`
Azure SDKs-operationer, inklusive Azure AI Inference	`@azure/opentelemetry-instrumentation-azure-sdk`	`const { createAzureSdkInstrumentation } = require('@azure/opentelemetry-instrumentation-azure-sdk');` `createAzureSdkInstrumentation()`

Traceloop-paketen är inte instrumentation från Microsoft. För ett Foundry Projects-program instrumenterar du klienten som gör modellbegäran. Azure SDKs instrumentation ersätter inte OpenAI-instrumentation för anrop som görs via en OpenAI-klient.

För nativa ECMAScript-moduler följer du OpenTelemetrys ESM-installation. Inläsning av instrumentation efter mål-SDK kan lämna anrop oinstrumenterade. Vid avstängning väntar du provider.shutdown() efter att begäranden har slutförts för att exportera buffrade spaner.

Important

De här exemplen inaktiverar insamling av meddelandeinnehåll för de listade GenAI-instrumenterarna. Detta är inte en allmän maskeringsgaranti. Granska andra exportörer, SDK-loggning, span-attribut och anpassad instrumentation innan du delar data. Kontrollera den länkade instrumentordokumentationen för paket och API:er som stöds.

Inspektera och hantera lokala spår

Använd span-trädet för att följa begäran från agentorkestrering till modell- och verktygsåtgärder.

Välj ett långsamt eller misslyckat span.
Kontrollera dess varaktighet och status.
Öppna Input + Output för inspelade meddelanden, när de tillhandahålls av instrumentationen, eller Metadata för span-attribut.

Exemplen har insamling av känsligt innehåll avstängd. Tidsdata utan meddelanden kan vara det förväntade resultatet.

För ett kontrollerat Agent Framework-utvecklingstest anger du enable_sensitive_data=True i den befintliga konfigurationen för att registrera prompt, svar och verktygsinnehåll som stöds. Återställ den till False när testet är klart. Andra instrumentors har egna innehållsinställningar.

Caution

Innehållsinspelning kan fånga upp personuppgifter, hemligheter, verktygsargument och resultat. Använd icke-känsliga testdata och minimera eller maskera innehåll innan det skickas till telemetrin. Aktivera inte inspelning av produktionsinnehåll enbart för att fylla en tom indata- och utdatavy.

Insamlade spårningar finns kvar i en lokal SQLite-databas med namnet traces.db, i underkatalogen tracing i .aitk under din hemmapp. Om du stänger visningsprogrammet tas de inte bort.

Välj Stoppa Collector för att stoppa lokal insamling. Agenten och dess modellanrop fortsätter att köras. Om du vill ta bort lokala poster väljer du spåren i listan och väljer Ta bort.

Lokal lagring är separat från Application Insights. Om du tar bort lokala spårningar tas inte molntelemetri bort, och om du rensar en konversation i Inspector tas ingen av de två lagringsplatserna bort.

Visa spår för hostad agent

Efter driftsättning använder du molnspår för att undersöka agenten som körs i Foundry i stället för din lokala process. Toolkit frågar projektets anslutna Application Insights-resurs. Den laddar inte upp din lokala spårningsdatabas.

Bekräfta molnkraven innan du startar. Åtkomst till enbart agenten ger inte behörighet att köra frågor mot telemetridata.

Anslut Application Insights och inspektera en begäran

Använd agentens fliken Spårningar för att ansluta Application Insights och hitta en begäran om distribuerad agent.

I sidofältet Foundry Toolkit öppnar du Minaresursagenter>. Välj fliken Värdbaserad agent och välj sedan agentens namn.
Välj Spår. Om projektet inte har någon ansluten resurs väljer du Aktivera App Insights.
I App Insights-inställningar väljer du ett befintligt Application Insights-resursnamn. Du kan också välja att skapa en resurs och slutföra de nödvändiga fälten för resurs och arbetsyta. Välj Skicka och vänta på bekräftelse.

Detta ändrar projektets delade Application Insights-anslutning, inte en lokal arbetsyteinställning. Resursskapande och telemetrisamling kan medföra Azure avgifter. Bekräfta det avsedda projektet och resursen innan du skickar.
Gå tillbaka till Playground och skicka en testbegäran till den driftsatta agenten.
Tillåt tid för inhämtning och öppna sedan Traces igen. Använd filter för tidsintervall, Sök efter konversations-ID, Status eller Varaktighet för att hitta begäran.
Välj ett spår, sedan ett span, för att granska metadata och indata + utdata, när innehåll är tillgängligt.

Om du vill inspektera åtgärder som är associerade med en konversation väljer du dess konversations-ID i spårningslistan. Konversationsvyn visar ett åtgärdsträd och metadata.

Genom att ansluta Application Insights aktiveras Foundrys spårning på serversidan. Synlighet för dina modellanrop, verktygsanrop och anpassad kod beror också på värdbiblioteket och ramverksinstrumentationen. Se Konfigurera spårning i Foundry för samling på tjänstsidan och ytterligare klientinstrumentation.

Toolkits trace-detail-fråga omfattar för närvarande de senaste sju dagarna. Det här är en frågeruta, inte en lagringsinställning. För äldre data använder du Foundry-portalen eller Azure Monitor, beroende på den anslutna arbetsytans kvarhållningskonfiguration.

Data, åtkomst, lagringstid och kostnad

Bestäm var telemetridata ska skickas innan du aktiverar insamling av innehåll eller ansluter en molnresurs. Samma begäran kan generera lokala spans, molntelemetri och data som skickas till modell- eller verktygsleverantörer.

Datakälla	Responsibilities
Lokala spår	Skydda åtkomsten till den lokala databasen och kopierade data. Om du stoppar insamlaren stoppas inte andra exportörer som konfigurerats i ditt program.
Molnspår	Application Insights och Log Analytics styr åtkomst, lagringstid och telemetriavgifter. Verktygsfilter ändrar inte dessa policyer.
Anrop till modeller och verktyg	Lokal kollektion hindrar inte begäranden från att lämna datorn. Granska alla anslutna tjänsters datahantering, inklusive verktyg som inte är Microsoft.

Använd Foundry-spårningsvägledningen för säkerhet och sekretess och datalagring och kostnader. För produktionsidentitet, nätverksisolering och nedströmsåtkomst följer du säkerhets- och datahantering för hostad agent. Behandla inte lokala autentiseringsuppgifter som den distribuerade agentens behörigheter.

Troubleshooting

Issue	Vad du bör kontrollera
Spårning är inte tillgängligt i sidofältet.	Bekräfta att det aktuella tillägget är installerat och aktiverat i miljön där du kör det. Lokal spårning kräver att dess plattformsspecifika SQLite-komponent läses in.
Insamlaren startar inte.	Sök efter en annan process med port 4317 eller 4318 och granska Toolkit-utdata. Undvik konkurrerande collectorer på samma portar.
En lokal begäran lyckas men inga spår visas.	Bekräfta att instrumentationen körs före begäran, att insamlaren körs och att exportören använder rätt protokoll och ändpunkt. Kontrollera åsidosättningar av ändpunkter, exportfel och buffrad telemetri och välj sedan Uppdatera.
Spann visas utan meddelanden.	Kontrollera inställningar för innehållsinspelning och attribut som stöds. Vissa bibliotek kräver också en loggexportör. Innehåll som saknas betyder inte nödvändigtvis att insamlingen misslyckades.
Cloud-spår är tomma.	Bekräfta projektet och Application Insights-anslutningen, generera ny trafik, utöka tidsintervallet och tillåt fördröjning i datainhämtning.
Frågor i molnet misslyckas på grund av ett behörighetsfel.	Kontrollera läsbehörigheten till Application Insights och Log Analytics, inklusive skyddade tabeller, med hjälp av förutsättningar för tjänsten.
En äldre spårning innehåller inga detaljer i Toolkit.	Detaljfrågan omfattar sju dagar. Sök i äldre bevarade poster i Foundry eller Azure Monitor.

Feedback

Var den här sidan till hjälp?

Uppdaterades senast 2026-10-08