Microsoft OpenTelemetry Distro

Microsoft OpenTelemetry Distro to zunifikowana dystrybucja obserwowalności, która zapewnia jednolity proces wdrażania do zbierania śladów, metryk i logów z aplikacji agentowych i nieagentowych. Zapewnia obserwowalność dla Microsoft Agent 365, Microsoft Foundry, Azure Monitor oraz dowolnego backendu zgodnego z OTLP (OpenTelemetry Protocol). Distro obsługuje .NET, Node.js i Python oraz zastępuje zfragmentowane konfiguracje w różnych stosach obserwowalności jednym importem i jednym wywołaniem konfiguracyjnym.

Główne korzyści

Dystrybucja Microsoft OpenTelemetry oferuje następujące korzyści:

  • Jeden pakiet, jedno API: Zastąp wiele pakietów eksporterów i instrumentacji jedną zależnością.
  • Obsługa wielu backendów: Przesyłaj telemetrię do Azure Monitor, dowolnego punktu końcowego zgodnego z protokołem OpenTelemetry (OTLP), takiego jak Datadog, Grafana lub New Relic, oraz Microsoft Agent 365 jednocześnie.
  • Wbudowane instrumentacje: Użyj automatycznej instrumentacji dla HTTP, baz danych, Azure SDK, Azure Functions i wielu innych bez dodatkowej konfiguracji.
  • Oparte na standardach: Zbudowane na OpenTelemetry, branżowej standardowej strukturze obserwowalności.
  • Minimalny szablon: Dodaj jedno wywołanie importu i jedno wywołanie funkcji do punktu wejścia aplikacji.

Konfigurowanie i instalowanie

Ten przewodnik pokazuje, jak dodać obserwowalność do swojej aplikacji za pomocą Microsoft OpenTelemetry Distro. Dystrybucja automatycznie zbiera ślady, metryki i logi dzięki wbudowanej instrumentacji oraz eksportuje telemetrię do Azure Monitor, dowolnego endpointu OpenTelemetry (OTLP) lub Microsoft Agent 365.

Zainstaluj bibliotekę

Aby rozpocząć pracę z dystrybucją Microsoft OpenTelemetry, zainstaluj odpowiednią bibliotekę dla swojej platformy programistycznej, korzystając z menedżera pakietów dla danego języka programowania.

Wymagania wstępne: Python 3.10 lub nowszy.

pip install microsoft-opentelemetry

Konfiguracja

Eksporter Agent 365 nie używa ciągu połączenia. Automatycznie wykrywa swój punkt końcowy na podstawie dzierżawcy. Aby umożliwić eksport do Agent 365, ustaw cel eksportera i zapewnij resolver tokenów, który zwraca token dostępu dla danego ID agenta i tenanta.

Wywołaj use_microsoft_opentelemetry(), aby włączyć obserwowalność.

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

Aby zastosować niestandardową obsługę tokenów (zamiast domyślnego rozwiązywacza tokenów), zobacz Ręczny rozwiązywacz tokenów.

Zachowanie eksportera można dostosować, przekazując instancję a365_* kwargs do use_microsoft_opentelemetry().

Parametr Podpis Wartość domyślna
a365_use_s2s_endpoint Gdy True jest ustawiony, używana jest ścieżka punktu końcowego S2S. False
a365_max_queue_size Maksymalny rozmiar kolejki procesora wsadowego. 2048
a365_scheduled_delay_ms Opóźnienie w milisekundach między wsadami eksportowymi. 5000
a365_exporter_timeout_ms Limit czasu (w milisekundach) dla operacji eksportu. 30000
a365_max_export_batch_size Maksymalny rozmiar partii dla operacji eksportowych. 512

Propaguj kontekst

Aby utrzymać obserwowalność w rozproszonych operacjach Agent 365, propaguj kontekst. Propagując kontekst przez agentów i usługi, zapewniasz, że ślady, logi i metryki są prawidłowo skorelowane przez cały cykl życia żądania. Ta korelacja jest niezbędna do pełnego i skutecznego monitorowania Microsoft Agent 365.

Atrybuty bagażu

