Microsoft OpenTelemetry Distro

Microsoft OpenTelemetry Distro er en enhetlig distribusjon for observerbarhet som gir en felles pålastingsopplevelse for innsamling av spor, målinger og logger fra apper med eller uten agent. Den støtter observerbarhet for Microsoft Agent 365, Microsoft Foundry, Azure Monitor og alle OTLP-kompatible serverdeler (OpenTelemetry Protocol). Distroen støtter .NET, Node.js og Python og erstatter fragmentert oppsett på tvers av flere observerbarhetsstakker med én import og ett konfigurasjonskall.

Hovedfordeler

Microsoft OpenTelemetry Distro gir disse fordelene:

  • Én pakke, ett API: Erstatt flere eksportør- og instrumenteringspakker med én enkelt avhengighet.
  • Støtte for flere serverdeler: Send telemetri til Azure Monitor, ethvert OpenTelemetry Protocol (OTLP)-kompatibelt endepunkt som Datadog, Grafana eller New Relic og Microsoft Agent 365 samtidig.
  • Innebygde instrumenteringer: Bruk automatisk instrumentering for HTTP, databaser, Azure SDK, Azure Functions og mer uten ekstra konfigurasjon.
  • Standardbasert: Bygg på OpenTelemetry, bransjestandard observerbarhetsrammeverket.
  • Minimal standardtekst: Legg til én import og ett funksjonskall til appens inngangspunkt.

Installasjon og konfigurasjon

Denne veiledningen viser hvordan du legger til observerbarhet i appen med Microsoft OpenTelemetry Distro. Distro samler automatisk inn sporingsdata, måledata og logger med innebygd instrumentering og eksporterer telemetrien til Azure Monitor, et hvilket som helst OpenTelemetry Protocol (OTLP)-endepunkt eller Microsoft Agent 365.

Installer bibliotek

For å komme i gang med Microsoft OpenTelemetry Distro må du installere det riktige biblioteket for utviklingsplattformen din ved å bruke språkets pakkebehandler.

Forutsetninger: Python 3.10 eller nyere.

pip install microsoft-opentelemetry

Konfigurasjon

Agent 365-eksportøren bruker ikke en tilkoblingsstreng. Den oppdager sitt endepunkt automatisk basert på leietaker. For å aktivere eksport til Agent 365 setter du eksportørmålet og legger til en tokenløser som returnerer et tilgangstoken for en gitt agent-ID og leietaker-ID.

Kall use_microsoft_opentelemetry() for å aktivere observerbarhet.

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

Hvis du ønsker egendefinert tokenløsing (i stedet for standard tokenløser), kan du se Manuell tokenløser.

Du kan tilpasse eksportørens atferd ved å sende inn valgfrie a365_*-kwarger til use_microsoft_opentelemetry().

Parameter Description Standard
a365_use_s2s_endpoint Når True brukes tjeneste-til-tjeneste-endepunktbanen. False
a365_max_queue_size Maksimal køstørrelse for partiprosessoren. 2048
a365_scheduled_delay_ms Forsinkelse i millisekunder mellom eksportpartiene. 5000
a365_exporter_timeout_ms Tidsavbrudd i millisekunder for eksportoperasjonen. 30000
a365_max_export_batch_size Maksimal partistørrelse for eksportoperasjoner. 512

Overfør kontekst

For å opprettholde observerbarhet på tvers av distribuerte Agent 365-operasjoner må du overføre kontekst. Når du overfører kontekst gjennom agentene og tjenestene dine, sikrer du at spor, logger og måledata er riktig korrelert gjennom hele forespørselslivssyklusen. Denne korrelasjonen er nødvendig for en komplett og effektiv overvåkingsopplevelse med Microsoft Agent 365.

Bagasjeattributter

Bruk BaggageBuilder til å angi kontekstuell informasjon som følger alle strekk i en forespørsel. SDK-en implementerer en SpanProcessor som kopierer alle ikke-tomme bagasjeoppføringer til nylig opprettede strekk uten å overskrive eksisterende attributter.

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

For å fylle ut BaggageBuilder automatisk fra TurnContext bruker du populate-hjelperen i microsoft-opentelemetry-pakken. Denne hjelperen henter automatisk ut detaljer om kaller, agent, leietaker, kanal og samtale fra aktiviteten.

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

