Microsoft OpenTelemetry Distro

Microsoft OpenTelemetry Distro je jednotná distribuce pozorovatelnosti, která poskytuje jednotný způsob nasazení pro sběr stop, metrik a logů z agentických i neagentických aplikací. Podporuje pozorovatelnost pro Microsoft Agent 365, Microsoft Foundry, Azure Monitor a jakýkoli backend kompatibilní s OpenTelemetry Protocol (OTLP). Distribuce podporuje .NET, Node.js a Python a nahrazuje roztříštěné nastavení napříč různými platformami pozorovatelnosti jedním importem a jedním konfiguračním voláním.

Klíčové výhody

Microsoft OpenTelemetry Distro poskytuje tyto výhody:

  • Jeden balíček, jedno API: Nahraďte více balíčků pro export a instrumentaci jedinou závislostí.
  • Podpora více back-endů: Posílejte telemetrii do služby Azure Monitor, do libovolného koncového bodu kompatibilního s protokolem OpenTelemetry Protocol (OTLP), jako je Datadog, Grafana nebo New Relic, a zároveň do služby Microsoft Agent 365.
  • Vestavěné instrumentace: Použijte automatickou instrumentaci pro HTTP, databáze, Azure SDK, Azure Functions a další bez nutnosti další konfigurace.
  • Založený na standardech: Staví na OpenTelemetry, průmyslovém standardu pro pozorovatelnost.
  • Minimální boilerplate: Přidejte jeden import a jedno volání funkce do vstupního bodu aplikace.

Instalace a konfigurace

Tato příručka vám ukáže, jak přidat pozorovatelnost do vaší aplikace pomocí Microsoft OpenTelemetry Distro. Distro automaticky shromažďuje trasování, metriky a logy pomocí vestavěné instrumentace a exportuje telemetrii do Azure Monitor, libovolného OTLP endpointu nebo Microsoft Agent 365.

Nainstalujte knihovnu

Chcete-li začít používat Microsoft OpenTelemetry Distro, nainstalujte odpovídající knihovnu pro vaši vývojovou platformu pomocí správce balíčků vašeho jazyka.

Předpoklady: Python 3.10 nebo novější.

pip install microsoft-opentelemetry

Konfigurace

Exportér Agent 365 nepoužívá připojovací řetězec. Exportér automaticky zjistí svůj koncový bod podle klienta. Pro umožnění exportu do Agent 365 nastavte cíl exportéru a implementujte tokenový resolver, který vrací přístupový token pro dané ID agenta a ID klienta.

Volání use_microsoft_opentelemetry() pro povolení pozorovatelnosti.

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

Pro vlastní rozlišení tokenů (místo výchozího překladače tokenů) viz Manuální překladač tokenů.

Chování exportéru můžete upravit předáním volitelných kwargs a365_* do use_microsoft_opentelemetry().

Parametr Popis Výchozí
a365_use_s2s_endpoint Při True se používá cesta koncového bodu pro komunikaci mezi službami. False
a365_max_queue_size Maximální velikost fronty pro dávkový procesor. 2048
a365_scheduled_delay_ms Zpoždění v milisekundách mezi dávkami exportů. 5000
a365_exporter_timeout_ms Časový limit v milisekundách pro exportní operaci. 30000
a365_max_export_batch_size Maximální velikost dávky pro exportní operace. 512

Propagujte kontext

Pro zachování pozorovatelnosti napříč distribuovanými operacemi Agent 365 propagujte kontext. Když propagujete kontext přes své agenty a služby, zajistíte, že stopy, logy a metriky jsou správně korelovány napříč celým životním cyklem požadavku. Tato korelace je nezbytná pro plnohodnotné a efektivní sledování Microsoft Agent 365.

Atributy baggage

Použijte BaggageBuilder k nastavení kontextových informací, které procházejí všemi spany v požadavku. SDK implementuje objekt SpanProcessor, který kopíruje všechny neprázdné položky baggage do nově spuštěných spanů, aniž by přepisoval existující atributy.

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

Chcete-li automaticky naplnit BaggageBuilder z TurnContext, použijte pomocníka populate v balíčku microsoft-opentelemetry. Tento pomocník automaticky extrahuje podrobnosti o volajícím, agentovi, klientovi, kanálu a konverzaci z aktivity.

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

Middleware pro baggage

