Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Belangrijk
Items die zijn gemarkeerd als voorbeeld in dit artikel, zijn momenteel beschikbaar als preview-versie. Deze preview wordt aangeboden zonder een service level agreement en Microsoft raadt dit niet aan voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure previews voor meer informatie.
Microsoft Foundry legt automatisch server-side traceringen vast voor agents die in de portal draaien. Tracering aan de clientzijde breidt die zichtbaarheid uit in uw eigen toepassingscode. Door uw agenttoepassing te instrumenteren met OpenTelemetry, kunt u spans vastleggen voor modelaanroepen, hulpprogrammaaanroepen en aangepaste logica. Exporteer ze vervolgens naar Azure Monitor Application Insights, de console of een waarneembaarheidsback-end die ondersteuning biedt voor het OpenTelemetry-protocol (OTLP), zoals Datadog, Grafana Tempo, Jaeger of Honeycomb.
In dit artikel leert u het volgende:
- Installeer de vereiste OpenTelemetry-traceringspakketten.
- Schakel GenAI-traceringsinstrumentatie in voor agenttoepassingen.
- Exporteer traceringen naar Azure Monitor, de console of een back-end die compatibel is met OTLP.
- Opname van inhoud inschakelen om de inhoud van berichten vast te leggen.
- Traceringscontextdoorgifte inschakelen voor gedistribueerde tracering (Python).
- Aangepaste functies traceren.
Voorwaarden
Een Foundry-project met een verbonden Application Insights-resource.
Een AI-model dat is geïmplementeerd in het project. Noteer de implementatienaam.
Azure CLI geïnstalleerd. Meld u aan door
az loginuit te voeren.Inzender of hogere rol in het Foundry-project. Als u traceringen wilt weergeven, hebt u ook Log Analytics Reader nodig voor de verbonden Application Insights-resource. Als deze Log Analytics tabellen zijn beveiligd, wijst u ook Bevoegde bewakingsgegevenslezer toe. Zie Op rollen gebaseerd toegangsbeheer in Foundry voor meer informatie.
De volgende omgevingsvariabelen zijn ingesteld met uw eigen waarden:
Variabele Beschrijving FOUNDRY_PROJECT_ENDPOINTDe eindpunt-URL van uw Foundry-project. Zoek het op de projectoverzichtspagina in de Foundry-portal. FOUNDRY_MODEL_NAMEDe implementatienaam van een AI-model in uw project. Zoek het onder Modellen in de Foundry-portal.
Taalspecifieke vereisten
- Python 3.10 of hoger.
- Het
azure-ai-projectspakket versie 2.0.0 of hoger.
Traceringspakketten installeren
Installeer de Microsoft Foundry SDK, OpenTelemetry en de Azure Monitor exporteur:
pip install azure-ai-projects opentelemetry-sdk azure-core-tracing-opentelemetry azure-monitor-opentelemetry
Installeer voor alleen-console- of OTLP-export (bijvoorbeeld Aspire Dashboard) de OTLP-exporteur:
pip install opentelemetry-exporter-otlp
GenAI-tracering inschakelen
GenAI-traceringsinstrumentatie is een experimentele preview-functie. Spans, attributen en gebeurtenissen kunnen in toekomstige versies veranderen. U moet zich expliciet aanmelden voordat tracering actief is.
Stel de AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING omgevingsvariabele in trueop voordat u aanroept AIProjectInstrumentor().instrument():
import os
os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"
from azure.ai.projects.telemetry import AIProjectInstrumentor
# Enable instrumentation
AIProjectInstrumentor().instrument()
Als de variabele niet is ingesteld of niet true (hoofdlettergevoelig), is traceringsinstrumentatie niet ingeschakeld en wordt er een waarschuwing vastgelegd.
Traceringen exporteren naar Azure Monitor
Verzend traceringen naar Azure-toepassing Insights zodat ze worden weergegeven in de Tracesweergave en in Azure Monitor.
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"]
AGENT_NAME = "MyAgent"
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"):
# Create an agent
agent = project.agents.create_version(
agent_name=AGENT_NAME,
definition=PromptAgentDefinition(
model=os.environ["FOUNDRY_MODEL_NAME"],
instructions="You are a helpful assistant.",
),
)
print(f"Agent created (id: {agent.id}, name: {agent.name})")
with project.get_openai_client(agent_name=agent.name) as openai:
# Create a conversation and get a response
conversation = openai.conversations.create()
response = openai.responses.create(
conversation=conversation.id,
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)
Verwijzing: AIProjectClient, DefaultAzureCredential, configure_azure_monitor
Opmerking
Als u traceringen wilt correleren met een specifieke agent in de Foundry-portal, neemt u de agent_reference op met zowel name als id in uw responses.create()-aanroep (zoals wordt weergegeven in het bovenstaande Python voorbeeld). Traces worden doorgaans binnen 2-5 minuten zichtbaar.
Traceringen exporteren naar de console
Consoleexport is handig voor lokale foutopsporing. Traceringen worden rechtstreeks naar standaarduitvoer afgedrukt.
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__)
U kunt Aspire Dashboard ook gebruiken als een lokale OTLP-compatibele viewer. Installeer de OTLP-exporteur (pip install opentelemetry-exporter-otlp) en configureer deze als de exporteur in plaats van ConsoleSpanExporter.
Naslaginformatie: AIProjectInstrumentor, ConsoleSpanExporter
Opname van inhoud inschakelen
Met inhoudsopname worden berichtinhoud en argumenten voor het aanroepen van hulpprogramma's vastgelegd in traceringen. Deze gegevens kunnen gevoelige gebruikersgegevens bevatten.
Voorzichtigheid
Met de inhoudsopname worden gebruikersberichten, argumenten voor het aanroepen van hulpprogramma's en modeluitvoer vastgelegd. Schakel deze instelling alleen in in ontwikkelomgevingen. Schakel het opnemen van inhoud niet in in productie, tenzij uw nalevings- en privacyvereisten dit toestaan.
Stel de omgevingsvariabele in voordat u instrumenteert:
import os
os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "true"
Belangrijk
Deze variabele regelt de opname uitsluitend voor ingebouwde traces. Wanneer u de @trace_function decorator op uw eigen functies gebruikt, worden alle parameters en retourwaarden altijd getraceerd, ongeacht deze instelling.
Automatische instrumentatie uitschakelen (Python)
De Python SDK instrumenteert automatisch OpenAI-antwoorden en gesprekken-API-aanroepen. Als u deze automatische instrumentatie wilt uitschakelen, stelt u deze in AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_APIfalse voordat u aanroept AIProjectInstrumentor().instrument(). Wanneer de functie is uitgeschakeld, worden alleen expliciete aangepaste spans vastgelegd.
import os
os.environ["AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API"] = "false"
Binaire gegevens traceren (Python)
Wanneer het opnemen van inhoud is ingeschakeld, traceert de SDK standaard bestands-id's en bestandsnamen. Als u volledige afbeeldings-URL's (inclusief base64-gegevens-URI's) en bestandsgegevens in spanten wilt opnemen, stelt u deze in AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA op true.
import os
os.environ["AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA"] = "true"
Waarschuwing
Het inschakelen van AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA kan de trace-payload aanzienlijk vergroten. Sommige traceringssystemen hebben beperkingen voor de maximale grootte van spangegevens. Controleer of uw observability backend de verwachte payload-groottes ondersteunt voordat u deze instelling inschakelt.
Traceercontext-inschakeling inschakelen (Python)
Het doorgeven van traceringscontext maakt het mogelijk om clientzijde-traces te correleren met serverzijde-traces van Azure OpenAI en andere Azure-services. Wanneer deze optie is ingeschakeld, injecteert de SDK automatisch W3C Trace Context-headers (traceparent en tracestate) in HTTP-aanvragen die zijn gedaan door OpenAI-clients die zijn verkregen via get_openai_client().
Traceercontextoverdracht is standaard ingeschakeld wanneer tracering is ingeschakeld. Als u deze wilt uitschakelen, stelt u de AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION omgevingsvariabele falsein op of geeft u de parameter rechtstreeks door:
from azure.ai.projects.telemetry import AIProjectInstrumentor
# Disable trace context propagation
AIProjectInstrumentor().instrument(enable_trace_context_propagation=False)
Wijzigingen in deze instelling zijn alleen van invloed op OpenAI-clients die get_openai_client() de wijziging zijn verkregen. Eerder aangeschafte clients worden niet beïnvloed.
Bagagepropagatie beheren (Python)
Standaard worden alleen traceparent kopteksten en tracestate kopteksten doorgegeven. Als u ook de baggage koptekst wilt opnemen, stelt u AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE in op true.
Belangrijk
De baggage header kan willekeurige sleutel-waardeparen bevatten, waaronder gebruikers-id's, sessiegegevens of andere mogelijk gevoelige gegevens. Voordat u baggage propagatie inschakelt:
- Controleer welke gegevens uw toepassing en bibliotheken van derden toevoegen aan OpenTelemetry-bagage.
- Begrijp dat bagage wordt verzonden naar Azure OpenAI en kan worden geregistreerd door Azure services.
- Voeg nooit gevoelige informatie toe aan bagage wanneer doorgifte is ingeschakeld.
Opmerking
De C#-SDK hangt af van de standaard .NET-propagatie System.Diagnostics.Activity. Expliciete traceringscontextinjectie per aanvraag wordt niet weergegeven als een afzonderlijke SDK-functie.
Aangepaste functies traceren
Python — gebruik de @trace_function decorator
De trace_function decorator maakt een OpenTelemetry-span voor elke aanroep naar uw functie. Parameters worden vastgelegd als code.function.parameter.<name> en de retourwaarde als 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"
Als u een aangepaste spannaam wilt gebruiken in plaats van de functienaam, geeft u deze door als een 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"
De decoratorrecords:
-
Parameters als
code.function.parameter.<name>spankenmerken. -
Retourneert waarden als
code.function.return.value. -
Ondersteunde typen:
str,int,float, ,boolen verzamelingen (list,dict,tuple,set). Objecttypen worden weggelaten.
Opmerking
De OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT omgevingsvariabele heeft geen invloed op aangepaste functietracering. De @trace_function decorator traceert altijd parameters en retourwaarden.
C# — handmatig gebruiken ActivitySource
De C#-SDK bevat geen traceringsdecorator. Gebruik de standaard-.NET ActivitySource om uw eigen functies te instrumenteren:
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;
}
Registreer uw aangepaste bron naast de SDK-bron in uw tracerprovider:
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("Azure.AI.Projects.*")
.AddSource("MyApp.CustomFunctions")
.SetResourceBuilder(
ResourceBuilder.CreateDefault().AddService("MyApp"))
.AddConsoleExporter()
.Build();
Instrumentatie programmatisch configureren (Python)
Als alternatief voor omgevingsvariabelen geeft u configuratieparameters rechtstreeks door aan 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 | Equivalent van omgevingsvariabele | Standaard |
|---|---|---|
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 |
* De standaardinstelling is True wanneer tracering is ingeschakeld.
Wanneer zowel een parameter als de bijbehorende omgevingsvariabele zijn ingesteld, heeft de parameterwaarde prioriteit.
Aangepaste kenmerken toevoegen aan spans
Maak een aangepaste SpanProcessor om metadata zoals sessie-id's in elke span te injecteren.
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
Registreer de processor bij de globale tracerprovider:
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())
Traceringsgedrag beheren met omgevingsvariabelen
De volgende tabel bevat alle omgevingsvariabelen die u kunt gebruiken om traceringsgedrag te configureren:
| Variabele | Taal | Standaard | Beschrijving |
|---|---|---|---|
AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING |
Python, C# | false |
Instrumentatie voor GenAI-tracering inschakelen. |
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT |
Python, C# | false |
Leg de berichtinhoud en parameters voor het aanroepen van hulpprogramma's vast. |
AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION |
Python | true* |
Voeg W3C Trace Context-headers toe aan aanvragen. |
AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE |
Python | false |
Neem de baggage header op in traceringscontextpropagatie. |
AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API |
Python | true |
Reacties en gespreks-API's voor geautomatiseerde instrumentatie. |
AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA |
Python | false |
Neem afbeeldings- en bestandsgegevens op in spanen (niet alleen bestands-id's). |
* De standaardinstelling is true wanneer tracering is ingeschakeld.
Zie Tracing in de Azure AI Projects SDK README voor de volledige lijst met omgevingsvariabelen en hun gedrag.
Beveiliging en privacy
Tracering aan de clientzijde kan gevoelige informatie vastleggen. Volg deze procedures om het risico te verminderen:
- Opname van inhoud: legt invoer van gebruikers, modelreacties en argumenten voor aanroepen van hulpprogramma's vast. Uitschakelen in productie tenzij vereist.
- Doorgifte van bagage: kan PII- en sessiegegevens beschikbaar maken. Standaard uitgeschakeld.
- Trace contextoverdracht: zend trace-ID's naar Azure services. Als nalevingsvereisten het delen van tracerings-id's verbieden, schakel ze dan uit.
- Geheimen: sla geen geheimen, aanmeldgegevens of tokens op in prompts, hulpprogramma-argumenten of attributen voor span-elementen.
- Toegangsbeheer: traceringsgegevens behandelen als productietelemetrie. Pas hetzelfde toegangsbeheer en bewaarbeleid toe dat u gebruikt voor logboeken en metrische gegevens.
Probleemoplossing
| Probleem | Resolutie |
|---|---|
| Tracering levert geen traces op | Controleer of AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING is ingesteld op truevoordat u AIProjectInstrumentor().instrument() aanroept (Python) of voordat u de tracerprovider (C#) maakt. |
| Berichtinhoud wordt niet weergegeven in span-elementen | Stel OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT in op true. |
| Traceringen worden niet weergegeven in Azure Monitor | Controleer of de Application Insights-verbindingsreeks juist is en of de resource toegankelijk is. Controleer of uw account de rol Log Analytics Lezer heeft. Als de tabellen zijn beveiligd, wijst u ook Privileged Monitoring Data Reader toe. |
| Spanten aan de clientzijde en serverzijde zijn niet gecorreleerd | (Python) Controleer of doorgifte van traceringscontext is ingeschakeld en of OpenAI-clients worden verkregen via get_openai_client()after instrumentatie. |
| Traces verschijnen met vertraging | Traceringen verschijnen doorgaans binnen 2-5 minuten in het Foundry-portaal en Azure Monitor. Wacht en vernieuw. |