Bagasjemellomvare

Hvis agenten din bruker vertsintegrasjonspakken, registrerer du bagasjemellomvare for automatisk å fylle ut bagasje for hver innkommende forespørsel. Dette trinnet fjerner behovet for å kalle BaggageBuilder manuelt i hver aktivitetsbehandlingsprogram.

I Python registrerer du bagasjemellomvare via ObservabilityHostingManager.configure() i stedet for direkte på adapteren.

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

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

Mellomvaren unngår å sette bagasje for asynkrone svar (ContinueConversation-hendelser) for å unngå å overskrive bagasje som den opprinnelige forespørselen allerede har satt.

Kontroller at data flyter i produktet

For å se agenttelemetri i Microsoft Purview eller Microsoft Defender må du sørge for at følgende krav er oppfylt:

Automatisk instrumentering

Microsoft OpenTelemetry Distro kombinerer standard OpenTelemetry-rørledninger med Microsoft-kuratert instrumentering. Distro kan samle apptelemetri, infrastrukturtelemetri og agenttelemetri eller telemetri for generativ kunstig intelligens avhengig av språk og konfigurasjon.

Kategori Hva den dekker
Signalrørledninger Spor, måledata og logger.
Ressursgjenkjenning Service-, vert-, sky- og Azure-kjøretidskontekst ble støttet.
Infrastrukturinstrumentering HTTP, ASP.NET Core, Azure SDK, databaseklienter og loggrammeverk der det støttes.
Instrumentering for generativ kunstig intelligens OpenAI, Azure OpenAI, Semantic Kernel, LangChain, OpenAI Agents SDK og Agent Framework der det støttes.
Manuelle agentomfang Agentaktivering, verktøyutførelse, inferens og utdatatelemetri der det støttes.
Eksportører og prosessorer Azure Monitor, Microsoft Agent 365, OTLP, konsollutgang, strekkprosessorer, loggprosessorer og måledatalesere.

Instrumenteringsdekning

Språk Felles appinstrumentering Felles instrumentering for agent og generativ kunstig intelligens
Python OpenTelemetry-ressurser, prosessorer, lesere, logging, måledata og spor. Semantic Kernel, OpenAI Agents SDK, Agent Framework, LangChain, Microsoft Agent 365-bagasje og Microsoft Agent 365-omfang.
Node.js HTTP, Azure SDK, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis, Bunyan og Winston. OpenAI Agents SDK, LangChain, Microsoft Agent 365-bagasje og Microsoft Agent 365-omfang.
.NET ASP.NET Core, HttpClient, SQL-klient, Azure SDK, ressursgjenkjenning, måledata og logger. Semantic Kernel, OpenAI og Azure OpenAI, Agent Framework, Microsoft Agent 365-bagasje og Microsoft Agent 365-omfang.

Automatisk instrumentering lytter til telemetrisignaler som sendes ut av støttede biblioteker og rammeverk. Manuell instrumentering benyttes når en app må beskrive agentspesifikke operasjoner, slik som aktivering, verktøyutførelse, inferens eller asynkron respons.

Legg til tilpassede OpenTelemetry-kilder, målere, prosessorer eller lesere når appen sender ut telemetri som ikke dekkes av de innebygde instrumenteringene.

Viktig!

Automatisk instrumentering overfører bare standard OpenTelemetry-attributter. Den inkluderer ikke alle attributter som Agent 365 krever. Du må legge til Microsoft-spesifikke attributter gjennom BaggageBuilder. For å se hvilke attributter som kreves, kan du se Lagre valideringsattributter.

Innebygde instrumenteringsbiblioteker

Automatisk instrumentering lytter til telemetri sendt ut av støttede rammeverk og sender det videre gjennom Distros OpenTelemetry-rørledning. I agentscenarioer bør du angi bagasje som leietaker-ID og agent-ID før det instrumenterte rammeverket oppretter strekk.

Rammeverk Python Node.js .NET
Semantic Kernel Støttes Støttes ikke Støttes
OpenAI og OpenAI Agents SDK Støttes Støttes Støttes
Agent Framework Støttes Støttes ikke Støttes
LangChain Støttes Støttes Ikke oppført

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

