Microsoft OpenTelemetry Distro

Microsoft OpenTelemetry Distro ist eine einheitliche Einblicksdistribution die eine einzige Onboarding-Erfahrung für das Sammeln von Ablaufverfolgungen, Metriken und Protokollen aus agentbasierten und nicht-agentbasierten Anwendungen bietet. Sie unterstützt Einblicke für Microsoft Agent 365, Microsoft Foundry, Azure Monitor und jedes mit OpenTelemetry Protocol (OTLP)kompatible Back-End. Die Distro unterstützt .NET, Node.js und Python und ersetzt fragmentierte Setups über mehrere Einblick-Stacks hinweg durch einen einzigen Import und einen einzigen Konfigurationsaufruf.

Wesentliche Vorteile

Die Microsoft OpenTelemetry Distro bietet folgende Vorteile:

  • Ein Paket, eine API: Ersetzen Sie mehrere Exporter- und Instrumentierungspakete durch eine einzige Abhängigkeit.
  • Multi-Backend-Support: Telemetrie gleichzeitig an Azure Monitor, jeden OTLP-kompatiblen Endpunkt wie Datadog, Grafana oder New Relic und an Microsoft Agent 365 senden.
  • Eingebaute Instrumentierungen: Verwenden Sie automatische Instrumentierung für HTTP, Datenbanken, Azure SDK, Azure Functions und mehr ohne zusätzliche Konfigurationen.
  • Standardbasiert: Setzen Sie auf OpenTelemetry, das branchenübliche Einblick-Framework.
  • Minimaler Boilerplate: Fügen Sie einen Import und einen Funktionsaufruf am Einstiegspunkt Ihrer Anwendung hinzu.

Installation und Konfiguration

In dieser Anleitung erfahren Sie, wie Sie Ihrer Anwendung Einblick mithilfe von Microsoft OpenTelemetry Distro hinzufügen können. Die Distribution erfasst mithilfe integrierter Instrumentierungen automatisch Nachverfolgungen, Metriken und Protokolle und exportiert die Telemetriedaten an Azure Monitor, einen beliebigen OpenTelemetry Protocol (OTLP)-Endpunkt 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 Paketmanagers Ihrer Programmiersprache.

Voraussetzungen: Python 3.10 oder höher.

pip install microsoft-opentelemetry

Konfiguration

Der Agent 365 Exporter benötigt keine Verbindungszeichenfolge. Es ermittelt seinen Endpunkt automatisch abhängig vom Mandant. Um den Export zu Agent 365 zu aktivieren, konfigurieren Sie das Exportziel und geben Sie einen Token-Resolver an, der ein Zugriffstoken für eine bestimmte Agenten-ID und Tenant-ID zurückgibt.

Rufen Sie use_microsoft_opentelemetry() auf, um die Einblicke 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
    ),
)

Für benutzerdefinierte Token-Auflösung (anstelle des Standard-Token-Resolvers) siehe Manueller Token-Resolver.

Sie können das Exporterverhalten anpassen, indem Sie eine a365_*-Kwargs an use_microsoft_opentelemetry() weitergeben.

Parameter BESCHREIBUNG Standard
a365_use_s2s_endpoint Verwendet bei True den Dienst-zu-Dienst-Endpunktpfad. False
a365_max_queue_size Maximale Größe der Warteschlange für den Batch-Prozessor. 2048
a365_scheduled_delay_ms Verzögerung in Millisekunden zwischen den Exportchargen. 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 über verteilte Agent 365-Operationen hinweg sicherzustellen, propagieren Sie den Kontext. Wenn Sie Kontext durch Ihre Agents und Dienste propagieren, stellen Sie sicher, dass Traces, Logs und Metriken über den gesamten Anforderungszyklus hinweg richtig korreliert werden. Diese Korrelation ist Voraussetzung für ein vollständiges und effektives Microsoft Agent 365 Monitoring-Erlebnis.

Gepäckattribute

