Microsoft OpenTelemetry Distro

Microsoft OpenTelemetry Distro is een geïntegreerde oplossing voor waarneembaarheid die een gestroomlijnde onboarding biedt voor het verzamelen van traceringen, metrische gegevens en logboeken uit agentische en niet-agentische toepassingen. Het ondersteunt waarneembaarheid voor Microsoft Agent 365, Microsoft Foundry, Azure Monitor en elke back-end die compatibel is met het OpenTelemetry Protocol (OTLP). De distributie ondersteunt .NET, Node.js en Python en vervangt gefragmenteerde configuraties over meerdere waarneembaarheid-stacks door één import en één configuratie-aanroep.

Belangrijkste voordelen

De Microsoft OpenTelemetry Distro biedt de volgende voordelen:

  • Eén pakket, één API: vervang meerdere exporter- en instrumentatiepakketten door één enkele afhankelijkheid.
  • Support voor meerdere back-ends: verzend telemetrie naar Azure Monitor, een OTLP-compatibel eindpunt zoals Datadog, Grafana of New Relic, en Microsoft Agent 365 op hetzelfde moment.
  • Ingebouwde instrumentaties: gebruik automatische instrumentatie voor HTTP, databases, Azure SDK, Azure Functions en meer zonder extra configuratie.
  • Gebaseerd op standaarden: bouw voort op OpenTelemetry, het branchestandaard framework voor waarneembaarheid.
  • Minimale standaard: voeg één import en één functieaanroep toe aan het toegangspunt van uw applicatie.

Installatie en configuratie

Deze handleiding laat zien hoe u waarneembaarheid toevoegt aan uw applicatie met Microsoft OpenTelemetry Distro. De Distro verzamelt automatisch traceringen, metrische gegevens en logboeken met ingebouwde instrumentatie en exporteert de telemetry naar Azure Monitor, elk OTLP-compatibel eindpunt of Microsoft Agent 365.

Bibliotheek installeren

Als u aan de slag wilt gaan met de Microsoft OpenTelemetry Distro, installeert u de juiste bibliotheek voor uw ontwikkelplatform via de pakketmanager van uw programmeertaal.

Vereisten: Python 3.10 of hoger.

pip install microsoft-opentelemetry

Configuratie

De Agent 365-exporter gebruikt geen verbindingsreeks. Het ontdekt zijn eindpunt automatisch op basis van de tenant. Als u export naar Agent 365 mogelijk wilt maken, stelt u het exportdoel in en geeft u een tokenomzetter op die een toegangstoken levert voor een opgegeven agent-id en tenant-id.

Roep use_microsoft_opentelemetry() aan om waarneembaarheid in te schakelen.

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

Voor aangepaste tokenresolutie (in plaats van de standaard tokenomzetter) gaat u naar Handmatige tokenomzetter.

U kunt het gedrag van de exporter aanpassen door optionele a365_*-kwargs aan use_microsoft_opentelemetry() mee te geven.

Parameter Omschrijving Standaard
a365_use_s2s_endpoint Wanneer dit True is, gebruikt het het eindpuntpad van de service-to-service. False
a365_max_queue_size Maximale wachtrijgrootte voor de batchprocessor. 2048
a365_scheduled_delay_ms Vertraging in milliseconden tussen exportbatches. 5000
a365_exporter_timeout_ms Time-out in milliseconden voor de exportbewerking. 30000
a365_max_export_batch_size Maximale batchgrootte voor exportbewerkingen. 512

Contextpropagatie

Als u waarneembaarheid wilt behouden over gedistribueerde Agent 365-bewerkingen, propageert u context. Door context te propageren via uw agents en services, zorgt u ervoor dat traceringen, logboeken en metrische gegevens op de juiste manier met elkaar verbonden worden gedurende de volledige levenscyclus van de aanvraag. Deze correlatie is vereist voor een volledige en effectieve Microsoft Agent 365-bewaking.