Manuell instrumentering

Bruk manuell instrumentering når automatisk instrumentering ikke beskriver agentens operasjon med nok detaljer. Manuelle omfang gjør det mulig for en app å beskrive vanlige agentaktiviteter på en konsekvent måte på tvers av språk.

Område Bruk for
InvokeAgentScope Starten og fullføringen av en agentaktivering.
ExecuteToolScope Et verktøykall gjort av en agent.
InferenceScope En inferensprosess fra en modell for kunstig intelligens.
OutputScope Utgang som må registreres etter at det opprinnelige omfanget allerede er fullført.

Gjenbruk de samme forespørsels- og agentidentitetsverdiene i alle omfang innenfor en forespørsel, slik at tilknyttet telemetri kan korreleres.

Agentaktivering

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

Verktøykjøring

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)

Inferens

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

Produktdokumentasjon bør definere eventuelle produktspesifikke valideringskrav for disse omfangene.

Lokal validering

Lokal validering bekrefter at appen produserer telemetri før en produktspesifikk destinasjon valideres. Bruk konsollutgang eller et lokalt OTLP-endepunkt for å kontrollere at spor, måledata og logger blir generert.

Valider med et lokalt OTLP-endepunkt

Konfigurer Distro til å sende telemetri til en lokal samler eller et annet OTLP-kompatibelt endepunkt.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Valider med lokal utdata

Bruk lokal utdata når du vil bekrefte instrumenteringen før du sender telemetri til et eksternt mål.

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.

Gå gjennom de lokale utdataene for strekk fra forventede kilder, som HTTP-forespørsler, OpenAI- eller Azure OpenAI-kall, agentaktiveringsomfang, verktøyeksekveringsomfang eller inferensomfang. Destinasjonsspesifikk validering hører hjemme i produktdokumentasjonen for den destinasjonen.

Konfigurer godkjenning manuelt

Når du bruker Agent 365-eksportøren, må du sørge for en mekanisme for å levere et autentiseringstoken. Tokenløseren opererer for hvert eksportparti og benytter agent-ID og leietaker-ID fra den aktive bagasjekonteksten. Distribusjonen støtter to tilnærminger.

Tips

Hvis du utvikler agenter med SDK for Microsoft 365-agenter, kan du se Observerbarhetsgodkjenningskonfigurasjon for Agent SDK for trinnvise instruksjoner om oppsett av OBO- og S2S-tokeninnhenting for både agentbaserte og ikke-agentbaserte agenter.

Manuell tokenløser

Bruk en manuell løser når du henter tokener utenfor Agent Framework-rørledningen, når du utvikler apper som ikke bruker Agent Framework, eller når du benytter service-til-service-autentisering (S2S) (klientlegitimasjonsflyt). Agenter kan generere et token selv, for eksempel ved å bruke Microsoft Authentication Library (MSAL) eller en annen metode for tokeninnhenting, men de må sørge for at tokenet har riktig observerbarhetsomfang (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite).

Notat

For tjeneste-til-tjeneste-autentisering (S2S) må du bruke denne manuelle tokenløsertilnærmingen. Agentisk tokenbuffer støtter bare på-vegne-av-autentiseringsflyter (OBO).

De følgende eksemplene illustrerer tokenløsermønsteret OBO (på-vegne-av) – agenten henter et brukertoken via det agentiske autentiseringsbehandlingsprogram og bytter den mot et token med observerbarhetsomfang. For S2S-eksempler (tjeneste-til-tjeneste) og en sammenligning av OBO-autentisering kontra S2S-autentisering kan du se Observerbarhetsautentiseringskonfigurasjon for Agent SDK.

Løseren må være synkron. Hent tokenet i det asynkrone aktivitetsbehandlingsprogrammet (eller via MSAL) og lagre det for løseren.

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

Agentisk tokenbuffer med Agent Framework-apper

For Agent Framework-apper som bruker på-vegne-av-autentisering (OBO), registrerer distro automatisk IExporterTokenCache<AgenticTokenStruct> via DI når du ikke angir en egendefinert TokenResolver. Agenten kaller RegisterObservability() ved kjøretid for å levere legitimasjonsinformasjon, og bufferen håndterer tokeninnhenting og -oppdatering.