Verwenden Sie BaggageBuilder, um Kontextinformationen festzulegen, die über alle Spannen in einer Anforderung fließen. Das SDK implementiert einen SpanProcessor, der alle nicht leeren Baggage-Einträge in neu gestartete Abschnitte kopiert, ohne vorhandene Attribute zu überschreiben.

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

Um BaggageBuilder automatisch aus TurnContext zu befüllen, verwenden Sie den populate Helfer im microsoft-opentelemetry Paket. Dieser Helfer extrahiert automatisch Anrufer-, Agenten-, Mandanten-, Kanal- und Gesprächsdetails 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

Baggage-Middleware

Wenn Ihr Agent das Hosting-Integrationspaket verwendet, registrieren Sie die Baggage-Middleware, um Baggage für jede eingehende Anfrage automatisch zu setzen. Dieser Schritt macht es überflüssig, BaggageBuilder in jedem Aktivitätshandler manuell aufzurufen.

Registrieren Sie in Python die Baggage-Middleware über ObservabilityHostingManager.configure(), anstatt sie direkt auf dem Adapter zu registrieren.

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

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

Die Middleware überspringt die Einrichtung von Baggage bei asynchronen Antworten (ContinueConversation-Ereignissen), um zu vermeiden, dass Baggage überschrieben wird, das bereits von der ursprünglichen Anfrage gesetzt wurde.

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

Um Agententelemetrie in Microsoft Purview oder Microsoft Defender anzuzeigen, stellen Sie sicher, dass die folgenden Anforderungen erfüllt sind:

Automatische Instrumentierung

Die Microsoft OpenTelemetry Distro kombiniert Standard-OpenTelemetrie-Pipelines mit von Microsoft kuratierter Instrumentierung. Die Distro kann Anwendungs-Telemetrie, Infrastruktur-Telemetrie sowie Agenten- oder generative KI-Telemetrie erfassen, je nach Sprache und Konfiguration.

Kategorie Was es abdeckt
Signal-Pipelines Nachverfolgungen, Metriken und Protokolle.
Ressourcenerkennung Service-, Host-, Cloud- und Azure-Laufzeitkontext, sofern unterstützt.
Infrastrukturinstrumentierung HTTP, ASP.NET Core, Azure SDK, Datenbank-Clients und Logging-Frameworks, sofern unterstützt.
Generative KI-Instrumentierung OpenAI, Azure OpenAI, Semantischer Kernel, LangChain, OpenAI Agents SDK und Agent Framework, sofern unterstützt.
Manuelle Agent-Bereiche Agent-Aufruf, Toolausführung, Rückschluss und Ausgabetelemetrie, sofern unterstützt.
Exporter und Verarbeiter Azure Monitor, Microsoft Agent 365, OTLP, Konsolenausgabe, Span-Prozessoren, Log-Prozessoren und Metrikleser.

Instrumentierungsabdeckung

Sprache Gemeinsame Anwendungsinstrumentierung Gängige Agent- und generative KI-Instrumentierung
Python OpenTelemetry Resources, Prozessoren, Reader, Protokollierung, Metriken und Traces. Semantischer Kernel, OpenAI Agents SDK, Agent Framework, LangChain, Microsoft Agent 365 Baggage 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 Baggage und Microsoft Agent 365-Bereiche.
.NET ASP.NET Core, HttpClient, SQL Client, Azure-SDK, Ressourcenerkennung, Metriken und Logs. Semantischer Kernel, OpenAI und Azure OpenAI, Agent Framework, Microsoft Agent 365 Baggage und Microsoft Agent 365-Bereiche.

Automatische Instrumentierung überwacht Telemetriesignale, die von unterstützten Bibliotheken und Frameworks gesendet werden. Manuelle Instrumentierung wird verwendet, wenn eine Anwendung agentenspezifische Operationen wie Aufruf, Werkzeugausführung, Inferenz oder asynchrone Ausgabe erfassen muss.

Fügen Sie benutzerdefinierte OpenTelemetry Sources, Meter, Prozessoren oder Reader hinzu, wenn Ihre Anwendung Telemetrie erzeugt, die nicht durch die integrierten Instrumentierungen abgedeckt wird.