Pokud váš agent používá integrační balíček pro hosting, zaregistrujte baggage middleware, aby se baggage automaticky doplňovala pro každý příchozí požadavek. Tento krok odstraňuje potřebu manuálně volat BaggageBuilder v každé obslužné funkci aktivit.

V Pythonu registrujte baggage middleware pomocí ObservabilityHostingManager.configure() namísto přímého přidání na adaptér.

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

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

Middleware přeskočí nastavení baggage pro asynchronní odpovědi (události typu ContinueConversation), aby nedošlo k přepsání baggage, kterou již původní požadavek nastavil.

Ověřte, že data proudí v produktu

Pro zobrazení telemetrie agentů v Microsoft Purview nebo Microsoft Defender se ujistěte, že jsou splněny následující požadavky:

Automatická instrumentace

Microsoft OpenTelemetry distribuce kombinuje standardní kanály OpenTelemetry s instrumentací spravovanou Microsoftem. Distribuce může shromažďovat aplikační telemetrii, infrastrukturní telemetrii a telemetrii agentů nebo generativní AI v závislosti na jazyce a konfiguraci.

Kategorie Co pokrývá
Kanály signálů Trasování, metriky a protokoly.
Detekce zdrojů Kontext běhového prostředí služby, hostitele, cloudu a Azure (pokud je podporováno).
Infrastrukturní instrumentace HTTP, ASP.NET Core, Azure SDK, databázoví klienti a logovací architektury tam, kde jsou podporovány.
Instrumentace generativní AI OpenAI, Azure OpenAI, Sémantické jádro, LangChain, OpenAI Agents SDK a Agent Framework tam, kde jsou podporovány.
Manuální rozsahy agenta Volání agenta, provádění nástrojů, inference a výstupní telemetrie, kde jsou podporovány.
Exportéry a procesory Azure Monitor, Microsoft Agent 365, OTLP, konzolový výstup, procesory spanů, procesory logů a čtečky metrik.

Pokrytí instrumentace

Jazyk Instrumentace běžných aplikací Instrumentace pro běžné agenty a generativní AI
Python Prostředky, procesory, čtenáři, protokolování, metriky a trasování v OpenTelemetry. Sémantické jádro, OpenAI Agents SDK, Agent Framework, LangChain, Microsoft Agent 365 baggage a Microsoft Agent 365 scopes.
Node.js HTTP, Azure SDK, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis, Bunyan a Winston. Sada OpenAI Agents SDK, LangChain, Microsoft Agent 365 baggage a rozsahy Microsoft Agent 365.
.NET ASP.NET Core, HttpClient, SQL Client, Azure SDK, detekce zdrojů, metriky a logy. Sémantické jádro, OpenAI a Azure OpenAI, Agent Framework, Microsoft Agent 365 baggage a rozsahy Microsoft Agent 365.

Automatická instrumentace naslouchá telemetrickým signálům vysílaným podporovanými knihovnami a frameworky. Manuální instrumentace se používá, když aplikace potřebuje popsat operace specifické pro agenta, jako je volání, spouštění nástrojů, inference nebo asynchronní výstup.

Přidejte vlastní OpenTelemetry zdroje, měřiče, procesory nebo čtečky, když vaše aplikace generuje telemetrii, která není pokryta vestavěnými instrumentacemi.

Důležité

Automatická instrumentace vyplňuje pouze standardní atributy OpenTelemetry. Nezahrnuje všechny atributy, které Agent 365 vyžaduje. Musíte přidat atributy specifické pro Microsoft pomocí BaggageBuilder. Chcete-li zjistit, které atributy jsou požadovány, viz Validační atributy obchodu.

Vestavěné knihovny přístrojů

Autoinstrumentace naslouchá telemetrii emitované podporovanými frameworky a předává ji prostřednictvím OpenTelemetry pipeline distribuce. U agentních scénářů nastavte baggage, například klient ID a agent ID, předtím, než instrumentovaný framework vytvoří spany.

Framework Python Node.js .NET
Sémantické jádro Podporováno Nepodporováno Podporováno
OpenAI a OpenAI Agents SDK Podporováno Podporováno Podporováno
Agent Framework Podporováno Nepodporováno Podporováno
LangChain Podporováno Podporováno Není uvedený

Sémantické jádro

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

Poznámka