Bagagekenmerken

Gebruik BaggageBuilder om contextuele informatie in te stellen, die door alle spans in een aanvraag loopt. De SDK implementeert een SpanProcessor die alle niet-lege bagageposten naar nieuw gestarte spans kopieert, zonder bestaande kenmerken te overschrijven.

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

Gebruik de populate helper in het microsoft-opentelemetry-pakket om de BaggageBuilder automatisch in te vullen vanuit de TurnContext. Deze helper haalt automatisch de details van beller, agent, tenant, kanaal en gesprek uit de activiteit.

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

Bagage-middleware

Wanneer uw agent het hostingintegratiepakket gebruikt, registreert u bagage-middleware om bagage automatisch in te vullen voor iedere binnenkomende aanvraag. Deze stap zorgt dat het niet langer nodig is om BaggageBuilder handmatig aan te roepen in elke activiteitenhandler.

Registreer in Python bagage-middleware via ObservabilityHostingManager.configure() in plaats van direct in de adapter.

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

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

De middleware slaat het instellen van bagage over voor asynchrone antwoorden (ContinueConversation-gebeurtenissen) om te voorkomen dat bagage die door het oorspronkelijke verzoek is ingesteld, wordt overschreven.

Valideergegevens stromen in het product

Als u agenttelemetrie in Microsoft Purview of Microsoft Defender wilt bekijken, zorg er dan voor dat aan de volgende vereisten wordt voldaan:

Automatische instrumentatie

De Microsoft OpenTelemetry Distro combineert standaard OpenTelemetry-pijplijnen met door Microsoft samengestelde instrumentatie. De Distro kan applicatietelemetrie, infrastructuurtelemetrie en agentische of generatieve AI-telemetrie verzamelen, afhankelijk van taal en configuratie.

Categorie Wat het omvat
Signaalpijplijnen Traceringen, metrische gegevens en logboeken.
Resourcedetectie Service-, host-, cloud- en Azure-runtimecontext werden ondersteund.
Infrastructuurinstrumentatie HTTP, ASP.NET Core, Azure SDK, databaseclients en frameworks voor logboekregistraties, wanneer deze worden ondersteund.
Generatieve AI-instrumentatie OpenAI, Azure OpenAI, Semantic Kernel, LangChain, OpenAI Agents SDK en Agent Framework, wanneer deze worden ondersteund.
Bereik voor handmatige agents Agentaanroep, tooluitvoering, inferentie en uitvoertelemetrie, wanneer deze worden ondersteund.
Exporters en verwerkers Azure Monitor, Microsoft Agent 365, OTLP, console-uitvoer, span-processors, logboekprocessors en lezers van metrische gegevens.

Instrumentatiedekking

Taal Instrumentatie van de algemene toepassing Veelvoorkomende agentische en generatieve AI-instrumentatie
Python OpenTelemetry-bronnen, processors, lezers, logboekregistratie, metrische gegevens en traceringen Semantic Kernel, OpenAI Agents SDK, Agent Framework, LangChain, Microsoft Agent 365-baggage en Microsoft Agent 365-bereiken.
Node.js HTTP, Azure SDK, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis, Bunyan en Winston. OpenAI Agents SDK, LangChain, Microsoft Agent 365 bagage en Microsoft Agent 365-bereiken.
.NET ASP.NET Core, HttpClient, SQL Client, Azure SDK, resource-detectie, metrische gegevens en logboeken. Semantic Kernel, OpenAI en Azure OpenAI, Agent Framework, Microsoft Agent 365-baggage en Microsoft Agent 365-bereiken.

Automatische instrumentatie luistert naar telemetriesignalen die worden uitgezonden door ondersteunde bibliotheken en frameworks. Handmatige instrumentatie wordt gebruikt wanneer een toepassing agent-specifieke bewerkingen moet beschrijven, zoals aanroepen, tooluitvoering, inferentie of asynchrone uitvoer.