Użyj BaggageBuilder, aby ustawić informacje kontekstowe, które przepływają przez wszystkie spany w żądaniu. SDK implementuje SpanProcessor, który kopiuje wszystkie niepuste wpisy bagażu do nowo rozpoczętych spanów, nie nadpisując istniejących atrybutów.

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

Aby automatycznie uzupełnić BaggageBuilder danymi z TurnContext, użyj Copilota populate z pakietu microsoft-opentelemetry. Ten Copilot automatycznie wyodrębnia szczegóły dzwoniącego, agenta, najemcy, kanału i rozmowy z aktywności.

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

Oprogramowanie pośredniczące bagażu

Jeśli Twój agent korzysta z pakietu integracji hostingu, zarejestruj middleware baggage, aby automatycznie uzupełniać baggage dla każdego przychodzącego żądania. Ten krok eliminuje konieczność ręcznego wywoływania BaggageBuilder w każdym handlerze aktywności.

W Pythonie zarejestruj middleware bagażu przez ObservabilityHostingManager.configure(), a nie bezpośrednio na adapterze.

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

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

Middleware pomija ustawianie baggage dla asynchronicznych odpowiedzi (ContinueConversation zdarzeń), aby uniknąć nadpisania baggage ustawionego przez żądanie początkowe.

Weryfikacja danych przepływa w produkcie

Aby wyświetlić telemetrię agentów w Microsoft Purview lub Microsoft Defender, upewnij się, że spełnione są następujące wymagania:

Automatyczna instrumentacja

Dystrybucja Microsoft OpenTelemetry łączy standardowe potoki OpenTelemetry z instrumentacją opracowaną przez Microsoft. Distro może zbierać telemetrię aplikacji, telemetrię infrastruktury oraz telemetrię agentową lub generatywną AI, w zależności od języka i konfiguracji.

Kategoria Co obejmuje
Potoki sygnałów Ślady, wskaźniki i dzienniki.
Wykrywanie zasobów Usługa, host, chmura i kontekst uruchomieniowy Azure tam, gdzie były obsługiwane.
Instrumentacja infrastruktury HTTP, ASP.NET Core, Azure SDK, klienci baz danych oraz frameworki logujące tam, gdzie są obsługiwane.
Instrumentacja generatywnej AI OpenAI, Azure OpenAI, Semantic Kernel, LangChain, OpenAI Agents SDK oraz Agent Framework, tam gdzie są obsługiwane.
Ręczne zakresy agenta Wywołanie agenta, uruchomienie narzędzia, inferencja i telemetria wynikowa tam, gdzie jest obsługiwane.
Eksporterzy i procesory Azure Monitor, Microsoft Agent 365, OTLP, wyjście konsolowe, procesory span, procesory logów oraz czytniki metryk.

Zakres instrumentacji

Język Typowe oprzyrządowanie do zastosowań Instrumentacja agentów powszechnych i generatywnej AI
Python Zasoby, procesory, czytniki, logowanie, metryki i ślady OpenTelemetry. Semantic Kernel, OpenAI Agents SDK, Agent Framework, LangChain, pakiet Microsoft Agent 365 oraz zakresy Microsoft Agent 365.
Node.js HTTP, Azure SDK, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis, Bunyan i Winston. OpenAI Agents SDK, LangChain, Microsoft Agent 365 baggage oraz Microsoft Agent 365.
.NET ASP.NET Core, HttpClient, SQL Client, Azure SDK, wykrywanie zasobów, metryki oraz logi. Semantic Kernel, OpenAI i Azure OpenAI, Agent Framework, bagaż Microsoft Agent 365 oraz zakresy Microsoft Agent 365.

Automatyczna instrumentacja nasłuchuje sygnałów telemetrycznych emitowanych przez obsługiwane biblioteki i frameworki. Instrumentacja manualna jest stosowana, gdy aplikacja musi opisać operacje specyficzne dla agenta, takie jak wywołanie, wykonanie narzędzia, wnioskowanie lub asynchroniczne wyjście.

Dodaj niestandardowe źródła, liczniki, procesory lub czytniki OpenTelemetry, gdy Twoja aplikacja emituje telemetrię, która nie jest obsługiwana przez wbudowane instrumentacje.