Autoinstrumentace pro rámec LangChain také podporuje LangGraph a Deep Agents. Stejná instrumentace automaticky zachycuje telemetrii pro agenty vytvořené v kterémkoli z těchto rámců.

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

Manuální instrumentace

Pokud automatické instrumentování nepopisuje činnost agenta s dostatečnými podrobnostmi, použijte ruční instrumentování. Manuální rozsahy umožňují aplikaci popisovat běžné aktivity agentů konzistentním způsobem napříč jazyky.

Rozsah Používejte pro
InvokeAgentScope Začátek a dokončení vyvolání agenta.
ExecuteToolScope Volání nástroje agentem
InferenceScope Operace inferování AI modelu.
OutputScope Výstup, který musí být zaznamenán poté, co již dokončil původní rozsah.

Znovu použijte stejné hodnoty identity požadavku a agenta napříč rozsahy v požadavku, aby bylo možné korelovat související telemetrii.

Volání agenta

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

Spuštění nástroje

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)

Odvozování

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

Výstup

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

Produktová dokumentace by měla stanovit produktově specifické požadavky na ověření pro tyto oblasti.

Místní validace

Lokální ověření potvrzuje, že aplikace vytváří telemetrii před ověřením cíle specifické pro produkt. Použijte konzolový výstup nebo lokální OTLP endpoint pro ověření, že jsou vytvářeny stopy, metriky a protokoly.

Ověřte pomocí lokálního OTLP koncového bodu

Nakonfigurujte distribuci tak, aby odesílala telemetrii do místního kolektoru nebo jiného OTLP-kompatibilního koncového bodu.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Ověřte pomocí lokálního výstupu

Použijte lokální výstup, když chcete ověřit instrumentaci před odesláním telemetrie do vzdáleného cíle.

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.

Zkontrolujte lokální výstup pro spany z očekávaných zdrojů, jako jsou HTTP požadavky, volání OpenAI nebo Azure OpenAI, scope vyvolání agenta, scope spuštění nástroje nebo scope inference. Ověření specifické pro destinaci patří do dokumentace produktu pro tuto destinaci.

Ruční nastavení ověřování

Když používáte exportér Agent 365, musíte implementovat mechanismus pro zadání autentizačního tokenu. Token resolver pracuje pro každou exportní dávku tím, že používá agent ID a klient ID z aktivního baggage kontextu. Distribuce OpenTelemetry podporuje dva přístupy.

Zpropitné

Pokud vytváříte agenty pomocí Sada SDK pro agenty Microsoft 365, podívejte se na Nastavení autentizace pro observabilitu pro Agent SDK, kde najdete podrobný postup konfigurace získávání tokenů OBO a S2S pro agentické i neagentické agenty.

Manuální resolver tokenů

Manuální resolver použijte, když získáváte tokeny mimo pipeline Agent Framework, při tvorbě neagentních aplikací nebo při použití service-to-service (S2S) autentizace (client credentials flow). Agenti si mohou token vygenerovat sami, například pomocí Identity a ověřování Microsoftu (MSAL) nebo jiné metody získávání tokenů, ale musí ověřit, že token má správný api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWriterozsah pozorovatelnosti.

Poznámka

Pro autentizaci mezi službami (S2S) musíte použít tento manuální tokenový resolver. Agentická cache tokenů podporuje pouze autentizační procesy typu on-behalf-of (OBO).

Následující příklady demonstrují pattern překladače tokenů OBO (on-behalf-of) — agent získá uživatelský token pomocí agentického autentizačního handleru a vymění ho za token s rozsahem pozorovatelnosti. Pro příklady S2S (service-to-service) a srovnání autentizace OBO vs S2S naleznete v Observability Authentication Setup for Agent SDK.

Resolver musí být synchronní. Získejte token ve svém asynchronním zpracovateli aktivity (nebo pomocí MSAL) a uložte ho do cache pro resolver.

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

_cached_token: str | None = None

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

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=my_token_resolver)

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

Agentic token cache pro aplikace Agent Framework

U aplikací Agent Framework, které používají autentizaci typu on-behalf-of (OBO), distribuce automaticky registruje IExporterTokenCache<AgenticTokenStruct> prostřednictvím DI, pokud nenastavíte vlastní TokenResolver. Váš agent volá RegisterObservability() za běhu, aby poskytl přihlašovací údaje, a cache zajišťuje získávání a obnovu tokenů.

