Microsoft OpenTelemetry Distro

Microsoft Дистрибутив OpenTelemetry — это унифицированное распределение наблюдаемости, которое предоставляет единый интерфейс подключения для сбора трассировок, метрик и журналов из агентических и неагентных приложений. Он поддерживает наблюдаемость для Microsoft Agent 365, Microsoft Foundry, Azure Monitor и любого серверного решения, совместимого с OpenTelemetry Protocol (OTLP). Дистрибутив поддерживает .NET, Node.jsи Python и заменяет фрагментированную настройку в нескольких стеках наблюдаемости одним вызовом импорта и одного вызова конфигурации.

Ключевые преимущества

Дистрибутив OpenTelemetry Microsoft предоставляет следующие преимущества:

  • Один пакет, один API: замените несколько экспортеров и пакетов инструментирования одним зависимостями.
  • поддержка мульти-бэкэнд: отправляйте телеметрию в Azure Monitor, любую совместимую с OpenTelemetry Protocol (OTLP) конечную точку, такую как Datadog, Grafana или New Relic, и Microsoft Agent 365 одновременно.
  • ** Встроенные инструменты: Используйте автоматическую инструментацию для HTTP, баз данных, Azure SDK, Функции Azure и т. д. без дополнительной настройки.
  • На основе стандартов: основанная на OpenTelemetry платформа наблюдения, стандартная для отрасли.
  • Минимальный шаблон: добавьте один импорт и один вызов функции в точку входа приложения.

Установка и настройка

В этом руководстве показано, как добавить наблюдаемость в приложение с помощью Microsoft OpenTelemetry Distro. Дистрибутив автоматически собирает трассировки, метрики и журналы с помощью встроенного инструментирования и экспортирует телеметрические данные в Azure Monitor, на любую конечную точку протокола OpenTelemetry (OTLP) или агент Microsoft 365.

Библиотека установки

Чтобы начать работу с дистрибутивом Microsoft OpenTelemetry, установите подходящую библиотеку для вашей платформы разработки, используя менеджер пакетов вашего языка.

Требования: Python 3.10 или выше.

pip install microsoft-opentelemetry

Конфигурация

Экспортер Agent 365 не использует строка подключения. Он автоматически обнаруживает свою конечную точку в зависимости от арендатора. Чтобы включить экспорт в Agent 365, установите целевой экспортер и предоставьте резолвер токенов, который возвращает токен доступа для заданного ID агента и ID арендатора.

Вызов use_microsoft_opentelemetry() для включения наблюдаемости.

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

Для разрешения пользовательских токенов (вместо стандартного резолвера токенов) см. раздел «Ручной резолвер токенов».

Вы можете настроить поведение экспортера, передавая опциональные a365_* kwarg в use_microsoft_opentelemetry().

Parameter Описание По умолчанию
a365_use_s2s_endpoint Когда True, использует путь от сервиса к конечной точке. False
a365_max_queue_size Максимальный размер очереди для пакетного процессора. 2048
a365_scheduled_delay_ms Задержка в миллисекундах между экспортными партиями. 5000
a365_exporter_timeout_ms Тайм-аут в миллисекундах для операции экспорта. 30000
a365_max_export_batch_size Максимальный размер партии для экспортных операций. 512

Контекст распространения

Чтобы сохранить наблюдаемость между распределёнными операциями Agent 365, необходимо передавать контекст. Когда вы распространяете контекст через агентов и сервисы, вы гарантируете, что трассы, логи и метрики корректно коррелируют на протяжении всего жизненного цикла запроса. Эта корреляция необходима для полного и эффективного мониторинга Microsoft Agent 365.

Атрибуты багажа

Используется BaggageBuilder для задания контекстной информации, которая проходит через все диапазоны в запросе. SDK реализует задачу SpanProcessor , которая копирует все непустые записи багажа в только что начатые споведы без перезаписи существующих атрибутов.

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

Чтобы автоматически заполнить BaggageBuilder из TurnContext, используйте populate помощник в microsoft-opentelemetry пакете. Этот помощник автоматически извлекает данные звонящего, агента, арендатора, канала и разговора из активности.

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

Багажное промежуточное программное обеспечение