Wichtig

Die automatische Instrumentierung setzt ausschließlich Standard-OpenTelemetry-Attribute. Die automatische Instrumentierung umfasst nicht alle Attribute, die von Agent 365 benötigt werden. Sie müssen Microsoft-spezifische Attribute über BaggageBuilder hinzufügen. Um zu sehen, welche Attribute benötigt werden, siehe Store-Prüfungsattribute.

Integrierte Instrumentierungsbibliotheken

Die Auto-Instrumentierung erfasst Telemetrie, die von unterstützten Frameworks erzeugt wird, und leitet sie durch die OpenTelemetry-Pipeline der Distro weiter. Legen Sie für Agent-Szenarien Baggage fest, z. B. Mandanten-ID und Agent-ID, bevor das instrumentierte Framework Abschnitte erstellt.

Framework Python Node.js .NET
Semantischer Kernel Unterstützt Nicht unterstützt Unterstützt
OpenAI und OpenAI Agents SDK Unterstützt Unterstützt Unterstützt
Agent Framework Unterstützt Nicht unterstützt Unterstützt
LangChain Unterstützt Unterstützt Nicht aufgeführt

Semantischer Kernel

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},
    },
)

Agent 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

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 die Aktivitäten des Agenten nicht detailliert genug abbildet. Manuelle Umfangs ermöglichen es einer Anwendung, gemeinsame Agentenaktivitäten auf konsistente Weise über verschiedene Programmiersprachen hinweg abzubilden.

Geltungsbereich Zweck
InvokeAgentScope Der Anfang und Abschluss eines Agent-Aufrufs.
ExecuteToolScope Ein Toolaufruf durch einen Agenten.
InferenceScope Eine KI-Modell-Inferenzoperation.
OutputScope Ausgabe, die aufgezeichnet werden muss, nachdem der ursprüngliche Bereich bereits abgeschlossen wurde.

Verwenden Sie dieselben Anforderungs- und Agent-Identitätswerte in den Bereichen einer Anforderung erneut, sodass zugehörige Telemetriewerte korreliert werden können.

Agent-Aufruf

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."])

Ausführung des Tools

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)

Rückschluss

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"])

Istmeldung

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 etwaige produktspezifische Validierungsanforderungen für diese Umfangs definieren.

Lokale Validierung

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

Validierung mit einem lokalen OTLP-Endpunkt

Konfigurieren Sie die Distro so, dass Telemetrie an einen lokalen Collector oder einen anderen OTLP-kompatiblen Endpunkt gesendet wird.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Validierung mit lokaler Ausgabe

Verwenden Sie die lokale Ausgabe, wenn Sie die Instrumentierung überprüfen möchten, bevor Sie Telemetrie an ein Remote-Ziel 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 Abschnitte aus erwarteten Quellen, wie z. B. HTTP-Anfragen, OpenAI- oder Azure OpenAI-Aufrufe, Aufrufbereiche von Agents, Ausführungsbereiche von Tools oder Inferenzbereiche. Die zielspezifische Prüfung gehört zur Produktdokumentation für dieses Ziel.

Manuelle Authentifizierung einrichten

Wenn Sie den Agent 365 Exporter verwenden, müssen Sie einen Mechanismus implementieren, um ein Authentifizierungstoken bereitzustellen. Der Tokenauflöser arbeitet pro Exportbatch, wobei er die Agent-ID und die Mandanten-ID aus dem Kontext des aktiven Baggage verwendet. Die Distro unterstützt zwei Ansätze.

Trinkgeld

Wenn Sie Agents mit dem Microsoft 365 Agents SDK erstellen, finden Sie unter Einrichtung der Einblick-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 Tokenresolver