Poznámka

Tento přístup podporuje pouze autentizační toky typu on-behalf-of (OBO). Pro autentizaci mezi službami (S2S) použijte místo toho manuální tokenový 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,
    )

Uložte atributy ověřování

Pro úspěšnou validaci úložiště musí váš agent implementovat InvokeAgentScope, InferenceScope a ExecuteToolScope. Každý rozsah odpovídá spanové operaci v kanonickém schématu:

Rozsah SDK Operace span Univerzální referenční kód
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

Úplné seznamy povinných a volitelných atributů pro jednotlivé rozsahy – včetně významu jednotlivých atributů, doporučení pro výběr hodnot a informací o tom, které atributy lze vyhledávat pomocí Microsoft Defender advanced hunting – najdete v referenčním dokumentu atributů pro Agent 365 observability. Sloupec Platí pro určuje, do jakého scope každý atribut patří, a sloupec Požadováno rozlišuje mezi povinnými (M) a volitelnými (O) atributy.

Otestujte svého agenta pomocí pozorovatelnosti

Po implementaci observability ověřte, že se telemetrie zaznamenává:

  1. Přejděte na https://admin.cloud.microsoft/#/agents/all.
  2. Vyberte svého agenta a následně vyberte Aktivita.
  3. Ověřte, že jsou zobrazeny relace a volání nástrojů.

Ukázkové aplikace a pokročilá konfigurace

Pro ukázkové aplikace a pokročilé konfigurační možnosti viz GitHub repozitáře pro každý jazyk:

Odkaz na programování

Projděte typy distribucí Microsoft OpenTelemetry pomocí následující programátorské reference:

Řešení problému

Tato sekce popisuje běžné problémy při implementaci a používání distribuce Microsoft OpenTelemetry s Agent 365.

Problém Popis
Data o pozorovatelnosti se nezobrazují Není vidět žádná telemetrie, protože export do Agent 365 není povolen, nastavení není dokončeno nebo došlo k chybě při vyřešení tokenu.
Chybí klient ID nebo agent ID – spany přeskočeny Spany jsou před exportem filtrovány, pokud chybí požadované identifikační atributy klientu nebo agenta.
Selhání při získání tokenu – export přeskočen nebo nepovolen Export je přeskočen nebo odmítnut, pokud tokenový resolver nevrátí žádný token nebo dojde k chybě při získávání tokenu.
HTTP 401 Neautorizováno Požadavky dorazí do služby, ale ověření selže, protože token je neplatný, jeho platnost vypršela nebo je určen pro nesprávné publikum.
HTTP 403 Zakázáno Autorizace selže kvůli chybějící licenci klienta nebo chybějícím oprávněním k zápisu pozorovatelnosti.
HTTP 403 Forbidden - Nesoulad ID agenta Služba odmítá export, pokud ID agenta v požadavku neodpovídá identitě tokenem autorizovaného agenta.
Chyby HTTP 429 nebo 5xx – Přechodné chyby Dočasné zpomalování nebo nestabilita backendu přerušují export a mohou vyžadovat opakované pokusy nebo dávkové ladění.
Exportní časový limit Exportní operace překračují časové limity kvůli zpožděním sítě nebo latenci odezvy koncových bodů.
Export uspěje, ale telemetrie se v Defenderu ani Purview nezobrazuje Import dat sice proběhne úspěšně, ale jejich viditelnost je zpožděna nebo blokována návaznými prerekvizitami a požadavky na schéma.

Zpropitné

Průvodce odstraňováním problémů Agent 365 obsahuje doporučení k odstraňování problémů na vysoké úrovni, osvědčené postupy a odkazy na obsah o řešení problémů pro každou část životního cyklu vývoje Agent 365.

Data o pozorovatelnosti se nezobrazují

Příznaky:

  • Agent běží
  • Žádná telemetrie v administračním centru
  • Není vidět aktivita agenta

Hlavní příčina:

  • Export z Agent 365 není aktivován
  • Chyby konfigurace
  • Problémy s resolverem tokenů