Если ваш агент использует интеграционный пакет хостинга, регистрируйте посредничество багажа, чтобы автоматически заполнять багаж для каждого входящего запроса. Этот шаг устраняет необходимость вызывать BaggageBuilder вручную в каждом обработчике активности.

В Python году регистрируйте багажное промежуточное ПО через ObservabilityHostingManager.configure(), а не напрямую на адаптере.

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

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

Middleware пропускает настройку багажа для асинхронных ответов (ContinueConversation событий), чтобы избежать перезаписи багажа, который уже задал исходный запрос.

Данные валидации течёт в продукте

Чтобы просматривать телеметрию агентов в Microsoft Purview или Microsoft Defender, убедитесь, что выполнены следующие требования:

Автоматическое инструментирование

Дистрибутив OpenTelemetry от Microsoft объединяет стандартные конвейеры OpenTelemetry с курируемым Microsoft инструментарием. Дистрибутив может собирать телеметрию приложений, телеметрию инфраструктуры, а также телеметрию агентов или генеративного ИИ в зависимости от языка и конфигурации.

Категория Что он охватывает
Трубопровод сигналов Трассировки, метрики и журналы.
Обнаружение ресурсов Служба, хост, облако и контекст выполнения Azure, где это поддерживается.
Инструментирование инфраструктуры HTTP, ASP.NET Core, Azure SDK, клиенты базы данных и платформы ведения журналов, где поддерживается.
Инструментирование создания искусственного интеллекта OpenAI, Azure OpenAI, Semantic Kernel, LangChain, пакет SDK для агентов OpenAI и платформа агента, где поддерживается.
Ручные области агентов Вызов агента, выполнение инструментов, вывод телеметрии и выходные данные, где поддерживается.
Экспортеры и процессоры Azure Monitor, Microsoft Agent 365, OTLP, выходные данные консоли, процессоры диапазонов, процессоры журналов и средства чтения метрик.

Покрытие инструментального анализа

Язык Стандартное инструментирование приложений Универсальный агент и инструментирование генеративным искусственным интеллектом
Python Ресурсы OpenTelemetry, процессоры, читатели, ведение журнала, метрики и трассировки. Semantic Kernel, пакет SDK для агентов OpenAI, Agent Framework, LangChain, набор Microsoft Agent 365 и области применения Microsoft Agent 365.
Node.js HTTP, Azure SDK, Функции Azure, MongoDB, MySQL, PostgreSQL, Redis, Bunyan и Winston. Пакет SDK для агентов OpenAI, LangChain, контекстные данные Microsoft Agent 365 и области Microsoft Agent 365.
.NET ASP.NET Core, HttpClient, клиент SQL, Azure SDK, обнаружение ресурсов, метрики и журналы. Semantic Kernel, OpenAI и Azure OpenAI, Agent Framework, функции Microsoft Agent 365 и контексты Microsoft Agent 365.

Автоматическое инструментирование прослушивает сигналы телеметрии, создаваемые поддерживаемыми библиотеками и фреймворками. Инструментирование вручную используется, когда приложению необходимо описать операции, связанные с агентом, такие как вызов, выполнение инструментов, вывод или асинхронные выходные данные.

Добавьте пользовательские источники OpenTelemetry, счетчики, процессоры или считыватели, когда ваше приложение излучает данные телеметрии, которые не охватываются встроенными инструментами.

Встроенные инструментальные библиотеки

Автоматическое инструментирование прослушивает данные телеметрии, создаваемые поддерживаемыми платформами, и пересылает его через конвейер OpenTelemetry дистрибутива. Для сценариев агента задайте багаж, например идентификатор клиента и идентификатор агента, прежде чем инструментированная платформа создает диапазоны.

Framework Python Node.js .NET
Семантическое ядро Поддерживается Не поддерживаются Поддерживается
SDK для OpenAI и OpenAI Agents Поддерживается Поддерживается Поддерживается
Платформа агента Поддерживается Не поддерживаются Поддерживается
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={
        "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},
    },
)

Платформа агента

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

Ручное инструментирование

Используйте ручное инструментирование, если автоматическое инструментирование не описывает операции агента в достаточной степени детализации. Ручные области позволяют приложению описывать распространенные действия агента согласованным образом для различных языков.

Объем Применение для
InvokeAgentScope Начало и завершение вызова агента.
ExecuteToolScope Вызов инструмента, сделанный агентом.
InferenceScope Операция вывода модели ИИ.
OutputScope Выходные данные, которые должны быть записаны после завершения исходной области.

