Tracering aan de clientzijde toevoegen aan Foundry-agents (preview)

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 login uit 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_ENDPOINT De eindpunt-URL van uw Foundry-project. Zoek het op de projectoverzichtspagina in de Foundry-portal.
    FOUNDRY_MODEL_NAME De 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-projects pakket 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.