ŘEŠENÍ: Vyzkoušejte následující kroky k vyřešení problému:

  • Ověřte, že export Agent 365 je povolen

    Musíte explicitně povolit exportér Agent 365. Pokud jej nenastavíte, distribuce může použít exportér konzole nebo neexportovat nic. Povolte to v kódu:

    from microsoft.opentelemetry import use_microsoft_opentelemetry

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

    Nebo nastavte proměnnou prostředí:

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    Poznámka

    ENABLE_A365_OBSERVABILITY_EXPORTER je sekundární přepínač, který se uplatní pouze tehdy, když je enable_a365=True nastaven v kódu. Můžete jej také ovládat pomocí a365_enable_observability_exporter kwarg.

  • Zkontrolujte konfiguraci překladače tokenů

    Exportér vyžaduje platný tokenový resolver, který vrací Bearer token pro každý požadavek na export. Pokud tokenový resolver chybí nebo vrátí null, export se tiše přeskočí.

  • Povolte export do konzole a zkontrolujte telemetrii lokálně

    Přidejte exportér do konzole, který ověří, že telemetrie je generována ještě před dosažením endpointu Agent 365:

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Povolit podrobné protokolování

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Zkontrolujte logy kvůli chybám exportu

    Použijte příkaz az webapp log tail pro vyhledávání chyb souvisejících s pozorovatelností v logech:

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

Chybí klient ID nebo agent ID – spany přeskočeny

Příznaky: Systém tiše zahazuje spany a nikdy je neexportuje. Některé platformy zaznamenávají počet přeskočených spanů nebo zprávu jako No spans with tenant/agent identity found. Jiní je zahazují bez zaznamenání do logu.

Řešení

  • Před exportem distribuce rozděluje spany podle identity klienta a agenta. Spany, kterým chybí buď ID nájemce, nebo ID agenta, jsou vyřazeny a nikdy nejsou odeslány do služby.
  • Před vytvářením spanů ověřte, že BaggageBuilder je nastaven s ID nájemce a ID agenta. Tyto hodnoty se propagují kontextem OpenTelemetry a připojují se ke všem spanům vytvořeným v rámci baggage scope. Pro platformově specifické API viz Baggage attributes.
  • Pokud používáte baggage middleware nebo turn context helper z integračního balíčku hostingu, ověřte, že aktivita TurnContext má platného příjemce s identitou agenta.

Selhání tokenového překladače — export přeskočen nebo neoprávněný

Symptomy: Tokenový resolver vrátí null nebo vyhodí chybu. V závislosti na platformě je export buď zcela přeskočen, nebo selže s HTTP 401.

Řešení

  • Je vyžadován tokenový resolver. Pokud chybí, exportér při startu vyhodí chybu. Ověřte, že je k dispozici token resolver a vrací platný Bearer token.
  • Ujistěte se, že správné ID klienta a ID agenta jsou předány BaggageBuilder, protože tyto hodnoty jsou předávány token překladače.
  • U agentů hostovaných v Azure ověřte, že spravovaná identita má požadované oprávnění API pro rozsah pozorovatelnosti.
  • U .NET aplikací využívajících hostingový balíček Agent Framework je výměna tokenů řešena automaticky přes DI. Pokud chybí tokeny, potvrďte, že je nainstalován a registrován Microsoft.Agents.A365.Observability.Hosting.

HTTP 401 Neautorizováno

Symptomy: Export selhal s chybou HTTP 401. Exportér tuto chybu neopakuje.

Řešení

  • Ověřte, že cílová skuina tokenu odpovídá koncovému bodu rozsahu pozorovatelnosti.
  • Zkontrolujte, že tokenový resolver nevrací delegovaný uživatelský token, token pro nesprávnou audience nebo expirovaný token.

HTTP 403 – Zakázáno

Symptomy: Export selhal s chybou HTTP 403. Exportér tuto chybu neopakuje.

Hlavní příčina: Chyba HTTP 403 může mít různé příčiny. Zkontrolujte následující řešení v uvedeném pořadí.

Řešení

  • Chybějící licence — Ověřte, že váš klient má přiřazenou jednu z následujících licencí v Centru pro správu Microsoft 365:

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

  • Chybějící Agent365.Observability.OtelWriteoprávnění — Udělte oprávnění své identitě (spravovaná identita nebo registrace aplikace). Bez něj se export telemetrie nezdaří s chybou HTTP 403.

Udělení oprávnění