Voeg aangepaste OpenTelemetry-bronnen, meters, processors of lezers toe wanneer uw toepassing telemetrie verstuurt die niet wordt gedekt door de ingebouwde instrumentatie.

Belangrijk

Automatische instrumentatie vult alleen standaard OpenTelemetry-kenmerken in. Het bevat niet alle kenmerken die Agent 365 vereist. U moet Microsoft-specifieke kenmerken toevoegen via BaggageBuilder. Als u wilt zien welke kenmerken vereist zijn, gaat u naar Validatiekenmerken opslaan.

Ingebouwde instrumentatiebibliotheken

Automatische instrumentatie detecteert telemetrie die door ondersteunde frameworks wordt gegenereerd en stuurt deze door via de OpenTelemetry-pijplijn van de Distro. Stel voor agentscenario's baggage in zoals tenant-id en agent-id voordat het geïnstrumenteerde framework spans aanmaakt.

Framework Python Node.js .NET
Semantic Kernel Ondersteund Niet ondersteund Ondersteund
OpenAI and OpenAI Agents SDK Ondersteund Ondersteund Ondersteund
Agent Framework Ondersteund Niet ondersteund Ondersteund
LangChain Ondersteund Ondersteund Niet vermeld

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

Handmatige instrumentatie

Gebruik handmatige instrumentatie wanneer automatische instrumentatie de werking van de agent niet voldoende gedetailleerd beschrijft. Met handmatige bereiken kan een toepassing veelvoorkomende agentactiviteiten op een consistente manier in verschillende talen beschrijven.

Scope Gebruiken voor
InvokeAgentScope Het begin en de voltooiing van een agent-aanroep
ExecuteToolScope Een tool-aanroep door een agent.
InferenceScope Een AI-modelinferentiebewerking.
OutputScope Uitvoer die moet worden vastgelegd nadat het oorspronkelijke bereik al is voltooid.

Gebruik dezelfde aanvraag- en agentidentiteitswaarden over bereiken binnen een aanvraag zodat gerelateerde telemetrie kan worden gecorreleerd.

Agentaanroepen

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

Uitvoering van hulpprogramma

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)

Deductie

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

Uitvoer

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

Productdocumentatie moet productspecifieke validatievereisten voor deze bereiken definiëren.

Lokale validatie

Lokale validatie bevestigt dat de toepassing telemetrie produceert voordat een productspecifieke bestemming wordt gevalideerd. Gebruik console-uitvoer of een lokaal OTLP-eindpunt om te controleren of traceringen, metrische gegevens en logboeken worden aangemaakt.

Valideer met een lokaal OTLP-eindpunt

Configureer de distro om telemetrie naar een lokale collector te verzenden of naar een ander OTLP-compatibel eindpunt.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Met lokale uitvoer valideren

Gebruik lokale uitvoer wanneer u de instrumentatie wilt controleren voordat u telemetry naar een externe bestemming verzendt.

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.

Controleer de lokale uitvoer op spans van verwachte bronnen, zoals HTTP-verzoeken, OpenAI- of Azure OpenAI-calls, agent-aanroepbereiken, tool-uitvoeringsbereiken of inferentiebereiken. Bestemmingsspecifieke validatie hoort thuis in de productdocumentatie van die bestemming.

Handmatig verificatie instellen

Wanneer u de Agent 365-exporter gebruikt, moet u een methode bieden om een verificatietoken aan te leveren. De tokenomzetter werkt per exportbatch en maakt daarbij gebruik van de agent-id en tenant-id uit de actieve bagagecontext. De distro ondersteunt twee benaderingen.

Fooi

Als u agents ontwikkelt met de SDK voor Microsoft 365-agents gaat u naar Instellen van waarneembaarheidsverificatie voor Agent SDK voor stapsgewijze instructies voor het configureren van OBO- en S2S-tokenverwerving voor zowel agentische als niet-agentische agents.