Повторно используйте те же значения идентификаторов запроса и агента в области запроса, чтобы связанные данные телеметрии могли быть сопоставлены.

Вызов агента

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

Запуск инструмента

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)

Инференс

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

Выходные данные

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

Документация по продукту должна определять все требования к проверке для конкретных продуктов для этих областей.

Локальная валидация

Локальная проверка подтверждает, что приложение генерирует телеметрию до верификации назначения, связанного с конкретным продуктом. Используйте выходные данные консоли или локальную конечную точку OTLP, чтобы проверить, создаются ли трассировки, метрики и журналы.

Проверка с помощью локальной конечной точки OTLP

Настройте дистрибутив для отправки данных телеметрии локальному сборщику или другой конечной точке, совместимой с OTLP.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Проверка с помощью локальных выходных данных

Используйте локальные выходные данные, если необходимо подтвердить инструментирование перед отправкой телеметрии в удаленное место назначения.

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.

Просмотрите локальные выходные данные для диапазонов из ожидаемых источников, таких как HTTP-запросы, вызовы OpenAI или Azure OpenAI, области вызова агента, области выполнения инструментов или области вывода заключений. Проверка, специфичная для назначения, входит в документацию по продукту для этого назначения.

Ручная настройка аутентификации

При использовании экспортера Agent 365 необходимо предоставить механизм для предоставления токена аутентификации. Резолвер токенов работает по экспортной партии, используя идентификаторы агента и идентификатор арендатора из контекста активного багажа. Дистрибутив поддерживает два подхода.

Подсказка

Если вы строите агенты с Пакет SDK агентов Microsoft 365, см. Observability Authentication Setup for Agent SDK для пошаговых инструкций по настройке OBO и S2S токенов для агентных и неагентных агентов.

Ручной резольвер токенов

Используйте ручной резолвер при приобретении токенов вне конвейера Agent Framework, при создании приложений вне Agent Framework или при использовании аутентификации сервис-сервис (S2S) (поток учетных данных клиента). Агенты могут создавать токен самостоятельно, например, используя Microsoft Authentication Library (MSAL) или любой другой метод получения токенов, но им необходимо убедиться, что токен имеет правильную область наблюдаемости (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite).

Примечание.

Для аутентификации service-to-service (S2S) необходимо использовать этот ручной подход с резольвером токенов. Кэш агентных токенов поддерживает только аутентификационные потоки от имени (OBO).

Следующие примеры показывают паттерн резолвера токена OBO (on-name-of ) — агент получает пользовательский токен через агентский обработчик аутентификации и обменяет его на токен с областью видимости. Для примеров S2S (service-to-service) и сравнения аутентификации OBO и S2S см. раздел Observability Authentication Setup for Agent SDK.

Резольвер должен быть синхронным. Получите токен в вашем асинхронном обработчике активности (или через MSAL) и кэшируйте его для резолвера.

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

Агентный кэш токенов с приложениями Agent Framework

Для приложений Agent Framework, использующих аутентификацию от имени OBO, дистрибутив автоматически регистрируется IExporterTokenCache<AgenticTokenStruct> через DI, если вы не устанавливаете пользовательский TokenResolver. Ваш агент вызывает RegisterObservability() во время выполнения для предоставления учетных данных, а кэш занимается получением и обновлением токенов.

Примечание.

Этот подход поддерживает только потоки аутентификации от имени OBO. Для аутентификации service-to-service (S2S) используйте ручной резолвер токенов .

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

Атрибуты валидации хранения

Для успешной валидации в магазине ваш агент должен реализовать InvokeAgentScope, InferenceScope, и ExecuteToolScope. Каждая область соответствует операции span в канонической схеме:

Область применения SDK Работа пролета Универсальный код ссылки
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

Для полных обязательных и необязательных списков атрибутов по области области — включая семантику по атрибутам, рекомендации по выбору значений и какие атрибуты можно запросить Microsoft Defender расширенном поиске — см. Agent 365 attributability attribute reference. Столбец «Применимо» к определяет, к какой области принадлежит каждый атрибут, а столбец «Требуется » отличает атрибуты обязательных (M) от опциональных (O) атрибутов.

Испытайте своего агента с использованием наблюдаемости