Použijte některou z těchto možností:

  • Agent 365 CLI

    Vyžaduje účet globálního administrátora; spusťte z adresáře projektu agenta, který obsahuje a365.config.json; nebo použijte --agent-name.

    a365 setup permissions bot

    Nebo bez konfiguračního souboru:

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

  • Entra Portal

    Nejsou potřeba žádné konfigurační soubory; vyžaduje přístup globálního administrátora k registraci aplikace Blueprint.

    1. Přejděte na Entra portal>Registrace aplikací> Vyberte svoji aplikaci Blueprint.
    2. Přejděte na Oprávnění API>Přidat oprávnění>Rozhraní API, které moje organizace používá> vyhledejte 9b975845-388f-4429-889e-eab1ef63949c.
    3. Vyberte Delegovaná oprávnění>, zaškrtněte Agent365.Observability.OtelWrite>Přidat oprávnění.
    4. Opakujte kroky 2–3, tentokrát vyberte Oprávnění aplikace> a zkontrolujte Agent365.Observability.OtelWrite>Přidat oprávnění.
    5. Klikněte na Udělit souhlas správce a potvrďte.

    Oba Agent365.Observability.OtelWrite (Delegováno) i Agent365.Observability.OtelWrite (Aplikace) zobrazují Granted stav.

HTTP 403 Forbidden — Neshoda ID agenta

Příznaky: Export selže s HTTP 403 a serverovou zprávou podobnou 403 Forbidden při agent-ID-mismatch chybě při volání koncových bodů Agent 365 pro trasování.

Příčina: Tato chyba nastává, když při konfiguraci agenta použijete ID klienta blueprint místo ID klienta instance agenta, když nastavujete podrobnosti agenta. ID agenta v exportní URL neodpovídá identitě autorizované tokenem, proto trasovací endpoint požadavek odmítá.

Řešení

  • Ověřte, zda je ID klientu přidáno do seznamu povolených klientů Agent 365.
  • Nastavte údaje o agentovi pomocí ID klienta instance agenta instance klienta agenta (nikoli ID klienta blueprintu).
  • Zkontrolujte exportní URL, která se generuje – je zaznamenána, pokud zapnete logger. Ověřte, že ID agenta v URL odpovídá ID klienta instance agenta.
  • Pro povolení diagnostického logování podle SDK viz Lokální validace.

Chyby HTTP 429 nebo 5xx – Přechodné chyby

Příznaky: Export selže s přechodným HTTP stavovým kódem, například 429 nebo 5xx.

Řešení

  • Tyto chyby jsou obvykle přechodné a samy se vyřeší. Distribuce pro Python a JavaScript automaticky opakují pokusy při HTTP stavových kódech 408, 429 a 5xx. Distribuce .NET automaticky neopakuje pokusy.
  • Pokud chyby přetrvávají, zkontrolujte dashboard zdravotního stavu služby.
  • Zvažte snížení frekvence exportu zvýšením plánovaného zpoždění mezi dávkami nebo zvýšením maximální velikosti exportní dávky. Pro Python a JavaScript použijte příslušné exporterOptions nebo a365_* parametry zdokumentované v GitHub repozitářích. Pro .NET použijte o.Agent365.Exporter.ScheduledDelayMilliseconds a o.Agent365.Exporter.MaxExportBatchSize.

Exportní časový limit

Příznaky: Pokusy o export končí vypršením časového limitu.

Řešení

  • Zkontrolujte síťové připojení k pozorovacímu endpointu.

  • Výchozí časový limit HTTP požadavku je 30 sekund na všech platformách. Pokud k vypršení časového limitu dochází často, zvyšte hodnotu časového limitu v nastavení exportéru:

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

    Viz repozitář Python pro úplný seznam možností a365_*.

Export uspěje, ale telemetrie se v Defenderu ani Purview nezobrazuje

Příznaky: Logy ukazují úspěšný export (HTTP 200), ale telemetrie není viditelná v Microsoft Defender ani Microsoft Purview.

Řešení

  • Ověřte, že splňujete předpoklady pro prohlížení exportovaných logů:
  • Telemetrie se může naplnit až po několika minutách od úspěšného exportu. Počkejte s dalším vyšetřováním.
  • Ověřte, že spany obsahují platné atributy microsoft.tenant.id a gen_ai.agent.id. Chybějící atributy identity způsobují, že na serverové straně jsou vyřazeny spany, i když export HTTP vrátí 200.

Související obsah

  • Last updated on