Microsoft OpenTelemetry Distro

Microsoft OpenTelemetry Distro ist eine einheitliche Observability-Distribution, die einen einzigen Onboarding-Prozess für das Sammeln von Ablaufverfolgungen, Metriken und Protokollen aus Agent-gestützten und nicht-Agent-gestützten Anwendungen bietet. Es unterstützt die Observability für Microsoft Agent 365, Microsoft Foundry, Azure Monitor und jedes openTelemetry Protocol (OTLP)-kompatible Back-End. Die Distro unterstützt .NET, Node.jsund Python und ersetzt das fragmentierte Setup über mehrere Observability-Stapel durch einen Import- und einen Konfigurationsaufruf.

Note

Wenn Sie eine bestehende Integration pflegen, die das frühere Agent 365 Observability SDK verwendet, sehen Sie sich die veraltete SDK-Dokumentation und Migrationsleitfäden an.

Hauptvorteile

Die Microsoft OpenTelemetry Distro bietet folgende Vorteile:

  • Ein Paket, eine API: Ersetzen Sie mehrere Exporter- und Instrumentierungspakete durch eine einzelne Abhängigkeit.
  • Multi-Back-End-Unterstützung: Senden von Telemetrie an Azure Monitor, alle openTelemetry Protocol (OTLP)-kompatiblen Endpunkte wie Datadog, Grafana oder New Relic und Microsoft Agent 365 gleichzeitig.
  • Built-In-Instrumentierungen: Verwenden Sie die automatische Instrumentierung für HTTP, Datenbanken, Azure SDK, Azure Functions und mehr ohne zusätzliche Konfiguration.
  • Standardsbasiert: Bauen Sie auf OpenTelemetry, dem Branchenstandard-Observability-Framework, auf.
  • Minimaler Textbaustein: Fügen Sie einen Import- und einen Funktionsaufruf zu Ihrem Einstiegspunkt der Anwendung hinzu.

Installation und Konfiguration

In diesem Leitfaden wird gezeigt, wie Sie Ihrer Anwendung mit Microsoft OpenTelemetry Distro die Observierbarkeit hinzufügen. Die Distro sammelt automatisch Traces, Metriken und Logs mit integrierten Instrumentierungen und exportiert die Telemetrie in Azure Monitor, jeden OTLP-Endpunkt (OpenTelemetry Protocol) oder Microsoft Agent 365.

Installieren der Bibliothek

Um mit der Microsoft OpenTelemetry Distro zu beginnen, installieren Sie die entsprechende Bibliothek für Ihre Entwicklungsplattform mithilfe des Paket-Managers Ihrer Sprache.

Prerequisites: Python 3.10 oder höher.

pip install microsoft-opentelemetry

Configuration

Der Agent 365-Exporter verwendet keine Verbindungszeichenfolge. Er ermittelt seinen Endpunkt automatisch basierend auf dem Mandanten. Um den Export nach Agent 365 zu aktivieren, legen Sie das Exporterziel fest und stellen einen Tokenlöser bereit, der ein Zugriffstoken für eine bestimmte Agent-ID und Mandanten-ID zurückgibt.

Standardmäßig exportiert die Distro auf der delegierten Route, die die delegierte Agent365.Observability.OtelWrite Berechtigung und die Zustimmung des Administrators benötigt. Der a365 setup all Befehl konfiguriert diese Berechtigung nicht für Blueprint-Agenten, also nutze stattdessen S2S mit einem app-only resolver für diese Agenten. Eine Registered Agent-Instanz kann auf der S2S-Route ohne Observability-Berechtigung oder Administrator-Zustimmung exportieren.

Rufen Sie use_microsoft_opentelemetry() an, um die Beobachtbarkeit zu aktivieren.

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.hosting.token_cache_helpers import AgenticTokenCache

token_cache = AgenticTokenCache()

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=lambda agent_id, tenant_id: (
        (t := asyncio.run(token_cache.get_observability_token(agent_id, tenant_id)))
        and t.token or None
    ),
)

Informationen zur benutzerdefinierten Tokenauflösung (anstelle des Standardtokenlösers) finden Sie unter Manual token resolver.

Sie können das Verhalten des Exporters anpassen, indem Sie optionale a365_* kwargs (Schlüsselwortargumente) an use_microsoft_opentelemetry() übergeben.

Parameter Description Default
a365_use_s2s_endpoint Wenn True, verwendet den Dienst-zu-Dienst-Endpunktpfad. Verwendung mit einem reinen App-Token-Resolver. False
a365_max_queue_size Maximale Warteschlangengröße für den Batchprozessor. 2048
a365_scheduled_delay_ms Verzögerung in Millisekunden zwischen Exportbatches. 5000
a365_exporter_timeout_ms Timeout in Millisekunden für den Exportvorgang. 30000
a365_max_export_batch_size Maximale Batchgröße für Exportvorgänge. 512

Verteilungskontext

Um die Beobachtbarkeit in verteilten Agent-365-Vorgängen aufrechtzuerhalten, geben Sie den Kontext weiter. Wenn Sie den Kontext über Ihre Agents und Dienste weitergeben, stellen Sie sicher, dass Ablaufverfolgungen, Protokolle und Metriken über den gesamten Anforderungslebenszyklus ordnungsgemäß korreliert werden. Diese Korrelation ist für eine vollständige und effektive Microsoft Agent 365-Überwachungserfahrung erforderlich.