Ważne

Automatyczna instrumentacja uzupełnia tylko standardowe atrybuty OpenTelemetry. Nie obejmuje wszystkich atrybutów wymaganych przez Agent 365. Musisz dodać atrybuty specyficzne dla Microsoft za pomocą BaggageBuilder. Aby zobaczyć, które atrybuty są wymagane, zobacz Zapisywanie atrybutów walidacji.

Wbudowane biblioteki instrumentacji

Auto-instrumentacja nasłuchuje telemetrii emitowanej przez obsługiwane frameworki i przekazuje ją przez potok OpenTelemetry Distro. W scenariuszach agentowych należy ustawić bagaż (np. tenant ID i agent ID) przed utworzeniem spanów przez instrumentowane środowisko.

Framework Python Node.js .NET
Semantic Kernel Obsługiwane Nieobsługiwane Obsługiwane
OpenAI i OpenAI Agents SDK Obsługiwana Obsługiwane Obsługiwana
Agent Framework Obsługiwane Nieobsługiwane Obsługiwane
LangChain Obsługiwana Obsługiwana Brak na liście

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

Instrumentacja ręczna

Używaj ręcznej instrumentacji, gdy automatyczna instrumentacja nie opisuje działania agenta wystarczająco szczegółowo. Zakresy ręczne pozwalają aplikacji opisywać wspólne działania agentów w spójny sposób w różnych językach.

Zakres Użycie dla
InvokeAgentScope Początek i zakończenie wywołania agenta.
ExecuteToolScope Wywołanie narzędzia przez agenta.
InferenceScope Operacja wnioskowania modelu AI.
OutputScope Wyjście, które musi zostać zarejestrowane po zakończeniu zakresu wyjściowego.

Ponownie użyj tych samych wartości identyfikujących żądanie i agenta we wszystkich zakresach w ramach jednego żądania, aby powiązana telemetria mogła być skorelowana.

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

Uruchamianie narzędzia

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)

Wnioskowanie

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

Dane wyjściowe

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

Dokumentacja produktu powinna określać wszelkie wymagania dotyczące walidacji specyficzne dla tych zakresów.

Walidacja lokalna

Lokalna weryfikacja potwierdza, że aplikacja generuje telemetrię, zanim zostanie ona zweryfikowana w docelowym punkcie przeznaczenia specyficznym dla produktu. Użyj wyjścia konsoli lub lokalnego endpointu OTLP, aby sprawdzić, czy tworzone są ślady, metryki i logi.

Waliduj z użyciem lokalnego punktu końcowego OTLP

Skonfiguruj Distro, aby wysyłała telemetrię do lokalnego kolektora lub innego punktu końcowego zgodnego z OTLP.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Weryfikacja za pomocą lokalnego wyjścia

Użyj lokalnego wyjścia, gdy chcesz potwierdzić instrumentację przed wysłaniem telemetrii do zdalnego celu.

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.

Przejrzyj lokalne wyjście pod kątem spanów z oczekiwanych źródeł, takich jak żądania HTTP, wywołania OpenAI lub Azure OpenAI, zakresy wywołań agentów, zakresy wykonywania narzędzi lub zakresy wnioskowania. Walidacja związana z konkretnym miejscem docelowym jest opisana w dokumentacji produktu dla tego celu.

Ręczna konfiguracja uwierzytelniania

Korzystając z eksportera Agent 365, musisz zapewnić mechanizm przekazywania tokena uwierzytelniającego. Mechanizm rozpoznawania tokenów działa dla każdej partii eksportu, wykorzystując ID agenta i ID najemcy z aktywnego kontekstu bagażowego. Dystrybucja obsługuje dwa podejścia.

Wskazówka

Jeśli tworzysz agenty przy użyciu Zestawu SDK agentów usługi Microsoft 365, zapoznaj się z dokumentem Konfiguracja uwierzytelniania w ramach funkcji obserwowalności dla pakietu Agent SDK — znajdziesz tam szczegółowe instrukcje krok po kroku dotyczące konfiguracji OBO oraz pozyskiwania tokenów S2S zarówno dla agentów typu „agentic”, jak i „non-agentic”.

Ręczny resolver tokenów