Verwenden Sie einen manuellen Resolver, wenn Sie Token außerhalb der Agent Framework-Pipeline erwerben, wenn Sie Nicht-Agent Framework-Anwendungen erstellen oder wenn Sie Service-to-Service (S2S)-Authentifizierung (Client-Credentials-Flow) verwenden. Agenten können selbst ein Token generieren, zum Beispiel mit der Microsoft Authentication Library (MSAL) (MSAL) oder einer anderen Methode zur Token-Erwerbung, müssen aber sicherstellen, dass das Token den richtigen Einblick-Umfang besitzt (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite).

Anmerkung

Bei der Service-to-Service-Authentifizierung (S2S) müssen Sie den manuellen Token-Resolver verwenden. Der agentische Token-Cache unterstützt nur On-Behalf-Of-(OBO)-Authentifizierungsflüsse.

Die folgenden Beispiele zeigen das Muster für den OBO-Tokenauflöser. Der Agent bezieht über den agentischen Authentifizierungs-Handler ein Benutzertoken und tauscht es gegen ein auf den Einblick-Bereich beschränktes Token aus. Für S2S (Service-to-Service) Beispiele und einen Vergleich von OBO- und S2S-Authentifizierung siehe Einblick 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",
    )

Agentenbasierte Tokenzwischenspeicherung mit Agent Framework-Anwendungen

Für Agent Framework-Apps, die On-Behalf-Of-(OBO)-Authentifizierung verwenden, registriert die Distro IExporterTokenCache<AgenticTokenStruct> automatisch über DI, wenn keine benutzerdefinierte TokenResolver festgelegt wird. Ihr Agent ruft RegisterObservability() zur Laufzeit auf, um Zugangsdaten bereitzustellen, und der Cache übernimmt die Token-Erfassung und Aktualisierung.

Anmerkung

Dieser Ansatz unterstützt ausschließlich On-Behalf-Of (OBO)-Authentifizierungsflüsse. Für die Service-to-Service-Authentifizierung (S2S) verwenden Sie stattdessen den manuellen Token-Resolver.

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

Speicherprüfungsattribute

Für eine erfolgreiche Store-Validierung muss Ihr Agent InvokeAgentScope, InferenceScope und ExecuteToolScope implementieren. Jeder Bereich entspricht einem Bereichsvorgang im kanonischen Schema:

SDK-Umfang Vorgangs-Weite Universeller Referenzcode
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

Die vollständigen Listen der je Umfang erforderlichen und optionalen Attribute – inklusive der Semantik jedes Attributs, Leitfaden zur Wertauswahl und Informationen darüber, welche Attribute über Microsoft Defender Advanced Hunting abfragbar sind – finden Sie unter Agent 365 Einblick-Attributreferenz. Die Gilt für -Spalte kennzeichnet, welchem Umfang jedes Attribut zugeordnet ist, und die Erforderlich-Spalte unterscheidet verpflichtende (M) von optionalen (O) Attributen.

Testen Ihres Agents mit Einblick

Nach der Implementierung der Einblicke überprüfen Sie, ob Telemetrie erfasst wird:

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

Beispielanwendungen und erweiterte Konfiguration

Funktionsbeispiele und erweiterte Konfigurationsoptionen finden Sie in den GitHub-Repositories der einzelnen Programmiersprachen:

Problembehandlung

Dieser Abschnitt beschreibt häufige Probleme bei der Implementierung und Nutzung des Microsoft OpenTelemetry Distro mit Agent 365.