Gepäckattribute

Verwenden Sie BaggageBuilder, um Kontextinformationen festzulegen, die über alle Spannen in einer Anforderung fließen. Das SDK implementiert eine SpanProcessor , die alle nichtleeren Baggage-Einträge in neu gestartete Spans kopiert, ohne dass bestehende Attribute überschrieben werden.

from microsoft.opentelemetry.a365.core import BaggageBuilder

with (
    BaggageBuilder()
    .tenant_id("tenant-123")
    .agent_id("agent-456")
    .conversation_id("conv-789")
    .build()
):
    # Any spans started in this context will receive these as attributes
    pass

Verwenden Sie das BaggageBuilder-Hilfsprogramm im TurnContext-Paket, um das populate aus dem microsoft-opentelemetry automatisch auszufüllen. Dieses Tool extrahiert automatisch Anrufer-, Agenten-, Mandanten-, Kommunikationskanal- und Unterhaltungsdetails aus der Aktivität.

from microsoft.opentelemetry.a365.core import BaggageBuilder
from microsoft.opentelemetry.a365.hosting.scope_helpers.populate_baggage import populate

builder = BaggageBuilder()
populate(builder, turn_context)

with builder.build():
    # Baggage is auto-populated from the TurnContext activity
    pass

Gepäck-Middleware

Wenn Ihr Agent das Hosting-Integrationspaket verwendet, registrieren Sie Gepäck-Middleware, um Gepäck für jede eingehende Anfrage automatisch aufzufüllen. Dieser Schritt entfernt die Notwendigkeit, manuell in jedem Aktivitätshandler aufzurufen BaggageBuilder .

Registrieren Sie in Python Gepäck-Middleware über ObservabilityHostingManager.configure() statt direkt auf dem Adapter.

from microsoft.opentelemetry.a365.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

options = ObservabilityHostingOptions(enable_baggage=True)
ObservabilityHostingManager.configure(adapter.middleware_set, options)

Die Middleware überspringt die Konfiguration für asynchrone Antworten (ContinueConversation Async-Ereignisse), um das Überschreiben von Baggage zu vermeiden, das bereits durch die ursprüngliche Anforderung festgelegt wurde.

Überprüfen, ob Daten im Produkt korrekt fließen

Um die Agententelemetrie in Microsoft Purview oder Microsoft Defender einzusehen, stellen Sie sicher, dass Sie die folgenden Anforderungen erfüllen:

Automatische Instrumentierung

Die Microsoft OpenTelemetry Distro kombiniert Standard-OpenTelemetry-Pipelines mit Microsoft-kuratierter Instrumentierung. Die Distro kann je nach Sprache und Konfiguration Anwendungstelemetrie, Infrastrukturtelemetrie und Agent oder generative KI-Telemetrie sammeln.

Category Was es abdeckt
Signalleitungen Ablaufverfolgungen, Metriken und Protokolle.
Ressourcenerkennung Dienst-, Host-, Cloud- und Azure Laufzeitkontext, sofern unterstützt.
Infrastrukturinstrumentation HTTP-, ASP.NET Core-, Azure SDK-, Datenbankclients und Protokollierungsframeworks, sofern unterstützt.
Generative KI-Instrumentierung OpenAI, Azure OpenAI, Semantischer Kernel, LangChain, OpenAI Agents SDK und Agent Framework, wo unterstützt.
Manuelle Agentbereiche Agentaufruf, Toolausführung, Rückschluss und Ausgabetelemetrie, wo unterstützt.
Exporteure und Verarbeiter Azure Monitor, Microsoft Agent 365, OTLP, Konsolenausgabe, Spanprozessoren, Protokollprozessoren und Metrikleser.

Instrumentationsabdeckung

Language Allgemeine Anwendungsinstrumentation Gängige Agent- und generative KI-Instrumentierung
Python OpenTelemetry-Ressourcen, Prozessoren, Leser, Protokollierung, Metriken und Ablaufverfolgungen. Semantischer Kernel, OpenAI Agents SDK, Agent Framework, LangChain, Microsoft Agent 365 Bag und Microsoft Agent 365-Bereiche.
Node.js HTTP, Azure SDK, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis, Bunyan und Winston. OpenAI Agents SDK, LangChain, Microsoft Agent 365 Zusatzdaten und Microsoft Agent 365-Bereiche.
.NET ASP.NET Core, HttpClient, SQL Client, Azure SDK, Ressourcenerkennung, Metriken und Protokolle. Semantischer Kernel, OpenAI und Azure OpenAI, Agent Framework, Microsoft Agent 365-Kontexte und Microsoft Agent 365-Bereiche.

Die automatische Instrumentierung überwacht die Telemetriesignale, die von unterstützten Bibliotheken und Frameworks ausgegeben werden. Manuelle Instrumentierung wird verwendet, wenn eine Anwendung agentspezifische Vorgänge beschreiben muss, z. B. Aufrufe, Toolausführung, Rückschluss oder asynchrone Ausgabe.