После внедрения наблюдаемости проверьте, фиксируется ли телеметрия:

  1. Перейдите на https://admin.cloud.microsoft/#/agents/all.
  2. Выберите своего агента, а затем выберите «Активность».
  3. Проверьте, появляются ли сессии и вызовы инструментов.

Примеры приложений и расширенная конфигурация

Для рабочих образцов и расширенных опций конфигурации смотрите репозитории GitHub для каждого языка:

Troubleshooting

В этом разделе описываются распространённые проблемы при реализации и использовании дистрибутива Microsoft OpenTelemetry с Agent 365.

Подсказка

Руководство по устранению неполадок Agent 365 содержит рекомендации по решению неполадок на высоком уровне, лучшие практики и ссылки на контент по устранению неполадок для каждой части жизненного цикла разработки Agent 365.

Данные о наблюдаемости не отображаются

Симптомы:

  • Агент бежит
  • В административном центре нет телеметрии
  • Не вижу активности агентов

Первопричина.

  • Экспорт агента 365 не включён
  • Ошибки конфигурации
  • Проблемы с резолвером токенов

Решения: Попробуйте следующие шаги для решения проблемы:

  • Проверьте, экспорт агента 365 включён

    Вы должны явно включить экспортер Agent 365. Если не настроить его, дистрибутив может вернуться к экспортеру консоли или вообще ничего не экспортировать. Включите его в коде:

    from microsoft.opentelemetry import use_microsoft_opentelemetry

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

    Или установить переменную среды:

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    Примечание.

    ENABLE_A365_OBSERVABILITY_EXPORTER — это вторичный переключатель, который действует только при enable_a365=True задании в коде. Вы также можете управлять ею через a365_enable_observability_exporter кварга.

  • Check token resolver configuration

    Экспортер требует действительный резолвер токенов, который возвращает токен Bearer для каждого запроса на экспорт. Если резолвер токенов отсутствует или возвращается null, экспорт тихо пропускается.

  • Включите экспорт в консоль и проверьте телеметрию локально

    Добавьте консольный экспортер для проверки генерации телеметрии до того, как она достигнет конечной точки Agent 365:

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Включить подробное журналирование

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Проверьте логи на ошибки экспорта

    Используйте az webapp log tail команду для поиска ошибок, связанных с наблюдаемостью:

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

Отсутствующий идентификатор арендатора или идентификатор агента — пропущены периоды

Симптомы: Система бесшумно сбрасывает развязки и никогда их не экспортирует. Некоторые платформы фиксируют количество пропущенных отсеков или сообщение, например No spans with tenant/agent identity found. Другие сбрасывают их без логировки.

Решение:

  • До экспорта разделы дистрибутивов охватываются по идентичности арендатора и агента. Споведы без ID арендатора или ID агента удаляются и никогда не отправляются в сервис.
  • Убедитесь, BaggageBuilder что вы настроены с идентификатором арендатора и агента перед созданием споведов. Эти значения распространяются через контекст OpenTelemetry и присоединяются ко всем отсекам, созданным в области багажа. Для платформенно-специфичного API см. атрибуты Багаж.
  • Если вы используете промежуточное программное обеспечение багажа или включите контекстного помощника из интеграционного пакета хостинга, убедитесь, что у TurnContext активности есть действительный получатель с идентификатором агента.

Сбой разрешения токена — экспорт пропущен или неавторизован

Симптомы: Резолвер токенов возвращает null или выдает ошибку. В зависимости от платформы, экспорт либо полностью пропускается, либо не работает с HTTP 401.

Решение:

  • Требуется резольвер токенов. Если он отсутствует, экспортер выдает ошибку при запуске. Проверьте, что предоставлен резолвер токенов и возвращает действительный токен носителя.
  • Убедитесь, что правильный идентификатор арендатора и идентификатор агента передаются в BaggageBuilder, потому что эти значения передаются токен-резолверу.
  • Для агентов, размещённых на Azure, убедитесь, что управляемая идентичность имеет необходимое разрешение API для области наблюдаемости.
  • Для .NET-приложений, использующих пакет хостинга Agent Framework, обмен токенами осуществляется автоматически через DI. Если жетоны отсутствуют, убедитесь, что Microsoft.Agents.A365.Observability.Hosting установлен и зарегистрирован.