Problem Beschreibung des Dataflows
Einblicksdaten werden nicht angezeigt Keine Telemetriedaten sind sichtbar, weil der Agent 365-Export nicht aktiviert wurde, die Einrichtung nicht vollständig abgeschlossen wurde oder die Token-Auflösung fehlschlägt.
Fehlende Mandanten-ID oder Agent-ID – Spans übersprungen 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 keinen Token zurückgibt oder Fehler bei der Token-Erfassung auftreten.
HTTP 401 – nicht autorisiert Anfragen erreichen den Dienst, aber die Authentifizierung schlägt fehl, weil das Token ungültig, abgelaufen oder für das falsche Ziel ist.
HTTP 403 – verboten Die Autorisierung schlägt fehl, weil die Mandant-Lizenzierung oder die Schreibberechtigung für Einblicke fehlt.
HTTP 403 verboten - Agent-ID stimmt nicht überein Der Dienst lehnt den Export ab, wenn die Agent-ID in der Anfrage nicht mit der durch das Token autorisierten Agent-Identität übereinstimmt.
HTTP 429- oder 5xx-Fehler – Transiente Fehler Temporäre Drosselung oder Back-End-Instabilität unterbricht den Export und erfordert möglicherweise Wiederholversuche oder Batchoptimierungen.
Exportzeitüberschreitung Exportoperationen überschreiten die Timeout-Grenzwerte aufgrund von Netzwerkverzögerungen oder Endpunkt-Antwortlatenz.
Export war erfolgreich, aber Telemetriedaten werden weder in Defender noch in Purview angezeigt Die Datenaufnahme gelingt, aber die Sichtbarkeit wird durch nachgelagerte Voraussetzungen und Schemaanforderungen verzögert oder blockiert.

Trinkgeld

Die Agent 365 Troubleshooting-Anleitung enthält übergeordnete Empfehlungen zur Fehlerbehebung, Best Practices und Links zu Inhalten zur Fehlerbehebung für jeden Abschnitt des Entwicklungszyklus von Agent 365.

Einblicksdaten werden nicht angezeigt

Symptome:

  • Agent wird ausgeführt
  • Keine Telemetrie im Admin Center
  • Kann keine Agentenaktivität sehen

Grundursache:

  • Agent 365 Export ist nicht aktiviert
  • Konfigurationsfehler
  • Token Resolver-Probleme

Lösungen: Führen Sie die folgenden Schritte aus, um das Problem zu beheben:

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

    Sie müssen den Agent 365 Exporter explizit aktivieren. Wenn Sie diese Option nicht festlegen, greift die Distribution möglicherweise auf einen Konsolenexporteur zurück oder führt keinen Export durch. Aktivieren Sie es 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

    Anmerkung

    ENABLE_A365_OBSERVABILITY_EXPORTER ist ein sekundärer Schalter, der nur greift, wenn enable_a365=True im Code gesetzt ist. Sie können dies auch über das a365_enable_observability_exporter-Kwarg steuern.

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

    Der Exporter benötigt einen gültigen Token-Resolver, der für jede Exportanfrage ein Bearer-Token zurückgibt. Wenn der Token-Resolver fehlt oder null zurückgibt, wird der Export stillschweigend übersprungen.

  • Aktivieren Sie den Konsolenexport und überprüfen Sie lokal die Telemetrie

    Fügen Sie einen Konsolenexporter hinzu, um zu überprüfen, ob die Telemetrie erzeugt wird, bevor sie den Endpunkt von Agent 365 erreicht:

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Ausführliches Protokoll aktivieren

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Überprüfen Sie Protokolle auf Exportfehler

    Verwenden Sie den az webapp log tail-Befehl, um Protokolle nach einblicksbezogenen 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 – Abschnitte übersprungen

Symptome: Das System löscht die Abschnitte unbemerkt und exportiert sie nie. Einige Plattformen protokollieren eine Anzahl übersprungener Spans oder eine Nachricht wie No spans with tenant/agent identity found. Andere löschen sie, ohne sie zu protokollieren.

Lösung:

  • Vor dem Export unterteilt die Distribution die Abschnitte nach Mandanten- und Agent-Identität. Abschnitte, denen entweder die Mandanten-ID oder die Agent-ID fehlt, werden verworfen und niemals an den Service gesendet.
  • Stellen Sie sicher, dass BaggageBuilder mit der Mandanten-ID und der Agent-ID konfiguriert ist, bevor Sie Abschnitte erstellen. Diese Werte werden über den OpenTelemetry-Kontext verteilt und an alle Abschnitte angefügt, die innerhalb des Baggage-Bereichs erstellt werden. Weitere Informationen zur plattformspezifischen API finden Sie unter Baggage-Attribute.
  • Wenn Sie die „Baggage“-Middleware oder den „Turn“-Kontext-Helper aus dem Hosting-Integrationspaket verwenden, stellen Sie sicher, dass die TurnContext-Aktivität einen gültigen Empfänger mit Agent-Identität aufweist.

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