Fügen Sie benutzerdefinierte OpenTelemetry-Quellen, -Meter, -Prozessoren oder -Leser hinzu, wenn Ihre Anwendung Telemetrie ausgibt, die nicht von den integrierten Instrumentierungen abgedeckt wird.

Important

Die automatische Instrumentierung füllt nur openTelemetry-Standardattribute auf. Es enthält nicht alle Attribute, die Agent 365 erfordert. Sie müssen Microsoft spezifische Attribute über BaggageBuilder hinzufügen. Informationen dazu, welche Attribute erforderlich sind, finden Sie unter Store-Überprüfungsattribute.

Integrierte Instrumentationsbibliotheken

Die automatische Instrumentierung lauscht auf Telemetrie, die von unterstützten Frameworks ausgegeben wird, und leitet sie über die OpenTelemetry-Pipeline von Distro weiter. Legen Sie für Agentszenarien Gepäck fest, z. B. Mandanten-ID und Agent-ID, bevor das instrumentierte Framework Spannweiten erstellt.

Rahmen Python Node.js .NET
Semantischer Kern Unterstützt Nicht unterstützt Unterstützt
OpenAI und OpenAI-Agents SDK Unterstützt Unterstützt Unterstützt
Agenten-Framework Unterstützt Nicht unterstützt Unterstützt
LangChain Unterstützt Unterstützt Nicht aufgelistet

Semantischer Kern

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "semantic_kernel": {"enabled": True},
    },
)

OpenAI

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "openai_agents": {"enabled": True},
    },
)

Agenten-Framework

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "agent_framework": {"enabled": True},
    },
)

LangChain

Note

Die automatische Instrumentierung für das LangChain-Framework unterstützt auch LangGraph und Deep Agents. Die gleiche Instrumentierung erfasst automatisch Telemetrie für Agents, die mit einem dieser Frameworks erstellt wurden.

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "langchain": {"enabled": True},
    },
)

Manuelle Instrumentierung

Verwenden Sie manuelle Instrumentierung, wenn die automatische Instrumentierung den Agentenvorgang nicht mit ausreichend Details beschreibt. Manuelle Bereiche ermöglichen es einer Anwendung, allgemeine Agent-Aktivitäten in einer konsistenten Weise in allen Sprachen zu beschreiben.

Geltungsbereich Verwendung für
InvokeAgentScope Der Anfang und abschluss eines Agent-Aufrufs.
ExecuteToolScope Ein Toolaufruf, der von einem Agenten ausgeführt wird.
InferenceScope Eine KI-Modell-Ableitungsoperation.
OutputScope Die Ausgabe muss aufgezeichnet werden, nachdem der Ursprungsbereich abgeschlossen ist.

Verwenden Sie dieselben Anforderungs- und Agentenidentitätswerte in Bereichen einer Anforderung wieder, sodass entsprechende Telemetrie korreliert werden kann.

Agentenaufruf

from microsoft.opentelemetry.a365.core import (
    AgentDetails,
    Channel,
    InvokeAgentScope,
    InvokeAgentScopeDetails,
    Request,
    ServiceEndpoint,
)

agent_details = AgentDetails(
    agent_id="agent-456",
    agent_name="Email Assistant",
    agent_description="An AI agent powered by Azure OpenAI",
    agentic_user_id="auid-123",
    agentic_user_email="agent@contoso.com",
    agent_blueprint_id="blueprint-789",
    tenant_id="tenant-123",
)

request = Request(
    content="Please help me organize my emails",
    session_id="session-42",
    conversation_id="conv-xyz",
    channel=Channel(name="msteams"),
)

scope_details = InvokeAgentScopeDetails(
    endpoint=ServiceEndpoint(hostname="myagent.contoso.com", port=443),
)