Użyj manualnego resolvera, gdy pozyskujesz tokeny poza procesem Agent Framework, gdy tworzysz aplikacje spoza Agent Framework lub gdy korzystasz z uwierzytelniania service-to-service (S2S) (przepływ z użyciem poświadczeń klienta). Agent może sam wygenerować token, na przykład korzystając z Microsoft Authentication Library (MSAL) lub innej metody pozyskiwania tokenów, ale musi upewnić się, że token ma odpowiedni zakres obserwowalności (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite).

Notatka

W przypadku uwierzytelniania typu service-to-service (S2S) należy zastosować ręczny resolver tokenów. Pamięć podręczna tokenów agentycznych obsługuje wyłącznie przepływy uwierzytelniania on-behalf-of (OBO).

Poniższe przykłady prezentują mechanizm rozwiązywania tokenów OBO (on-behalf-of) — agent pozyskuje token użytkownika za pomocą agentowego modułu uwierzytelniania i wymienia go na token z zakresem obserwowalności. Aby zobaczyć przykłady S2S (service-to-service) oraz porównanie uwierzytelniania OBO i S2S, zobacz „Observability Authentication Setup for Agent SDK”.

Ten resolver musi działać synchronicznie. Uzyskaj token w swoim asynchronicznym handlerze aktywności (lub za pomocą MSAL) i przechowaj go dla resolvera.

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 w aplikacjach Agent Framework

W przypadku aplikacji Agent Framework, które używają uwierzytelniania on-behalf-of (OBO), dystrybucja automatycznie rejestruje IExporterTokenCache<AgenticTokenStruct> przez DI, jeśli nie ustawisz własnego TokenResolver. Twój agent wywołuje RegisterObservability() podczas działania aplikacji, aby przekazać dane uwierzytelniające, a pamięć podręczna obsługuje pozyskiwanie i odświeżanie tokenów.

Notatka

To rozwiązanie wspiera wyłącznie procesy uwierzytelniania on-behalf-of (OBO). W przypadku uwierzytelniania serwis-serwis (S2S) zastosuj ręczny resolver tokenów zamiast tego.

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

Zapisz atrybuty walidacji

Aby walidacja store zakończyła się sukcesem, Twój agent musi zaimplementować InvokeAgentScope, InferenceScope oraz ExecuteToolScope. Każdy zakres odpowiada operacji span w schemacie kanonicznym:

Zakres SDK Operacja span Uniwersalny kod referencyjny
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

Pełne listy wymaganych i opcjonalnych atrybutów dla każdego zakresu — wraz z opisem semantyki poszczególnych atrybutów, wskazówkami dotyczącymi wyboru wartości oraz informacją, które atrybuty są dostępne do wyszukiwania zaawansowanego w Microsoft Defender — znajdziesz w dokumencie Referencja atrybutów obserwowalności Agent 365. Kolumna Dotyczy wskazuje, do którego zakresu należy każdy atrybut, a kolumna Wymagane rozróżnia atrybuty obowiązkowe (M) od opcjonalnych (O).

Przetestuj agenta pod kątem obserwowalności

Po wdrożeniu obserwowalności sprawdź, czy telemetria jest rejestrowana:

  1. Przejdź do https://admin.cloud.microsoft/#/agents/all.
  2. Wybierz swojego agenta, a następnie wybierz Aktywność.
  3. Sprawdź, czy pojawiają się sesje i wywołania narzędzi.

Przykładowe aplikacje i zaawansowana konfiguracja

Działające przykłady i zaawansowane opcje konfiguracyjne znajdziesz w repozytoriach GitHub dla każdego języka:

Rozwiązywanie problemów

Ta sekcja opisuje typowe problemy podczas implementacji i użytkowania dystrybucji Microsoft OpenTelemetry z Agent 365.