Symptome: Der Token-Resolver liefert null zurück oder wirft eine Ausnahme. Je nach Plattform wird der Export entweder übersprungen oder scheitert mit HTTP 401.

Lösung:

  • Der Token-Resolver ist erforderlich. Fehlt er, löst der Exporter beim Start einen Fehler aus. Stellen Sie sicher, dass ein Token-Resolver bereitgestellt wird und ein gültiges Bearer-Token zurückgibt.
  • Stellen Sie sicher, dass die korrekte Mandanten-ID und Agenten-ID an BaggageBuilder übergeben werden, da diese Werte an den Token-Resolver weitergeleitet werden.
  • Für Azure-gehostete Agenten stellen Sie sicher, dass die verwaltete Identität über die erforderliche API-Berechtigung für den Einblicke-Scope verfügt.
  • Für .NET-Anwendungen, die das Agent Framework-Hosting-Paket verwenden, erfolgt der Tokenaustausch automatisch über DI. Wenn Token fehlen, bestätigen Microsoft.Agents.A365.Observability.Hosting Sie, ob sie installiert und registriert sind.

HTTP 401 – nicht autorisiert

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

Lösung:

  • Stellen Sie sicher, dass die Zielgruppe des Tokens mit dem Bereich des Einblicksendpunkts übereinstimmt.
  • Überprüfen Sie, ob der Token-Resolver kein delegiertes Benutzertoken, ein Token für eine falsche Zielgruppe oder ein abgelaufenes Token zurückgibt.

HTTP 403 – Unzulässig

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

Grundursache: Ein HTTP-403-Fehler kann verschiedene Ursachen haben. Überprüfen Sie die folgenden Lösungen in der angegebenen Reihenfolge.

Lösung:

  • Fehlende Lizenz – Überprüfen Sie, ob Ihrem Mandanten eine der folgenden Lizenzen im Microsoft 365 Admin Center zugewiesen ist:

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

  • Fehlende Agent365.Observability.OtelWrite-Berechtigung: Sie müssen Ihrer Identität (verwaltete Identität oder App-Registrierung) die Berechtigung erteilen. Ohne diese Berechtigung schlägt der Telemetrieexport mit HTTP 403 fehl.

Berechtigung gewähren

Nutzen Sie eine der folgenden Optionen:

  • Agent 365 CLI

    Erfordert ein Konto eines globalen Admins; führen Sie den Befehl im Agent-Projektverzeichnis aus, das a365.config.json enthält, oder verwenden Sie --agent-name.

    a365 setup permissions bot

    Oder ohne Konfigurationsdatei:

    a365 setup permissions bot --agent-name "<agent-name>"

  • Entra Portal

    Keine Konfigurationsdateien erforderlich; erfordert Global Administrator-Zugriff auf die Blueprint-App-Anmeldung.

    1. Gehen Sie zu Entra-Portal>App-Registrierungen> und wählen Sie Blueprint-App.
    2. Navigieren Sie zu API-Berechtigungen>,Berechtigung hinzufügen>APIs, die von meiner Organisation verwendet werden>, suchen Sie nach 9b975845-388f-4429-889e-eab1ef63949c.
    3. Wählen Sie Delegierte Berechtigungen> aus, setzen Sie ein Häkchen bei Agent365.Observability.OtelWrite>Berechtigungen hinzufügen.
    4. Wiederholen Sie die Schritte 2–3, wählen Sie diesmal Anwendungsberechtigungen> aus, setzen Sie ein Häkchen bei Agent365.Observability.OtelWrite>Berechtigungen hinzufügen.
    5. Klicken Sie auf Administratoreinwilligung gewähren gewähren und bestätigen.

    Sowohl Agent365.Observability.OtelWrite (Delegiert) als auch Agent365.Observability.OtelWrite (Anwendung) sollten den Status Granted anzeigen.