with InvokeAgentScope.start(
    request=request,
    scope_details=scope_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Please help me organize my emails"])

    # Run the agent invocation.

    invoke_scope.record_output_messages(["I found 15 urgent emails."])

Werkzeugausführung

from microsoft.opentelemetry.a365.core import (
    ExecuteToolScope,
    ServiceEndpoint,
    ToolCallDetails,
    ToolType,
)

tool_details = ToolCallDetails(
    tool_name="email-search",
    arguments={"query": "from:manager@contoso.com"},
    tool_call_id="tool-call-456",
    description="Search emails by criteria",
    tool_type=ToolType.FUNCTION.value,
    endpoint=ServiceEndpoint(
        hostname="tools.contoso.com",
        port=8080,
        protocol="https",
    ),
)

with ExecuteToolScope.start(
    request=request,
    details=tool_details,
    agent_details=agent_details,
) as scope:
    result = search_emails(tool_details.arguments)
    scope.record_response(result)

Schlussfolgerung

from microsoft.opentelemetry.a365.core import (
    InferenceCallDetails,
    InferenceOperationType,
    InferenceScope,
)

inference_details = InferenceCallDetails(
    operationName=InferenceOperationType.CHAT,
    model="gpt-4o-mini",
    providerName="azure-openai",
)

with InferenceScope.start(
    request=request,
    details=inference_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Summarize the following emails for me."])
    response = call_llm()
    scope.record_output_messages([response.text])
    scope.record_input_tokens(response.usage.input_tokens)
    scope.record_output_tokens(response.usage.output_tokens)
    scope.record_finish_reasons(["stop"])

Output

from microsoft.opentelemetry.a365.core import OutputScope, Response, SpanDetails

# Capture this before exiting the originating InvokeAgentScope context.
parent_context = invoke_scope.get_span_context()
response = Response(
    messages=["Here is your organized inbox."],
)

with OutputScope.start(
    request=request,
    response=response,
    agent_details=agent_details,
    user_details=None,
    span_details=SpanDetails(parent_context=parent_context),
) as scope:
    pass

Die Produktdokumentation sollte alle produktspezifischen Validierungsanforderungen für diese Bereiche definieren.

Lokale Überprüfung

Die lokale Überprüfung bestätigt, dass die Anwendung Telemetrie erzeugt, bevor ein produktspezifisches Ziel überprüft wird. Verwenden Sie die Konsolenausgabe oder einen lokalen OTLP-Endpunkt, um zu überprüfen, ob Ablaufverfolgungen, Metriken und Protokolle erstellt werden.

Überprüfen mit einem lokalen OTLP-Endpunkt

Konfigurieren Sie die Distro, um Telemetrie an einen lokalen Sammler oder einen anderen OTLP-kompatiblen Endpunkt zu senden.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Validieren mit lokaler Ausgabe

Verwenden Sie die lokale Ausgabe, wenn Sie die Instrumentierung bestätigen möchten, bevor Sie Telemetrie an ein Remoteziel senden.

export ENABLE_A365_OBSERVABILITY_EXPORTER=false

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "local-validation-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
)

# Run instrumented application code.

Überprüfen Sie die lokale Ausgabe für Bereiche von erwarteten Quellen, z. B. HTTP-Anforderungen, OpenAI- oder Azure OpenAI-Aufrufe, Agentaufrufbereiche, Toolausführungsbereiche oder Ableitungsbereiche. Die zielspezifische Überprüfung gehört zur Produktdokumentation für dieses Ziel.

Manuelles Einrichten der Authentifizierung

Wenn Sie den Agent 365-Exporter verwenden, müssen Sie einen Mechanismus zum Bereitstellen eines Authentifizierungstokens bereitstellen. Der Tokenlöser funktioniert pro Exportbatch mithilfe der Agent-ID und der Mandanten-ID aus dem aktiven Gepäckkontext. Die Distro unterstützt zwei Ansätze.

Für Agent 365-fähige Blueprint-Agenten, die mit a365 setup alleingerichtet sind, verwenden Sie S2S mit einem App-Only-Resolver. Der integrierte agentische Token-Cache und die OBO-Beispiele auf dieser Seite verwenden die delegierte Route, die die delegierte Agent365.Observability.OtelWrite Berechtigung und die Zustimmung des Administrators benötigt. Der a365 setup all Befehl konfiguriert diese Berechtigung nicht für Blueprint-Agenten.

Tip

Wenn Sie Agents mit dem Microsoft 365 Agents SDK erstellen, finden Sie unter Einrichtung der Observability-Authentifizierung für das Agent SDK eine Schritt-für-Schritt-Anleitung zum Konfigurieren des OBO- und S2S-Tokenabrufs für agentische und nicht-agentische Agents.

Manueller Tokenlöser

Verwenden Sie einen manuellen Resolver, wenn Sie Token außerhalb der Agent-Framework-Pipeline erwerben, beim Erstellen von Nicht-Agent-Framework-Apps oder bei der Nutzung der Service-to-Service-(S2S)-Authentifizierung. Der Token, den dein Resolver zurückgibt, muss mit der Route übereinstimmen. Für die delegierte Route gib ein delegiertes Token mit dem Agent365.Observability.OtelWrite Scope zurück. Für die S2S-Route gib das letzte App-only-Token zurück, das du mit dem api://9b975845-388f-4429-889e-eab1ef63949c/.default Scope angefordert hast. Ein registrierter Blueprint-Agent auf S2S benötigt weder die Agent365.Observability.OtelWrite Rolle noch die Zustimmung des Administrators.

Note

Für die S2S-Authentifizierung (Service-to-Service) müssen Sie diesen manuellen Tokenlöseransatz verwenden. Der agentic Token-Cache unterstützt nur On-Behalf-Of-(OBO)-Authentifizierungsabläufe.

Die folgenden Beispiele zeigen das Muster für den OBO-Token-Resolver (im Auftrag von) – der Agent bezieht über den agentischen Authentifizierungs-Handler ein Benutzertoken und tauscht es gegen ein auf den Observability-Bereich beschränktes Token aus. Für diese Beispiele ist die delegierte Agent365.Observability.OtelWrite Berechtigung und die Zustimmung des Administrators erforderlich. Beispiele für S2S (Service-to-Service) und einen Vergleich der OBO- und S2S-Authentifizierung finden Sie unter Observability Authentication Setup for Agent SDK.

Der Resolver muss synchron sein. Rufen Sie das Token in Ihrem asynchronen Aktivitätshandler (oder über MSAL) ab und speichern Sie es für den Resolver zwischen.

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope

_cached_token: str | None = None

def my_token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _cached_token

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=my_token_resolver)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    global _cached_token
    _cached_token = await AGENT_APP.auth.exchange_token(
        context,
        scopes=get_observability_authentication_scope(),
        auth_handler_id="AGENTIC",
    )