Problem Podpis
Dane telemetryczne nie pojawiają się Telemetria nie jest widoczna, ponieważ eksport przez Agent 365 nie jest włączony, konfiguracja jest niekompletna lub pozyskiwanie tokena nie powiodło się.
Brakujący identyfikator najemcy lub agenta – span'y pominięte Spany są filtrowane przed eksportem, gdy wymagane atrybuty tożsamości najemcy lub agenta są nieobecne.
Awaria pozyskiwania tokena – eksport pominięty lub nieautoryzowany Eksport jest pomijany lub odrzucany, gdy resolver tokena nie zwraca tokena lub wystąpią błędy podczas pozyskiwania tokena.
HTTP 401 Brak autoryzacji Żądania docierają do usługi, ale uwierzytelnianie zawodzi, ponieważ token jest nieprawidłowy, wygasł lub jest przeznaczony dla niewłaściwego odbiorcy.
HTTP 403 Zabronione Autoryzacja nie powiodła się z powodu braku licencjonowania dzierżawcy lub braku uprawnień do zapisu danych obserwowalności.
HTTP 403 Forbidden — Niedopasowanie identyfikatorów agenta Usługa odrzuca eksport, gdy identyfikator agenta w żądaniu nie zgadza się z tożsamością agenta autoryzowanego przez token.
Błędy HTTP 429 lub 5xx – błędy przejściowe Tymczasowe ograniczanie lub niestabilność backendu przerywają eksport i mogą wymagać ponownych prób lub dostrojenia wsadowego.
Limit czasu eksportu Operacje eksportowe przekraczają limit czasu z powodu opóźnień sieciowych lub opóźnionej odpowiedzi ze strony punktów końcowych.
Eksport się powiódł, ale telemetria nie pojawia się w Defender ani Purview Pobieranie danych kończy się sukcesem, ale widoczność jest opóźniona lub blokowana przez wymagania wstępne i schematy.

Wskazówka

Przewodnik po rozwiązywaniu problemów Agent 365 zawiera wysokopoziomowe zalecenia dotyczące rozwiązywania problemów, najlepsze praktyki oraz odnośniki do treści dotyczących rozwiązywania problemów dla każdego etapu cyklu rozwoju Agent 365.

Dane telemetryczne nie pojawiają się

Objawy:

  • Agent jest uruchomiony
  • Brak telemetrii w centrum administracyjnym
  • Nie widać aktywności agenta

Główna przyczyna:

  • Eksport Agent 365 nie jest włączony
  • Błędy konfiguracji
  • Problemy z rozwiązywaniem tokenów

Rozwiązania: Wykonaj poniższe kroki, aby rozwiązać problem:

  • Sprawdź, czy eksport Agent 365 jest włączony

    Musisz jawnie włączyć eksporter Agent 365. Jeśli tego nie ustawisz, distro może przełączyć się na eksportera konsolowego lub nie wyeksportować niczego. Aktywuj w kodzie:

    from microsoft.opentelemetry import use_microsoft_opentelemetry

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

    Lub ustaw zmienną środowiskową:

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    Notatka

    ENABLE_A365_OBSERVABILITY_EXPORTER jest dodatkowym przełącznikiem, który działa tylko wtedy, gdy enable_a365=True jest ustawiony w kodzie. Możesz także kontrolować to za pomocą argumentu a365_enable_observability_exporter kwarg.

  • Sprawdź konfigurację mechanizmu rozstrzygania tokenów

    Eksporter wymaga prawidłowego mechanizmu rozstrzygania tokenów, który zwraca token typu Bearer dla każdego żądania eksportu. Jeśli resolver tokenów jest nieobecny lub zwraca null, eksport jest pomijany po cichu.

  • Włącz eksport na konsolę i sprawdź telemetrię lokalnie

    Dodaj eksporter konsolowy, aby zweryfikować, czy telemetria jest generowana, zanim dotrze do punktu końcowego Agent 365:

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Włącz rejestrowanie pełne

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Sprawdź logi pod kątem błędów eksportu

    Użyj polecenia az webapp log tail, aby wyszukać w logach błędy związane z obserwowalnością:

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

Brak identyfikatora dzierżawy lub identyfikatora agenta — spany pominięte

Objawy: System bez powiadomienia odrzuca span(y) i nigdy ich nie eksportuje. Niektóre platformy logują liczbę pominiętych spanów lub wiadomość taką jak No spans with tenant/agent identity found. Inne platformy pomijają je bez zapisywania w logach.