Handmatige tokenomzetter

Gebruik een handmatige tokenomzetter wanneer u tokens van buiten de Agent Framework-pijplijn verkrijgt, wanneer u apps bouwt buiten het Agent Framework, of wanneer u service-to-service (S2S)-verificatie gebruikt (clientreferentiestroom). Agents kunnen zelf een token genereren, bijvoorbeeld door gebruik te maken van de Microsoft-verificatiebibliotheek (MSAL) of een andere methode voor het verkrijgen van tokens, maar ze moeten ervoor zorgen dat het token het juiste waarneembaarheidsbereik api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite heeft.

Notitie

Voor service-to-service-verificatie (S2S) moet u deze handmatige tokenomzetter gebruiken. De agentische tokencache ondersteunt alleen on-behalf-of (OBO) verificatiestromen.

De volgende voorbeelden tonen het tokenomzetterpatroon van OBO (on-behalf-of): de agent verkrijgt een gebruikerstoken via de agentische auth-handler en ruilt deze in voor een token voor waarneembaarheidsbereik. Voor voorbeelden van S2S (service-to-service) en een vergelijking van OBO/S2S-verificatie gaat u naar Instellen van waarneembaarheidsverificatie voor Agent SDK.

De omzetter moet synchroon zijn. Verkrijg het token in uw asynchrone activiteitshandler (of via MSAL) en cache het voor de omzetter.

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

Agentische tokencache met Agent Framework-apps

Voor Agent Framework-apps die on-behalf-of (OBO) verificatie gebruiken, registreert de distro automatisch IExporterTokenCache<AgenticTokenStruct> via DI wanneer u geen aangepaste TokenResolver instelt. Uw agent roept RegisterObservability() aan tijdens de runtime om referenties te verstrekken en de cache verzorgt het verkrijgen en vernieuwen van tokens.

Notitie

Deze aanpak ondersteunt alleen on-behalf-of (OBO) verificatiestromen. Gebruik de handmatige tokenomzetter in plaats daarvan voor S2S-verificatie (service-to-service ).

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

Validatiekenmerken opslaan

Voor een succesvolle opslagvalidatie moet uw agent InvokeAgentScope, InferenceScope en ExecuteToolScope implementeren. Elk bereik komt overeen met een spanbewerking in het canonieke schema:

SDK-bereik Span-bewerking Universele referentiecode
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

Voor de volledige lijsten van verplichte en optionele kenmerken per bereik, inclusief de semantiek per kenmerk, richtlijnen voor het kiezen van waarden en welke kenmerken via Microsoft Defender Advanced Hunting kunnen worden opgevraagd, gaat u naar Kenmerkreferentie voor Agent 365-waarneembaarheid. De kolom Van toepassing op geeft aan bij welk bereik elk kenmerk hoort, terwijl de kolom Vereist onderscheid maakt tussen verplichte (M) en optionele (O) kenmerken.

Uw agent testen met waarneembaarheid

Controleer na het implementeren van waarneembaarheid of er telemetry wordt vastgelegd:

  1. Ga naar https://admin.cloud.microsoft/#/agents/all.
  2. Selecteer uw agent en selecteer vervolgens Activiteit.
  3. Controleer of sessies en toolaanroepen zichtbaar zijn.

Voorbeeldtoepassingen en geavanceerde configuratie

Voor werkende voorbeelden en geavanceerde configuratieopties, gaat u naar de GitHub-opslagplaatsen voor elke taal:

Probleemoplossing

Deze sectie beschrijft veelvoorkomende problemen bij het implementeren en gebruiken van de Microsoft OpenTelemetry Distro met Agent 365.