Agentic Token-Cache mit Agent-Framework-Apps

Bei Agent Framework-Apps, die die On-Behalf-Of-(OBO)-Authentifizierung verwenden, registriert die Distribution IExporterTokenCache<AgenticTokenStruct> automatisch über DI, wenn Sie keine benutzerdefinierte TokenResolver festlegen. Ihr Agent ruft RegisterObservability() zur Laufzeit auf, um Zugangsdaten bereitzustellen, und der Cache übernimmt die delegierte Tokenbeschaffung und Aktualisierung.

Note

Dieser Ansatz unterstützt nur On-Behalf-Of-(OBO)-Authentifizierungsflüsse auf der delegierten Route, was die delegierte Agent365.Observability.OtelWrite Berechtigung und die Administratorzustimmung erfordert. Für Service-to-Service-(S2S)-Authentifizierung, einschließlich Blueprint-Agenten, die mit a365 setup all eingerichtet sind, verwenden Sie stattdessen den manuellen Token-Resolver mit einem reinen App-Token. Für Einrichtungsschritte siehe Agent 365-enabled mit S2S.

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.hosting.token_cache_helpers import AgenticTokenCache, AgenticTokenStruct
from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope

token_cache = AgenticTokenCache()

_cached_tokens: dict[tuple[str, str], str | None] = {}

# Keep the sync resolver side-effect free; refresh the cache in the async request handler.
def sync_token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _cached_tokens.get((agent_id, tenant_id))

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=sync_token_resolver)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    agent_id = context.activity.recipient.id
    tenant_id = context.activity.recipient.tenant_id
    token_cache.register_observability(
        agent_id=agent_id,
        tenant_id=tenant_id,
        token_generator=AgenticTokenStruct(
            authorization=AGENT_APP.auth,
            turn_context=context,
        ),
        observability_scopes=get_observability_authentication_scope(),
    )
    _cached_tokens[(agent_id, tenant_id)] = await token_cache.get_observability_token(
        agent_id, tenant_id,
    )

Speicher-Validierungsattribute

Für eine erfolgreiche Speicherüberprüfung muss Ihr Agent InvokeAgentScope, InferenceScope und ExecuteToolScope implementieren. Jeder Geltungsbereich entspricht einer Span-Operation im kanonischen Schema:

SDK-Bereich Spannenvorgang Universeller Referenzcode
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

Eine vollständige Liste der erforderlichen und optionalen Attribute pro Geltungsbereich – einschließlich der Semantik der einzelnen Attribute, der Anleitung zur Wertauswahl und der Angabe, welche Attribute über die erweiterte Suche in Microsoft Defender abfragbar sind – finden Sie unter Agent 365 observability attribute reference. Die Spalte "Gilt für " gibt an, zu welchem Bereich jedes Attribut gehört, und die Erforderliche Spalte unterscheidet obligatorisch (M) von optionalen (O) Attributen.

Testen Sie Ihren Agenten mit Observierbarkeit

Überprüfen Sie nach der Implementierung der Observability, ob Telemetrie erfasst wird:

  1. Gehe zu https://admin.cloud.microsoft/#/agents/all.
  2. Wählen Sie Ihren Agent und dann "Aktivität" aus.
  3. Überprüfen Sie, ob Sitzungen und Toolaufrufe angezeigt werden.

Beispielanwendungen und erweiterte Konfiguration

Arbeitsbeispiele und erweiterte Konfigurationsoptionen finden Sie in den GitHub Repositorys für jede Sprache:

Referenz zum Programmieren

Um die Microsoft OpenTelemetry Distro-Typen zu überprüfen, siehe die folgenden Programmierreferenzartikel:

Troubleshooting

In diesem Abschnitt werden häufige Probleme bei der Implementierung und Verwendung der Microsoft OpenTelemetry Distro mit Agent 365 beschrieben.

Problem Description
Observability-Daten werden nicht angezeigt Keine Telemetrie ist sichtbar, weil der Agent 365-Export nicht aktiviert ist, die Einrichtung nicht abgeschlossen ist oder die Token-Auflösung fehlschlägt.
Fehlende Mandanten-ID oder Agent-ID – übersprungene Spanne Spans werden vor dem Export herausgefiltert, wenn erforderliche Mandanten- oder Agent-Identitätsattribute fehlen.
Fehler bei der Tokenauflösung – Export übersprungen oder nicht autorisiert Der Export wird übersprungen oder abgelehnt, wenn der Token-Resolver kein Token zurückgibt oder beim Token-Abruf Fehler auftreten.
HTTP 401 nicht autorisiert Anforderungen erreichen den Dienst, aber die Authentifizierung schlägt fehl, da das Token ungültig, abgelaufen oder für die falsche Zielgruppe ist.
HTTP 403 Verboten Die Autorisierung schlägt fehl wegen fehlender Mandantenlizenzierung, einer nicht registrierten S2S-Identität oder fehlenden Schreibberechtigungen für Observability, wo sie erforderlich sind.
HTTP 403 Verboten – Agent-ID stimmt nicht überein Der Dienst lehnt den Export ab, wenn die Agent-ID in der Anforderung nicht mit der tokenautorisierten Agentidentität übereinstimmt.
HTTP 429- oder 5xx-Fehler – Vorübergehende Fehler Temporäre Drosselung oder Backend-Instabilität unterbricht den Export und erfordert möglicherweise erneute Versuche oder Batch-Tuning.
Exporttimeout Exportvorgänge überschreiten die Zeitlimits aufgrund von Netzwerkverzögerungen oder der Antwortlatenz des Endpunkts.
Der Export ist erfolgreich, die Telemetrie wird jedoch nicht in Defender oder purview angezeigt. Die Datenaufnahme ist erfolgreich, die Sichtbarkeit wird jedoch durch nachgelagerte Voraussetzungen und Schemaanforderungen verzögert oder blockiert.