Rozwiązanie:

  • Przed eksportem dystrybucja dzieli spany według tożsamości najemcy i agenta. Spany, które nie mają identyfikatora najemcy lub agenta, są odrzucane i nigdy nie są wysyłane do usługi.
  • Upewnij się, że BaggageBuilder jest skonfigurowany z identyfikatorem najemcy i agenta przed utworzeniem spanów. Te wartości są przekazywane przez kontekst OpenTelemetry i przypisywane do wszystkich spanów utworzonych w zakresie bagażu. Aby uzyskać informacje o API specyficznym dla platformy, zobacz Atrybuty bagażu.
  • Jeśli używasz middleware do obsługi bagażu lub Copilota kontekstu rozmowy z pakietu integracji hostingu, upewnij się, że aktywność TurnContext ma prawidłowego odbiorcę z tożsamością agenta.

Błąd rozpoznawania tokena — eksport pominięty lub nieautoryzowany

Objawy: Mechanizm rozpoznawania tokena zwraca null lub zgłasza błąd. W zależności od platformy, eksport jest albo całkowicie pomijany, albo kończy się błędem HTTP 401.

Rozwiązanie:

  • Token resolver jest wymagany. Jeśli go brakuje, eksporter zgłasza błąd podczas uruchamiania. Zweryfikuj, czy token resolver został skonfigurowany oraz że zwraca prawidłowy token typu Bearer.
  • Upewnij się, że poprawny identyfikator tenanta i identyfikator agenta są przekazywane do BaggageBuilder, ponieważ te wartości są przekazywane do resolvera tokenów.
  • Dla agentów hostowanych w Azure sprawdź, czy Managed Identity posiada wymagane uprawnienia API do zakresu obserwowalności.
  • W przypadku aplikacji .NET korzystających z pakietu hostingowego Agent Framework, wymiana tokenów jest obsługiwana automatycznie przez DI. Jeśli brakuje tokenów, upewnij się, że Microsoft.Agents.A365.Observability.Hosting jest zainstalowany i zarejestrowany.

HTTP 401 Brak autoryzacji

Objawy: Eksport kończy się niepowodzeniem z błędem HTTP 401. Eksporter nie ponawia próby po tym błędzie.

Rozwiązanie:

  • Sprawdź, czy audience tokena odpowiada zakresowi punktu końcowego obserwowalności.
  • Sprawdź, czy resolver tokenów nie zwraca tokena użytkownika delegowanego, tokena dla niewłaściwej grupy odbiorców lub tokena wygasłego.

HTTP 403 Zabronione

Objawy: Eksport kończy się niepowodzeniem z błędem HTTP 403. Eksporter nie ponawia próby po tym błędzie.

Główna przyczyna: Błąd HTTP 403 może mieć różne przyczyny. Sprawdź następujące rozwiązania po kolei.

Rozwiązanie:

  • Brakująca licencja — Zweryfikuj, czy Twój tenant ma przypisaną jedną z następujących licencji w Centrum administracyjnym platformy Microsoft 365:

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

  • Brak Agent365.Observability.OtelWriteuprawnienia — nadaj uprawnienie swojej tożsamości (zarządzana tożsamość lub rejestracja aplikacji). Bez niego eksport telemetrii kończy się błędem HTTP 403.

Przyznaj uprawnienie

Skorzystaj z jednej z tych opcji:

  • Agent 365 CLI

    Wymaga konta Global Administratora; uruchom z katalogu projektu agenta zawierającego a365.config.json, lub użyj --agent-name.

    a365 setup permissions bot

    Lub bez plików konfiguracyjnych:

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

  • Entra Portal

    Nie są wymagane pliki konfiguracyjne; wymagany jest dostęp Globalnego Administratora do rejestracji aplikacji Blueprint.

    1. Przejdź do Entra portal>Rejestracja aplikacji> i wybierz swoją aplikację Blueprint.
    2. Przejdź do Uprawnienia API>Dodaj uprawnienie>API używane przez moją organizację> wyszukaj 9b975845-388f-4429-889e-eab1ef63949c.
    3. Wybierz Delegowane uprawnienia> i zaznacz Agent365.Observability.OtelWrite>Dodaj uprawnienia.
    4. Powtórz kroki 2–3, tym razem wybierz Uprawnienia aplikacji> zaznacz Agent365.Observability.OtelWrite>Dodaj uprawnienia.
    5. Kliknij Udziel zgody administratora i potwierdź.

    Zarówno Agent365.Observability.OtelWrite (Delegowane), jak i Agent365.Observability.OtelWrite (Aplikacyjne) powinny mieć status Granted.