Notat

Denne tilnærmingen støtter bare OBO-autentiseringsflyter (på-vegne-av). For tjeneste-til-tjeneste-autentisering (S2S) bruker du den manuelle tokenløseren i stedet.

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

Lagre valideringsattributter

For vellykket lagringsvalidering må agenten din implementere InvokeAgentScope, InferenceScope og ExecuteToolScope. Hvert omfang tilsvarer en strekk operasjon i det kanoniske skjemaet:

SDK-omfang Strekkoperasjon Universell referansekode
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

For fullstendige per-område-nødvendige-lister og valgfrie attributtlister – inkludert per-attributtsemantikk, veiledning for verdiplukking og hvilke attributter som kan spørres gjennom Microsoft Defender avansert jakt – se Agent 365-observerbarhetsattributtreferanse. Kolonnen Gjelder angir hvilket omfang hvert attributt tilhører, og kolonnen Obligatorisk skiller obligatoriske (M) fra valgfrie (O) attributter.

Test agenten din med observerbarhet

Etter å ha implementert observerbarhet, verifiser du at telemetri fanges opp:

  1. Gå til https://admin.cloud.microsoft/#/agents/all.
  2. Velg agenten din og deretter Aktivitet.
  3. Verifiser at økter og verktøykall vises.

Eksempelapper og avansert konfigurasjon

For eksempelapper og avanserte konfigurasjonsalternativer kan du se GitHub-repositoriene for hvert språk:

Feilsøking

Denne delen beskriver vanlige problemer ved implementering og bruk av Microsoft OpenTelemetry Distro med Agent 365.

Problem Description
Observerbarhetsdata vises ikke Ingen telemetri er synlig fordi Agent 365-eksport ikke er aktivert, oppsettet er ufullstendig eller tokenoppløsningen mislykkes.
Manglende leier-ID eller agent-ID – strekk hoppes over Strekk filtreres ut før eksport når nødvendige leietaker- eller agentidentitetsattributter mangler.
Tokenoppløsningsfeil – eksport hoppet over eller uautorisert Eksport utelates eller avvises når tokenløseren ikke returnerer et token eller det oppstår feil under innhenting av token.
HTTP 401 Uautorisert Forespørsler når tjenesten, men autentiseringen mislykkes fordi tokenet er ugyldig, utløpt eller tilhører feil målgruppe.
HTTP 403 Ikke tillatt Autorisasjon feiler på grunn av manglende leietakerlisenser eller manglende skrivetillatelser for observerbarhet.
HTTP 403 Forbudt – Agent-ID-konflikt Tjenesten avviser eksport når agent-ID-en i forespørselen ikke samsvarer med tokenautorisert agentidentitet.
HTTP 429 eller 5xx-feil – Midlertidige feil Midlertidig begrensing eller ustabilitet i serverdel avbryter eksport og kan kreve nye forsøk eller partijustering.
Eksporttidsavbrudd Eksportoperasjoner overskrider tidsavbruddsgrenser på grunn av nettverksforsinkelser eller endepunktsvarforsinkelse.
Eksport lykkes, men telemetri vises ikke i Defender eller Purview Datainntak lykkes, men synligheten blir forsinket eller blokkert av forutsetninger og skjemakrav.

Tips

Feilsøkingsveiledning for Agent 365 inneholder anbefalinger på høyt nivå for feilsøking, anbefalte fremgangsmåter og koblinger til feilsøkingsinnhold for hver fase i utviklingssyklusen i Agent 365.

Observerbarhetsdata vises ikke

Symptomer:

  • Agenten kjører
  • Ingen telemetri i administrasjonssenteret
  • Kan ikke se agentaktivitet

Rotårsak:

  • Agent 365-eksport er ikke aktivert
  • Konfigurasjonsfeil
  • Tokenløserproblemer