Tip

Der Agent 365 Troubleshooting Guide enthält übergeordnete Empfehlungen zur Fehlerbehebung, Best Practices und Links zu Inhalten zur Fehlerbehebung für jeden Teil des Entwicklungszyklus von Agent 365.

Observabilitätsdaten erscheinen nicht

Symptome:

  • Agent läuft
  • Keine Telemetrie im Verwaltungszentrum
  • Kann keine Agentenaktivität sehen

Grundursache:

  • Agent 365-Export ist nicht aktiviert
  • Konfigurationsfehler
  • Probleme des Token-Resolvers

Lösungen: Probieren Sie die folgenden Schritte aus, um das Problem zu lösen:

  • Überprüfen, ob der Agent 365-Export aktiviert ist

    Sie müssen den Agent 365-Exporter explizit aktivieren. Wenn es nicht festgelegt wird, kann die Distribution auf eine Konsolenausgabe zurückgreifen oder gar nichts exportieren. Aktivieren Sie sie im Code:

    from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_enable_observability_exporter=True,
    a365_token_resolver=my_token_resolver,
)

    Oder legen Sie die Umgebungsvariable fest:

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    Note

    ENABLE_A365_OBSERVABILITY_EXPORTER ist ein sekundärer Schalter, der nur wirksam wird, wenn enable_a365=True im Code gesetzt ist. Sie können es auch über den a365_enable_observability_exporter Kwarg steuern.

  • Überprüfen Sie die Token-Resolver-Konfiguration

    Der Exporter erfordert einen gültigen Tokenlöser, der ein Bearertoken für jede Exportanforderung zurückgibt. Wenn der Tokenlöser fehlt oder zurückgibt null, wird der Export im Hintergrund übersprungen.

  • Aktivieren des Konsolenexports und der lokalen Überprüfung auf Telemetrie

    Fügen Sie einen Konsolenexporteur hinzu, um zu überprüfen, ob Telemetrie generiert wird, bevor er den Agent 365-Endpunkt erreicht:

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Ausführliche Protokollierung aktivieren

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Überprüfen von Protokollen auf Exportfehler

    Verwenden Sie den az webapp log tail Befehl , um Protokolle nach Observability-bezogenen Fehlern zu durchsuchen:

    az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"

Fehlende Mandanten-ID oder Agent-ID – übersprungen

Symptome: Das System verwirft die Spans unbemerkt und exportiert sie nie. Einige Plattformen protokollieren die Anzahl der übersprungenen Bereiche oder eine Nachricht wie No spans with tenant/agent identity found. Andere lassen sie fallen, ohne Protokoll zu führen.

Auflösung:

  • Vor dem Export werden die Distributionspartitionen nach Mandanten- und Agentenidentität aufgeteilt. Spans, die weder eine Tenant-ID noch eine Agent-ID besitzen, werden verworfen und nie an den Dienst gesendet.
  • Stellen Sie sicher, dass BaggageBuilder mit der Mandanten-ID und der Agenten-ID eingerichtet ist, bevor Sie Spannweiten erstellen. Diese Werte werden über den OpenTelemetry-Kontext verteilt und an alle Spans angefügt, die innerhalb des Baggage-Bereichs erstellt werden. Informationen zur plattformspezifischen API finden Sie unter Gepäckattribute.
  • Wenn Sie die Baggage-Middleware verwenden oder das kontextbezogene Hilfsprogramm aus dem Hosting-Integrationspaket verwenden, bestätigen Sie, dass die TurnContext Aktivität über einen gültigen Empfänger mit Agentidentität verfügt.

Fehler bei der Tokenauflösung – Export übersprungen oder nicht autorisiert

Symptome: Der Tokenlöser gibt null zurück oder wirft einen Fehler. Je nach Plattform wird der Export entweder vollständig übersprungen oder schlägt mit HTTP 401 fehl.