HTTP 403 Forbidden — Agent-ID stimmt nicht überein

Symptome: Der Export schlägt mit HTTP 403 und einer Servernachricht fehl, die ähnlich ist wie 403 Forbidden bei agent-ID-mismatch Fehlern beim Aufruf der Agent 365 Ablauf-Endpunkte.

Hauptursache: Dieser Fehler tritt auf, wenn Sie die Blueprint-Client-ID anstelle der Agent-Instanz-Client-ID bei der Einstellung der Agentendetails verwenden. Die Agenten-ID in der Export-URL stimmt nicht mit der vom Token autorisierten Identität überein, sodass der Ablauf-Endpunkt die Anfrage ablehnt.

Lösung:

  • Überprüfen Sie, ob die Mandanten-ID zur Liste der für die Trace-Erfassung zugelassenen Mandanten in Agent 365 hinzugefügt wurde.
  • Geben Sie die Agentendetails mit der Agent-Instanz-Client-ID an (nicht die Blueprint-Client-ID).
  • Überprüfen Sie die generierte Export-URL - sie wird protokolliert, wenn Sie Ihren Logger aktivieren. Überprüfen Sie, ob die Agent-ID in der URL mit der Client-ID der Agent-Instanz übereinstimmt.
  • Um diagnostisches Logging pro SDK zu ermöglichen, siehe Lokale Validierung.

HTTP 429- oder 5xx-Fehler – Transiente Fehler

Symptome: Der Export scheitert mit einem vorübergehenden HTTP-Statuscode wie 429 oder 5xx.

Lösung:

  • Diese Fehler sind in der Regel vorübergehend und beheben sich von allein. Die Python- und JavaScript-Distros führen automatisch einen erneuten Versuch bei HTTP 408, 429 und 5xx-Statuscodes durch. Die .NET-Distribution versucht es nicht automatisch erneut.
  • Sollten die Fehler weiterhin auftreten, überprüfen Sie das Service-Health-Dashboard.
  • Erwägen Sie, die Exportfrequenz zu reduzieren, indem Sie die geplante Verzögerung zwischen den Batches oder die maximale Export-Batchgröße erhöhen. Für Python und JavaScript verwenden Sie die relevanten exporterOptions- oder a365_*-Parameter, die in den GitHub-Repositorien dokumentiert sind. Für .NET verwenden Sie o.Agent365.Exporter.ScheduledDelayMilliseconds und o.Agent365.Exporter.MaxExportBatchSize.

Exportzeitüberschreitung

Symptome: Exportversuche laufen ab.

Lösung:

  • Überprüfen Sie die Netzwerkverbindung zum Einblick-Endpunkt.

  • Das Standard-Timeout für HTTP-Anfragen beträgt 30 Sekunden auf allen Plattformen. Wenn Timeouts häufig auftreten, erhöhen Sie den Timeout-Wert in Ihren Exportoptionen:

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

    Die vollständige Liste der a365_* Optionen finden Sie im Python-Repository.

Export war erfolgreich, aber Telemetriedaten werden weder in Defender noch in Purview angezeigt

Symptome: Die Protokolle zeigen einen erfolgreichen Export (HTTP 200), aber Telemetrie ist in Microsoft Defender oder Microsoft Purview nicht sichtbar.

Lösung:

  • Stellen Sie sicher, dass Sie die Voraussetzungen für das Anzeigen exportierter Protokolle erfüllen:
  • Nach einem erfolgreichen Export kann es mehrere Minuten dauern, bis die Telemetrie angezeigt wird. Warten Sie, bevor Sie weiter untersuchen.
  • Überprüfen Sie, ob Spans gültige microsoft.tenant.id und gen_ai.agent.id Attribute enthalten. Fehlende Identitätsattribute führen dazu, dass Spans auf der Serverseite verworfen werden, auch wenn der HTTP-Export einen Status 200 zurückgibt.

Zugehöriger Inhalt

  • Last updated on