Løsninger: Prøv følgende trinn for å løse problemet:

  • Verifiser at Agent 365-eksport er aktivert

    Du må eksplisitt aktivere Agent 365-eksporten. Hvis du ikke setter det, kan distro falle tilbake til eksport til konsoll eller ikke eksportere noe. Aktiver det i koden:

    from microsoft.opentelemetry import use_microsoft_opentelemetry

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

    Eller angi miljøvariabelen:

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    Notat

    ENABLE_A365_OBSERVABILITY_EXPORTER er en sekundær bryter som bare trer i kraft når enable_a365=True er satt i koden. Du kan også kontrollere den via a365_enable_observability_exporter-kwarg.

  • Sjekk konfigurasjonen for tokenløser

    Eksportøren krever en gyldig tokenløser som returnerer en bærertoken for hver eksportforespørsel. Hvis tokenløseren mangler eller returnerer null, blir eksporten hoppet over uten varsel.

  • Aktiver konsolleksport og kontroller telemetri lokalt

    Legg til en konsolleksportør for å kontrollere at telemetri genereres før den når Agent 365-endepunktet:

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Aktiver detaljert logging

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Sjekk logger for eksportfeil

    Bruk az webapp log tail-kommandoen til å søke i logger etter feil relatert til observerbarhet:

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

Manglende leier-ID eller agent-ID – strekk hoppet over

Symptomer: Systemet senker stille strekk og eksporterer dem aldri. Noen plattformer logger et antall strekk som er hoppet over, eller en melding som No spans with tenant/agent identity found. Andre fjerner dem uten å logge det.

Løsning.

  • Før eksport partisjonerer distroen strekk etter leietaker- og agentidentitet. Strekk som mangler enten en leier-ID eller agent-ID, blir fjernet og aldri sendt til tjenesten.
  • Sørg for at BaggageBuilder er satt opp med leietaker-ID og agent-ID før du oppretter strekk. Disse verdiene videreføres gjennom OpenTelemetry-konteksten og legges til alle strekk som opprettes innenfor bagasjeomfanget. For den plattformspesifikke API-en kan du se Bagasjeattributter.
  • Hvis du bruker bagasjemellomvaren eller omgangskonteksthjelperen fra vertsintegrasjonspakken, må du bekrefte at TurnContext-aktiviteten har en gyldig mottaker med agentidentitet.

Tokenoppløsningsfeil – eksport utelatt eller uautorisert

Symptomer: Tokenløseren returnerer null eller kaster en feil. Avhengig av plattformen hoppes eksporten enten helt over eller feiler med HTTP 401.

Løsning.

  • Tokenløseren er nødvendig. Hvis det mangler, gir eksportøren en feilmelding ved oppstart. Kontroller at en tokenløser er oppgitt og returnerer et gyldig bærertoken.
  • Sørg for at riktig leietaker-ID og agent-ID sendes til BaggageBuilder, fordi disse verdiene videresendes til tokenløseren.
  • For Azure-baserte agenter må du sørge for at administrert identitet har de nødvendige API-rettighetene for observerbarhetsomfanget.
  • For .NET-apper som bruker Agent Framework-vertspakken håndteres tokenutveksling automatisk via DI. Hvis tokenene mangler, bekrefter du at Microsoft.Agents.A365.Observability.Hosting er installert og registrert.

HTTP 401 Uautorisert

Symptomer: Eksport mislykkes med HTTP 401. Eksportøren forsøker ikke på nytt ved denne feilen.

Løsning.

  • Verifiser at tokenmålgruppen samsvarer med observerbarhetsendepunktets omfang.
  • Sjekk at tokenløseren ikke returnerer en delegert brukertoken, et token for feil målgruppe eller et utløpt token.

HTTP 403 Ikke tillatt

Symptomer: Eksport mislykkes med HTTP 403. Eksportøren forsøker ikke på nytt ved denne feilen.

Rotårsak: En HTTP 403-feil kan ha ulike årsaker. Sjekk følgende løsninger i rekkefølge.

Løsning.

  • Manglende lisens – Kontroller at leietakeren din har én av følgende lisenser tildelt i Administrasjonssenteret for Microsoft 365:

    • Test – Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Agent 365 Frontier

  • Manglende Agent365.Observability.OtelWrite-tillatelse – Tildel tillatelsen til identiteten (administrert identitet eller appregistrering). Uten denne tillatelsen mislykkes eksport av telemetri med HTTP 403.

Gi tillatelsene