Auflösung:

  • Der Tokenlöser ist erforderlich. Wenn er fehlt, löst der Exporter beim Start einen Fehler aus. Stellen Sie sicher, dass ein Tokenlöser bereitgestellt wird, und gibt ein gültiges Bearertoken zurück.
  • Stellen Sie sicher, dass die richtige Mandanten-ID und Agent-ID an BaggageBuilder übergeben werden, da diese Werte an den Tokenlöser übertragen werden.
  • Für S2S geben Sie das letzte app-only Observability-Token für 9b975845-388f-4429-889e-eab1ef63949c oder api://9b975845-388f-4429-889e-eab1ef63949czurück. Gib weder die Zwischen-Blueprint-Assertion, ein Blueprint-Token noch ein Benutzer- oder OBO-Token zurück.
  • Für die delegierte Route gib ein delegiertes Token mit dem Agent365.Observability.OtelWrite Scope zurück.
  • Für Azure-gehostete Agenten, die direkt mit einer verwalteten Identität exportieren, sollte überprüft werden, dass die verwaltete Identität die Agent365.Observability.OtelWrite App-Rolle hat. Registered Blueprint Agent-Instanzen auf S2S benötigen das nicht.
  • Für .NET Apps, die das Agent Framework-Hostingpaket verwenden, wird der Tokenaustausch automatisch über DI verarbeitet. Wenn Token fehlen, bestätigen Sie, dass Microsoft.Agents.A365.Observability.Hosting installiert und registriert ist.

HTTP 401 nicht autorisiert

Symptome: Der Export schlägt mit HTTP 401 fehl. Der Exporter wiederholt diesen Fehler nicht.

Auflösung:

  • Überprüfen Sie, ob die Token-Zielgruppe 9b975845-388f-4429-889e-eab1ef63949c oder api://9b975845-388f-4429-889e-eab1ef63949cist, und dass der Token-Typ mit der Route übereinstimmt: ein delegiertes Token für die delegierte Route oder ein reines App-Token für die S2S-Route.
  • Für S2S solltest du überprüfen, ob der Resolver kein delegiertes Benutzertoken, eine Zwischen-Blueprint-Assertion, ein Blueprint-Token, ein Token für eine falsche Zielgruppe oder ein abgelaufenes Token zurückgibt.
  • Für die delegierte Route prüfen Sie, ob der Claim des Tokens scpAgent365.Observability.OtelWrite enthält und dass der Token nicht abgelaufen ist.

HTTP 403 – Unzulässig

Symptome: Der Export schlägt mit HTTP 403 fehl. Der Exporter wiederholt diesen Fehler nicht.

Ursache: Ein HTTP 403-Fehler kann unterschiedliche Ursachen haben. Überprüfen Sie die folgenden Auflösungen in der angegebenen Reihenfolge.

Auflösung:

  • Missing license – Vergewissern Sie sich, dass Ihrem Mandanten eine der folgenden Lizenzen in Microsoft 365 Admin Center:

    • Test - Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Agent 365 Frontier

  • Unregistrierte Identität auf S2S — Eine registrierte Blueprint-Agent-Instanz kann mit einem App-only-Token, das keine Agent365.Observability.OtelWrite Rolle hat, auf der S2S-Route exportieren. Wenn die Identität nicht bei Agent 365 registriert ist, gibt der Dienst HTTP 403 insufficient_scopezurück. Für Blueprint-Agenten registriert a365 setup all die Agenteninstanz. Um eine fehlgeschlagene Registrierung erneut zu versuchen, führe a365 setup all --agent-registration-only aus. Allein das Erstellen einer Microsoft Entra-Identität registriert die Agenteninstanz nicht.

  • Fehlende Berechtigung Agent365.Observability.OtelWrite , wo sie erforderlich ist – Erteile die Berechtigung für den delegierten Fluss oder für nicht registrierte Identitäten, einschließlich Standard-App-Registrierungen. Registrierte Blueprint-Agenten auf S2S benötigen diese Erlaubnis nicht.

Berechtigung erteilen

Gewähren Sie Agent365.Observability.OtelWrite nur, wenn Sie die delegierte Route oder eine nicht registrierte Identität verwenden. Registrierte Blueprint-Agenten, die S2S verwenden, benötigen diese Erlaubnis oder die Zustimmung des Admins nicht. Gewähren Sie nur den Berechtigungstyp, den Ihre Route verwendet:

  • Delegierter Pfad: Füge die delegierte Berechtigung hinzu.
  • S2S-Route mit einer nicht registrierten Identität, wie der Standard-App-Registrierung, die ein Custom Engine-Agent verwendet: Fügen Sie die Anwendungsberechtigung hinzu (App-Rolle).