HTTP 401 Несанкционированный

Симптомы: Экспорт не удаётся с HTTP 401. Экспортер не повторяет эту ошибку.

Решение:

  • Проверьте, соответствует ли аудитория токена сфере обзора конечной точки.
  • Проверьте, не возвращает ли токен-резолвер делегированный пользовательский токен, токен для неправильной аудитории или истёкший токен.

HTTP 403 — запрещено

Симптомы: Экспорт не удаётся с HTTP 403. Экспортер не повторяет эту ошибку.

Коренная причина: Ошибка HTTP 403 может иметь разные причины. Проверьте следующие резолюции в порядке.

Решение:

  • Отсутствие лицензии — Убедитесь, что у вашего арендатора есть одна из следующих лицензий, присвоенных в Центр администрирования Microsoft 365:

    • Тест - Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Агент 365 Frontier

  • Отсутствие Agent365.Observability.OtelWrite разрешения — Дайте разрешение на вашу личность (управляемую личность или регистрацию приложения). Без неё экспорт телеметрии с HTTP 403 проваливается.

Дайте разрешение

Используйте один из этих вариантов:

  • Агент 365 CLI

    Требуется учётная запись глобального администратора; запускать из каталога проекта агентов, содержащего a365.config.json, или использовать --agent-name

    a365 setup permissions bot

    Или, без конфигурационного файла:

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

  • Entra Portal

    Конфигурационные файлы не требуются; требуется доступ Глобального администратора к регистрации приложения blueprint.

    1. Перейдите на Entra portal>Регистрация приложений> выберите приложение Blueprint.
    2. Перейти в раздел API-разрешения.>Добавить API.>Моя организация> использует поиск .9b975845-388f-4429-889e-eab1ef63949c
    3. Выберите «Делегированные права> » — отметьте Agent365.Observability.OtelWrite>«Добавить права».
    4. Повторите шаги 2–3, на этот раз выберите «Разрешения> приложений», Agent365.Observability.OtelWrite> «Добавить права».
    5. Нажмите «Дать согласие администратора » и подтвердить.

    И Agent365.Observability.OtelWrite (Делегировано), и Agent365.Observability.OtelWrite (Заявка) должны показывать Granted статус.

Ошибки HTTP 429 или 5xx — временные ошибки

Симптомы: Экспорт не удаётся с временным HTTP-кодом статуса, таким как 429 или 5xx.

Решение:

  • Эти ошибки обычно временные и разрешаются сами по себе. Дистрибутивы Python и JavaScript автоматически перепробовывают коды статуса HTTP 408, 429 и 5xx. Дистрибутив .NET не повторяется автоматически.
  • Если ошибки сохраняются, проверьте панель управления состоянием сервиса.
  • Рассмотрите возможность снижения частоты экспорта, увеличив запланированную задержку между партиями или максимальный размер экспортной партии. Для Python и JavaScript используйте соответствующие параметры exporterOptions или a365_*, задокументированные в репозиториях GitHub. Для .NET используйте o.Agent365.Exporter.ScheduledDelayMilliseconds и o.Agent365.Exporter.MaxExportBatchSize.

Экспортный тайм-аут

Симптомы: Попытки экспорта выходят за тайм-аут.

Решение:

  • Проверьте сетевое подключение к конечной точке наблюдаемости.

  • Стандартный тайм-аут для HTTP-запросов — 30 секунд на всех платформах. Если тайм-ауты случаются часто, увеличьте значение тайм-аута в ваших экспортерских опциях:

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

    Смотрите репозиторий Python для полного списка вариантов a365_*.

Экспорт успешен, но телеметрия отсутствует в Defender или Purview

Симптомы: Логи показывают успешный экспорт (HTTP 200), но телеметрия не видна в Microsoft Defender или Microsoft Purview.

Решение:

  • Убедитесь, что вы соответствуете требованиям для просмотра экспортированных логов:
  • Телеметрия может заполняться за несколько минут после успешного экспорта. Подождите, прежде чем продолжать расследование.
  • Проверьте, содержат ли spans валидные microsoft.tenant.id и gen_ai.agent.id атрибуты. Отсутствие атрибутов идентичности приводит к тому, что spans теряются на сервере, даже если экспорт HTTP возвращает 200.

Связанный контент

  • Last updated on