HTTP 403 Forbidden — Niedopasowanie identyfikatorów agenta

Objawy: Eksport kończy się niepowodzeniem z HTTP 403 i komunikatem serwera podobnym do 403 Forbidden, z agent-ID-mismatch błędami podczas wywoływania punktów końcowych Śledzenia Agent 365.

Przyczyna źródłowa: Ten błąd występuje, gdy używasz identyfikatora klienta blueprint zamiast identyfikatora instancji agenta podczas ustawiania szczegółów agenta. ID agenta w URL eksportu nie zgadza się z tożsamością autoryzowaną przez token, więc punkt końcowy Śledzenia odrzuca żądanie.

Rozwiązanie:

  • Zweryfikuj, czy identyfikator najemcy został dodany do listy dozwolonych najemców Agent 365.
  • Ustaw szczegóły agenta za pomocą identyfikatora klienta instancji agenta (nie identyfikatora klienta blueprintu).
  • Zweryfikuj wygenerowany adres eksportu – jest logowany, jeśli włączysz loggera. Potwierdź, że identyfikator agenta w URL odpowiada identyfikatorowi klienta instancji agenta.
  • Aby włączyć logowanie diagnostyczne dla poszczególnych SDK, zobacz Weryfikacja lokalna.

Błędy HTTP 429 lub 5xx – błędy przejściowe

Objawy: Eksport kończy się niepowodzeniem z przejściowym kodem statusowym HTTP, takim jak 429 lub 5xx.

Rozwiązanie:

  • Te błędy mają zwykle charakter przejściowy i ustępują bez interwencji. Dystrybucje dla Pythona i JavaScriptu automatycznie ponawiają próby wysyłki przy kodach statusu HTTP 408, 429 i 5xx. Dystrybucja .NET nie ponawia prób automatycznie.
  • Jeśli błędy się utrzymają, sprawdź pulpit nawigacyjny statusu usługi.
  • Rozważ ograniczenie częstotliwości eksportu poprzez zwiększenie zaplanowanego opóźnienia między partiami lub zwiększenie maksymalnej wielkości partii. W przypadku Pythona i JavaScript użyj odpowiednich parametrów exporterOptions lub a365_* udokumentowanych w repozytoriach GitHub . Dla .NET użyj o.Agent365.Exporter.ScheduledDelayMilliseconds oraz o.Agent365.Exporter.MaxExportBatchSize.

Limit czasu eksportu

Objawy: próby eksportu kończą się przekroczeniem limitu czasu.

Rozwiązanie:

  • Sprawdź łączność sieciową z punktem końcowym obserwowalności.

  • Domyślny limit czasu żądania HTTP na wszystkich platformach wynosi 30 sekund. Jeśli przekroczenia limitu czasu występują często, zwiększ wartość limitu czasu w opcjach eksportera:

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

    Pełną listę a365_* opcji znajdziesz w repozytorium Pythona.

Eksport się powiódł, ale telemetria nie pojawia się w Defender ani Purview

Objawy: Logi pokazują eksport zakończony sukcesem (HTTP 200), ale telemetria nie jest widoczna w Microsoft Defender ani Microsoft Purview.

Rozwiązanie:

  • Sprawdź, czy spełniasz wymagania wstępne do przeglądania wyeksportowanych logów:
  • Telemetria może pojawić się dopiero po kilku minutach od udanego eksportu. Poczekaj, zanim zaczniesz dalej badać.
  • Sprawdź, czy spany zawierają poprawne atrybuty microsoft.tenant.id i gen_ai.agent.id. Brak atrybutów tożsamości powoduje odrzucenie spanów po stronie serwera, nawet jeśli eksport HTTP zwraca kod 200.

Powiązana zawartość

  • Last updated on