Probleem Omschrijving
Waarneembaarheidsgegevens zijn niet zichtbaar Er zijn geen telemetriegegevens zichtbaar omdat de export van Agent 365 niet is ingeschakeld, de configuratie onvolledig is of de tokenresolutie faalt.
Ontbrekende tenant-id of agent-id - spans overgeslagen Spans worden gefilterd voordat ze worden geëxporteerd wanneer vereiste tenant- of agentidentiteitskenmerken ontbreken.
Tokenresolutiefout - export overgeslagen of ongeautoriseerd De export wordt overgeslagen of geweigerd wanneer de tokenomzetter geen token retourneert of wanneer er fouten optreden tijdens het verkrijgen van een token.
HTTP 401 Niet-geautoriseerd Verzoeken bereiken de service, maar verificatie mislukt omdat het token ongeldig, verlopen is of voor de verkeerde doelgroep is ingesteld.
HTTP 403 Verboden Verificatie faalt door het ontbreken van tenantlicenties of schrijfrechten voor waarneembaarheid.
HTTP 403 Verboden - Agent-id komt niet overeen De service weigert export wanneer de agent-id in het verzoek niet overeenkomt met de door de token geverifieerde agentidentiteit.
HTTP 429 of 5xx-fouten - tijdelijke fouten Tijdelijke beperking of instabiliteit van de back-end onderbreekt de export en kan herhalingen of afstemming van batches vereisen.
Exporttime-out Exportoperaties overschrijden de time-outlimieten door netwerkvertragingen of reactietijd van het eindpunt.
Export slaagt, maar telemetrie verschijnt niet in Defender of Purview Gegevensopname is geslaagd, maar de zichtbaarheid wordt vertraagd of geblokkeerd door downstreamvereisten en schema-eisen.

Fooi

De Gids voor probleemoplossing in Agent 365 bevat aanbevelingen voor probleemoplossing op hoog niveau, best practices en links naar relevante probleemoplossingsinformatie voor elk onderdeel van de Agent 365-ontwikkelingscyclus.

Waarneembaarheidsgegevens zijn niet zichtbaar

Symptomen:

  • Agent wordt uitgevoerd
  • Geen telemetrie in het beheercentrum
  • Kan de activiteit van de agent niet zien

Hoofdoorzaak:

  • Agent 365-export is niet ingeschakeld
  • Configuratiefouten
  • Problemen met tokenomzetter

Oplossingen: probeer de volgende stappen uit om het probleem op te lossen:

  • Controleer of Agent 365-export is ingeschakeld

    U moet de Agent 365-exporter expliciet inschakelen. Wanneer u deze niet instelt, kan de distro terugvallen op een console-exporter of niets exporteren. Schakel het in de code in:

    from microsoft.opentelemetry import use_microsoft_opentelemetry

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

    Of stel de omgevingsvariabele in:

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    Notitie

    ENABLE_A365_OBSERVABILITY_EXPORTER is een secundaire schakelaar die alleen werkt wanneer enable_a365=True in de code is ingesteld. U kunt deze ook aansturen via de a365_enable_observability_exporter-kwarg.

  • Controleer de configuratie van de tokenomzetter

    De exporter vereist een geldige tokenomzetter die voor elk exportverzoek een Bearer-token oplevert. Als de tokenomzetter ontbreekt of null teruggeeft, wordt de export stilzwijgend overgeslagen.

  • Schakel console-export in en controleer lokaal op telemetrie

    Voeg een console-exporter toe om te verifiëren dat telemetrie wordt gegenereerd voordat deze het Agent 365-eindpunt bereikt:

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Uitgebreid vastleggen inschakelen

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Controleer logboeken op exportfouten

    Gebruik het az webapp log tail-commando om logboeken te doorzoeken op fouten met betrekking tot waarneembaarheid.

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

Ontbrekende tenant-id of agent-id; spans overgeslagen

Symptomen: het systeem verwijdert spans zonder melding en exporteert ze nooit. Sommige platforms registreren een aantal overgeslagen spans of een bericht zoals No spans with tenant/agent identity found. Anderen verwijderen ze zonder dit te registreren.