Verwenden Sie eine dieser Optionen:

  • Agent 365 CLI (Blueprint-Agenten auf der delegierten Route)

    Dieser Befehl fügt die delegierte Berechtigung zu deinem Blueprint und seinen vererbbaren Berechtigungen hinzu und gewährt dann die Administratorzustimmung. Die Anwendungsberechtigung wird nicht hinzugefügt. Dafür ist ein Konto eines globalen Administrators erforderlich. Führe den Befehl aus dem Agentenprojektverzeichnis aus, das a365.config.json enthält, oder füge --agent-name "<agent-name>" hinzu.

    a365 setup permissions custom --resource-app-id 9b975845-388f-4429-889e-eab1ef63949c --scopes Agent365.Observability.OtelWrite

  • Microsoft Entra Admin Center (egal welcher Weg)

    Keine Konfigurationsdateien erforderlich; erfordert globalen Administratorzugriff auf die App-Registrierung. Für einen Blueprint auf der delegierten Route verwenden Sie diese Option nur, wenn der Blueprint bereits die Observability-API in seinen vererbbaren Berechtigungen enthält, wie z. B. einen Blueprint, den eine frühere CLI-Version eingerichtet hat. Ansonsten nutze die Agent 365 CLI.

    1. Gehe ins Microsoft Entra Admin Center, wähle App-Registrierungen aus und wähle dann deinen Blueprint oder die Standard-App-Registrierung aus.
    2. Wechseln Sie zu API-Berechtigungen>Eine Berechtigung hinzufügen>APIs, die meine Organisation verwendet> suchen nach 9b975845-388f-4429-889e-eab1ef63949c.
    3. Wählen Sie delegierte Berechtigungen für die delegierte Route oder Anwendungsberechtigungen für eine nicht registrierte Identität auf der S2S-Route.
    4. Prüfe Agent365.Observability.OtelWrite, und wähle dann Berechtigungen hinzufügen.
    5. Wählen Sie Administratorzustimmung erteilen aus und bestätigen Sie.

    Die von dir hinzugefügte Berechtigung zeigt den GrantedStatus an.

HTTP 403 Verboten – Nichtübereinstimmung der Agent-ID

Symptome: Der Export schlägt mit HTTP 403 und einer Servernachricht fehl, die mit 403 Forbidden Fehlern beim Aufrufen von Agent 365-Ablaufverfolgungsendpunkten vergleichbar istagent-ID-mismatch.

Ursache: Dieser Fehler tritt auf, wenn Sie die Blueprint-Client-ID anstelle der Agentinstanz-Client-ID verwenden, wenn Sie die Agentdetails festlegen. Die Agent-ID in der Export-URL stimmt nicht mit der durch das Token autorisierten Identität überein, sodass der Traces-Endpunkt die Anfrage ablehnt.

Auflösung:

  • Überprüfen Sie, ob die Mandanten-ID der Liste "Agent 365 zulässiger Mandanten" hinzugefügt wird.
  • Legen Sie die Agentdetails mit der Client-ID der Agentinstanz fest (nicht die Blueprint-Client-ID).
  • Überprüfen Sie die generierte Export-URL – es wird protokolliert, wenn Sie Ihren Logger aktivieren. Bestätigen Sie, dass die Agent-ID in der URL mit der Client-ID der Agentinstanz übereinstimmt.
  • Informationen zum Aktivieren der Diagnoseprotokollierung pro SDK finden Sie unter "Lokale Überprüfung".

HTTP 429- oder 5xx-Fehler – Vorübergehende Fehler

Symptome: Der Export schlägt mit einem vorübergehenden HTTP-Statuscode wie 429 oder 5xx fehl.

Auflösung:

  • Diese Fehler sind in der Regel vorübergehend und allein behoben. Die Python- und JavaScript-Distributionen initiieren automatisch einen erneuten Versuch bei HTTP 408-, 429- und 5xx-Statuscodes. Die .NET-Distribution versucht nicht automatisch erneut.
  • Wenn Fehler weiterhin bestehen, überprüfen Sie das Dienststatusdashboard.
  • Erwägen Sie, die Exporthäufigkeit zu verringern, indem Sie die geplante Verzögerung zwischen Batches oder der maximalen Exportbatchgröße erhöhen. Verwenden Sie für Python und JavaScript die relevanten Parameter exporterOptions oder a365_*, die in den Repositorys GitHub dokumentiert sind. Verwenden Sie für .NET o.Agent365.Exporter.ScheduledDelayMilliseconds und o.Agent365.Exporter.MaxExportBatchSize.

Export-Zeitüberschreitung

Symptome: Exportversuche laufen ab.

Auflösung:

  • Überprüfen Sie die Netzwerkkonnektivität mit dem Observability-Endpunkt.

  • Das standardmäßige HTTP-Anforderungstimeout beträgt 30 Sekunden auf allen Plattformen. Wenn Timeouts häufig auftreten, erhöhen Sie den Timeoutwert in den Exporteroptionen:

    use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=my_token_resolver,
    # No direct timeout kwarg — set via environment variable or exporterOptions if supported
)

    Sehen Sie sich das Python-Repository für die vollständige Liste der a365_* Optionen an.

Der Export ist erfolgreich, die Telemetrie wird jedoch nicht in Defender oder purview angezeigt.

Symptoms: Protokolle zeigen einen erfolgreichen Export (HTTP 200) an, die Telemetrie ist jedoch in Microsoft Defender oder Microsoft Purview nicht sichtbar.

Auflösung:

  • Stellen Sie sicher, dass Sie die Voraussetzungen für die Anzeige exportierter Protokolle erfüllen:
  • Telemetriedaten können nach einem erfolgreichen Export mehrere Minuten benötigen, um angezeigt zu werden. Warten Sie, bevor Sie weitere Untersuchungen ausführen.
  • Stellen Sie sicher, dass Spannen gültige microsoft.tenant.id und gen_ai.agent.id Attribute enthalten. Fehlende Identitätsattribute führen dazu, dass serverseitig Spannen verworfen werden, auch wenn der HTTP-Export 200 zurückgibt.

Verwandte Inhalte

  • Zuletzt aktualisiert um