Bruk et av disse alternativene:

  • Agent 365 CLI

    Krever en global administratorkonto. Kjør fra mappen for agentprosjektet som inneholder a365.config.json eller bruk --agent-name.

    a365 setup permissions bot

    Eller uten konfigurasjonsfil:

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

  • Entra Portal

    Ingen konfigurasjonsfiler kreves. Krever global administratortilgang til blåkopiappregistreringen.

    1. Gå til Entra Portal>Appregistreringer> velg blåkopiappen.
    2. Gå til API-tillatelser>Legg til en tillatelse>API-er organisasjonen min bruker> søk etter 9b975845-388f-4429-889e-eab1ef63949c.
    3. Velg Delegerte tillatelser>, merk av Agent365.Observability.OtelWrite>Legg til tillatelser.
    4. Gjenta trinn 2–3, denne gangen velg Apptillatelser>, kryss av Agent365.Observability.OtelWrite>Legg til tillatelser.
    5. Klikk på Gi administratorsamtykke og bekreft.

    Både Agent365.Observability.OtelWrite (delegert) og Agent365.Observability.OtelWrite (app) viser Granted-status.

HTTP 403 Forbudt – Agent-ID-konflikt

Symptomer: Eksporten mislykkes med HTTP 403 og en servermelding som ligner på 403 Forbidden med agent-ID-mismatch-feil ved kall til Agent 365-sporendepunkter.

Rotårsak: Denne feilen oppstår når du bruker blåkopiklient-ID-en i stedet for klient-ID-en til agentforekomsten når du konfigurerer agentdetaljene. Agent-ID-en i eksportnettadressen samsvarer ikke med identiteten autorisert av tokenet, så sporendepunktet avviser forespørselen.

Løsning.

  • Verifiser at leietaker-ID-en er lagt til i listen over tillatte leietakere for Agent 365.
  • Konfigurer agentdetaljene med klient-ID-en til agentforekomst (ikke blåkopiklient-ID-en).
  • Verifiser eksportnettadressen som genereres – den logges hvis logging er aktivert. Bekreft at agent-ID-en i nettadressen samsvarer med agentforekomstens klient-ID.
  • For å aktivere diagnostisk logging per SDK kan du se Lokal validering.

HTTP 429 eller 5xx-feil – Midlertidige feil

Symptomer: Eksport feiler med en midlertidig HTTP-statuskode som 429 eller 5xx.

Løsning.

  • Disse feilene er vanligvis forbigående og løser seg av seg selv. Python- og JavaScript-distribusjonene prøver automatisk på nytt på HTTP 408, 429 og 5xx-statuskoder. .NET-distribusjonen prøver ikke automatisk på nytt.
  • Hvis feilene vedvarer, sjekker du tjenestetilstandsinstrumentbordet.
  • Vurder å redusere eksportfrekvensen ved å øke det planlagte intervallet mellom partier eller den maksimale eksportpartistørrelsen. For Python og JavaScript bruker du de relevante exporterOptions- eller a365_*-parameterne som er dokumentert i GitHub-repositorier. For .NET bruker du o.Agent365.Exporter.ScheduledDelayMilliseconds og o.Agent365.Exporter.MaxExportBatchSize.

Eksporttidsavbrudd

Symptomer: Eksportforsøk har tidsavbrudd.

Løsning.

  • Kontroller nettverkstilkoblingen til observerbarhetsendepunktet.

  • Standard HTTP-tidsavbrudd er 30 sekunder på alle plattformer. Hvis tidsavbrudd oppstår ofte, øker du tidsavbruddsverdien i eksporteringsalternativene:

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

    Se Python-repositoriet for hele listen over a365_*-alternativer.

Eksport lykkes, men telemetri vises ikke i Defender eller Purview

Symptomer: Loggene viser en vellykket eksport (HTTP 200), men telemetri er ikke synlig i Microsoft Defender eller Microsoft Purview.

Løsning.

  • Kontroller at du oppfyller kravene for å se eksporterte logger:
  • Det kan ta flere minutter før telemetridata blir tilgjengelig etter en vellykket eksport. Vent med å undersøke nærmere.
  • Verifiser at strekk inneholder gyldige microsoft.tenant.id- og gen_ai.agent.id-attributter. Manglende identitetsattributter fører til at strekk forkastes på serversiden selv om HTTP-eksporten returnerer 200.

Relatert innhold

  • Last updated on