Oplossing:

  • Voor export verdeelt de distro de spans op basis van tenant- en agentidentiteit. Spans die geen tenant-id of agent-id hebben, worden verwijderd en nooit naar de service gestuurd.
  • Zorg ervoor dat BaggageBuilder is ingesteld met de tenant-id en agent-id voordat u spans aanmaakt. Deze waarden worden doorgegeven via de OpenTelemetry-context en worden gekoppeld aan alle spans die binnen het bagage-bereik worden gecreëerd. Zie Bagagekenmerken voor de platformspecifieke API.
  • Als u baggage-middleware of de contexthelper uit het hostingintegratiepakket gebruikt, bevestig dan of de TurnContext-activiteit een geldige ontvanger met agentidentiteit heeft.

Tokenresolutiefout: export overgeslagen of ongeautoriseerd

Symptomen: de tokenomzetter geeft null weer of geeft een foutmelding. Afhankelijk van het platform wordt de export volledig overgeslagen of treedt er een HTTP 401-fout op.

Oplossing:

  • De tokenomzetter is vereist. Als deze ontbreekt, geeft de exporter bij het opstarten een foutmelding. Controleer of er een tokenomzetter aanwezig is en een geldige Bearer-token retourneert.
  • Zorg ervoor dat de juiste tenant-id en agent-id worden doorgegeven aan BaggageBuilder, want deze waarden worden doorgestuurd naar de tokenomzetter.
  • Voor door Azure gehoste agents controleert u of de Beheerde identiteit de vereiste API-toestemming heeft voor het waarneembaarheidsbereik.
  • Voor .NET-apps die het Agent Framework-hostingpakket gebruiken, wordt tokenuitwisseling automatisch afgehandeld via DI. Als tokens ontbreken, bevestig dan of Microsoft.Agents.A365.Observability.Hosting is geïnstalleerd en geregistreerd.

HTTP 401 Niet-geautoriseerd

Symptomen: exporteren met HTTP 401 mislukt. De exporter herhaalt de export niet na deze fout.

Oplossing:

  • Controleer of de tokendoelgroep overeenkomt met het bereik van het waarneembaarheidseindpunt.
  • Controleer of de tokenomzetter geen token van een gemachtigde gebruiker, een token voor een verkeerde doelgroep of een verlopen token teruggeeft.

HTTP 403 Verboden

Symptomen: exporteren met HTTP 403 mislukt. De exporter herhaalt de export niet na deze fout.

Hoofdoorzaak: een HTTP 403-fout kan verschillende oorzaken hebben. Bekijk de volgende oplossingen op volgorde.

Oplossing:

  • Ontbrekende licentie: controleer of uw tenant een van de volgende licenties toegewezen heeft gekregen in het Microsoft 365-beheercentrum:

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

  • Ontbrekende Agent365.Observability.OtelWrite-toestemming: Verleen de toestemming aan uw identiteit (Beheerde identiteit of app-registratie). Zonder deze toestemming mislukt de telemetrie-export met HTTP 403.

De machtiging verlenen

Gebruik een van deze opties:

  • Agent 365 CLI

    Hiervoor is een Globale beheerder-account vereist; voer het uit vanuit de agent-projectmap die a365.config.json bevat, of gebruik --agent-name.

    a365 setup permissions bot

    Of zonder configuratiebestand:

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

  • Entra Portal

    Geen configuratiebestanden nodig; vereist Globale beheerdertoegang tot de app-registratie van de blauwdruk.

    1. Ga naar Entra portal>App-registraties> selecteer uw Blueprint-app.
    2. Ga naar API-machtigingen>Machtiging toevoegen>API's die door mijn organisatie worden gebruikt> zoek naar 9b975845-388f-4429-889e-eab1ef63949c.
    3. Selecteer Gedelegeerde machtigingen>, controleer Agent365.Observability.OtelWrite>Machtigingen toevoegen.
    4. Herhaal stappen 2–3, selecteer deze keer Toepassingstoestemming> controleer Agent365.Observability.OtelWrite>Rechten toevoegen.
    5. Klik op Beheerderstoestemming verlenen en bevestig.

    Zowel Agent365.Observability.OtelWrite (Gedelegeerd) als Agent365.Observability.OtelWrite (Toepassing) hebben de status Granted.

HTTP 403 Verboden - Agent-id komt niet overeen

Symptomen: export mislukt met HTTP 403 en een serverbericht vergelijkbaar met 403 Forbidden, met agent-ID-mismatch-fouten bij het aanroepen van eindpunten van Agent 365 traceringen.

Hoofdoorzaak: deze fout treedt op als u de client-id van de blauwdruk gebruikt in plaats van de client-id van het agentexemplaar tijdens het instellen van de agentdetails. De agent-ID in de export-URL komt niet overeen met de door het token geverifieerde identiteit, waardoor het traceringeneindpunt het verzoek afwijst.

Oplossing:

  • Controleer of de tenant-id is opgenomen in de door Agent 365 toegestane tenantlijst.
  • Stel de agentgegevens in met de client-id van het agentexamplaar (niet de client-id van de blauwdruk).
  • Controleer de gegenereerde export-URL, deze wordt geregistreerd als u uw registratie inschakelt. Bevestig dat de agent-id in de URL overeenkomt met de client-id van de agentinstantie.
  • Zie Lokale validatie voor het inschakelen van diagnostische logboekregistratie per SDK.

HTTP 429 of 5xx-fouten - tijdelijke fouten

Symptomen: exporteren mislukt door een tijdelijke HTTP-statuscode zoals 429 of 5xx.

Oplossing:

  • Deze fouten zijn meestal tijdelijk en lossen vanzelf op. De Python- en JavaScript-distributies proberen automatisch opnieuw HTTP-statuscodes 408, 429 en 5xx. De .NET-distro probeert het niet automatisch opnieuw.
  • Als er fouten blijven optreden, controleert u het servicestatusdashboard van de service.
  • Overweeg om de exportfrequentie te verlagen door de geplande vertraging tussen batches te verhogen of de maximale exportbatchgrootte te vergroten. Gebruik voor Python en JavaScript de relevante exporterOptions- of a365_*-parameters die in de GitHub-opslagplaatsen zijn gedocumenteerd. Gebruik voor .NET o.Agent365.Exporter.ScheduledDelayMilliseconds en o.Agent365.Exporter.MaxExportBatchSize.

Exporttime-out

Symptomen: exportpogingen lopen vast door time-out.

Oplossing:

  • Controleer de netwerkconnectiviteit naar het waarneembaarheidseindpunt.

  • De standaard time-out voor HTTP-verzoeken is 30 seconden op alle platforms. Als time-outs vaak voorkomen, verhoogt u de time-outwaarde in de exporteropties:

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

    Zie de Python-opslagplaats voor de volledige lijst met a365_*-opties.

Export slaagt, maar telemetrie verschijnt niet in Defender of Purview

Symptomen: logboeken tonen een succesvolle export (HTTP 200), maar telemetrie is niet zichtbaar in Microsoft Defender of Microsoft Purview.

Oplossing:

  • Controleer of u voldoet aan de vereisten om geëxporteerde logboeken te bekijken:
  • Telemetrie kan enkele minuten duren voordat dit zichtbaar wordt na een succesvolle export. Wacht voordat u verder onderzoek doet.
  • Controleer of spans de geldige kenmerken microsoft.tenant.id en gen_ai.agent.id bevatten. Ontbrekende identiteitskenmerken zorgen ervoor dat spans aan de serverzijde worden genegeerd, zelfs als de HTTP-export een statuscode 200 retourneert.

Gerelateerde inhoud

  • Last updated on