Microsoft OpenTelemetry Distro

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

Note

Если вы поддерживаете существующую интеграцию с использованием более раннего SDK Agent 365 Observability, ознакомьтесь с устаревшей документацией SDK и руководствами по миграции.

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

Дистрибутив 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

Configuration

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

По умолчанию дистрибутив экспортируется по делегированному маршруту, для которого требуется Agent365.Observability.OtelWrite полное разрешение и согласие администратора. Команда a365 setup all не настраивает это право для blueprint agents, поэтому используйте S2S с резолвером только для приложений для этих агентов. Зарегистрированный экземпляр агента может экспортировать по маршруту S2S без разрешения на Observability или согласия администратора.

Вызовите 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_* kwargs в функцию use_microsoft_opentelemetry().

Parameter Description Default
a365_use_s2s_endpoint При True используется путь конечной точки «служба-служба» (service-to-service). Используйте токен-резолвер только для приложения. 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)

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

Убедитесь, что данные поступают в продукт

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

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

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

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

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

Language Стандартное инструментирование приложений Универсальный агент и инструментирование генеративным искусственным интеллектом
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. Он не включает все атрибуты, требуемые Agent 365. Вы должны добавить атрибуты, характерные для Microsoft, через BaggageBuilder. Чтобы узнать, какие атрибуты требуются, см. Сохраните атрибуты проверки.

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

Автоматическое инструментирование прослушивает данные телеметрии, создаваемые поддерживаемыми платформами, и пересылает его через конвейер 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

Note

Автоматическое инструментирование для платформы LangChain также поддерживает LangGraph и Deep Agent. То же инструментирование автоматически записывает данные телеметрии для агентов, созданных с помощью любой из этих платформ.

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

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

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

Scope Применение для
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 необходимо реализовать механизм для передачи маркера аутентификации. Сопоставитель маркеров работает для каждой партии экспорта, используя идентификатор агента и идентификатор арендатора из активного контекста багажа. Дистрибутив поддерживает два подхода.

Для агентов blueprint с поддержкой Agent 365, настроенных на a365 setup all, используйте S2S с резолвером только для приложения. Встроенный кэш агентских токенов и примеры OBO на этой странице используют делегированный маршрут, для которого требуется делегированное Agent365.Observability.OtelWrite разрешение и согласие администратора. Команда не настраивает это разрешение для агентов a365 setup all blueprint.

Tip

Если вы разрабатываете агенты с помощью пакета SDK агентов Microsoft 365, см. раздел Настройка аутентификации для наблюдаемости в пакете SDK агентов для пошаговых инструкций по настройке получения маркеров OBO (от имени пользователя) и S2S (служба-служба) как для агентных, так и для безагентных решений.

Ручной сопоставитель маркеров

Используйте ручной резолвер при приобретении токенов вне конвейера Agent Framework, при создании приложений вне Agent Framework или при использовании аутентификации service-to-service (S2S). Токен, который возвращает резолвер, должен совпадать с маршрутом. Для делегированного маршрута возвращайте делегированный жетон с Agent365.Observability.OtelWrite прицелом. Для S2S-маршрута возвращайте последний токен только для приложения, который вы запрашиваете с api://9b975845-388f-4429-889e-eab1ef63949c/.default помощью прицела. Зарегистрированному агенту Blueprint на S2S не требуется разрешение роли Agent365.Observability.OtelWrite или администратора.

Note

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

В приведённых ниже примерах показан паттерн сопоставителя маркеров OBO (от имени) — агент получает пользовательский маркер через агентный обработчик аутентификации и обменивает его на маркер, предназначенный для наблюдаемости. Для таких примеров требуется делегированное Agent365.Observability.OtelWrite разрешение и согласие администратора. Для примеров S2S (служба-служба) и сравнения аутентификации OBO и S2S см. раздел Настройка аутентификации для наблюдаемости в пакете 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() во время выполнения для предоставления учетных данных, а кэш занимается делегированным получением и обновлением токенов.

Note

Этот подход поддерживает только потоки аутентификации от имени OBO по делегированному маршруту, для чего требуется делегированное Agent365.Observability.OtelWrite разрешение и согласие администратора. Для аутентификации service-to-service (S2S), включая blueprint-агенты, настроенные с a365 setup all, используйте ручной токен-резолвер с токеном, используемым только для приложения. Для этапов настройки см. раздел «Агент 365 с поддержкой 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. Каждая область соответствует операции спана в канонической схеме:

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

Справочник по атрибутам включает обязательные и необязательные параметры для каждой области, семантику, рекомендации по значениям и информацию о доступности для расширенного поиска в Microsoft Defender. Подробные сведения доступны в разделе Справочник по атрибутам наблюдаемости Agent 365. В столбце Применяется указывается, к какой области действия относится каждый атрибут, а в столбце Обязательный проводится различие между обязательными (M) и необязательными (O) атрибутами.

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

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

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

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

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

Справочник по программированию

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

Troubleshooting

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

Проблема. Description
Данные о наблюдаемости не отображаются Телеметрия не видна, потому что экспорт Agent 365 не включён, настройка не завершена или разрешение токена не работает.
Отсутствует ИД арендатора или ИД агента - спаны пропущены Спаны исключаются из экспорта, если отсутствуют обязательные атрибуты идентификации арендатора или агента.
Ошибка разрешения маркера — экспорт пропущен или неавторизован Экспорт не выполняется или отклоняется, если сопоставитель маркеров не возвращает маркер или возникает ошибка при его получении.
Http 401 Несанкционированный доступ Запросы поступают на сервис, но аутентификация не проходит, потому что маркер недействителен, истёк или не соответствует аудитории.
HTTP 403 Запрещено Авторизация не проходит из-за отсутствия лицензии арендатора, незарегистрированной личности S2S или разрешения на запись на наблюдаемость там, где это необходимо.
HTTP 403 Forbidden — несоответствие идентификатора агента Сервис отклоняет экспорт, если идентификатор агента в запросе не совпадает с идентификатором агента, авторизованного с помощью маркера.
Ошибки HTTP 429 или 5xx — временные ошибки Временное троттлинг или нестабильность бэкенда прерывают экспорт и могут потребовать повторных попыток или пакетной настройки.
Истечение времени ожидания экспорта Операции экспорта не укладываются в лимиты тайм-аута из-за сетевых задержек или медленного ответа конечных точек.
Экспорт успешно выполнен, но телеметрия не отображается в Defender или Purview Приём данных проходит успешно, но видимость задерживается или блокируется из-за предварительных требований и требований схемы.

Tip

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

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

Симптомы:

  • Агент запущен
  • В административном центре нет телеметрии
  • Активность агента не отображается

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

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

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

  • Проверьте, что экспорт Agent 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

    Note

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

  • Проверьте конфигурацию сопоставителя маркеров

    Экспортер требует валидный сопоставитель маркеров, который возвращает маркер носителя для каждого запроса на экспорт. Если сопоставитель маркеров отсутствует или возвращает 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. Другие отбрасывают их без регистрации в журнале.

Решение:

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

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

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

Решение:

  • Требуется сопоставитель маркеров. Если он отсутствует, экспортер выдает ошибку при запуске. Убедитесь, что сопоставитель маркеров предоставлен и возвращает действительный маркер носителя.
  • Убедитесь, что правильные идентификаторы арендатора и агента передаются в BaggageBuilder, так как эти значения далее направляются сопоставителю маркеров.
  • Для S2S верните окончательный токен наблюдаемости, предназначенный только для приложения, для 9b975845-388f-4429-889e-eab1ef63949c или api://9b975845-388f-4429-889e-eab1ef63949c. Не возвращайте промежуточное утверждение чертежа, токен blueprint, пользовательский или OBO-токен.
  • Для делегированного маршрута возвращайте делегированный жетон с Agent365.Observability.OtelWrite прицелом.
  • Для агентов, размещённых на Azure, которые экспортируют напрямую с управляемой идентичностью, проверьте, что управляемая идентичность выполняет Agent365.Observability.OtelWrite роль приложения. Зарегистрированные агенты Blueprint на S2S не нуждаются в этом.
  • Для .NET-приложений, использующих пакет хостинга Agent Framework, обмен маркерами автоматически происходит через DI. Если маркеры отсутствуют, убедитесь, что Microsoft.Agents.A365.Observability.Hosting установлен и зарегистрирован.

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

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

Решение:

  • Проверьте, что аудитория токена — 9b975845-388f-4429-889e-eab1ef63949c это или api://9b975845-388f-4429-889e-eab1ef63949c, и что тип токена совпадает с маршрутом: делегированный токен для делегированного маршрута или токен только для приложения для маршрута S2S.
  • Для S2S проверьте, не возвращает ли резольвер делегированный пользовательский токен, промежуточное утверждение blueprint, токен blueprint, токен для неправильной аудитории или истёкший токен.
  • Для делегированного маршрута проверьте, содержит ли претензия scpAgent365.Observability.OtelWrite токена и что токен не истек.

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

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

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

Решение:

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

    • Тест - Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Agent 365 Frontier

  • Незарегистрированная личность на S2S — зарегистрированный агент blueprint может экспортировать по маршруту S2S с токеном, используемым только для приложения, который не Agent365.Observability.OtelWrite имеет роли. Если идентификация не зарегистрирована у Агента 365, сервис возвращает HTTP 403 insufficient_scope. Для blueprint агентов a365 setup all регистрируется экземпляр агента. Чтобы попробовать повторить неудачную регистрацию, забегайте a365 setup all --agent-registration-only. Создание идентичности Microsoft Entra само по себе не регистрирует экземпляр агента.

  • Отсутствие Agent365.Observability.OtelWrite разрешения там, где это необходимо — предоставьте разрешение на делегированный маршрут или для незарегистрированных личностей, включая стандартные регистрации в приложениях. Зарегистрированным агентам чертежей на S2S это разрешение не нужно.

Предоставление разрешения

Предоставляйте Agent365.Observability.OtelWrite только при использовании делегированного маршрута или незарегистрированной личности. Зарегистрированным агентам Blueprint, использующими S2S, не требуется это разрешение или согласие администратора. Предоставьте только тот тип разрешения, который используется в вашем маршруте:

  • Делегированный маршрут: Добавьте делегированное разрешение.
  • Маршрутизация S2S с незарегистрированной идентификацией, например, стандартной регистрацией приложения, используемой пользовательским агентом движка: Добавить разрешение приложения (роль приложения).

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

  • Агент 365 CLI (чертежные агенты по делегированному маршруту)

    Эта команда добавляет делегированное разрешение к вашему чертежу и его наследуемым правам, а затем даёт согласие администратора. Разрешение приложения не добавляется. Для этого требуется учётная запись глобального администратора. Выполните команду из каталога проекта агента, содержащего a365.config.json, или добавьте --agent-name "<agent-name>".

    a365 setup permissions custom --resource-app-id 9b975845-388f-4429-889e-eab1ef63949c --scopes Agent365.Observability.OtelWrite

  • Центр администрирования Microsoft Entra (любой вариант)

    Конфигурационные файлы не требуются; требуется доступ Глобального администратора к регистрации приложения. Для чертежа на делегированном маршруте используйте эту опцию только если в чертеже уже есть API наблюдаемости в наследуемых правах, например, чертеж, установленный в более ранней версии CLI. В противном случае используйте Agent 365 CLI.

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

    Разрешение, которое вы добавили, показывает Granted статус.

HTTP 403 Forbidden — несоответствие идентификатора агента

Симптомы: Экспорт завершился ошибкой HTTP 403 и серверным сообщением, аналогичным 403 Forbidden с agent-ID-mismatch ошибками при обращении к конечным точкам трассировки Agent 365.

Основная причина: эта ошибка возникает, если используется идентификатор клиента схемы вместо идентификатора клиента экземпляра агента при настройке сведений об агенте. Идентификатор агента в URL экспорта не соответствует идентификатору, авторизованному маркером, поэтому конечная точка трассировки отклоняет запрос.

Решение:

  • Убедитесь, что идентификатор арендатора добавлен в список разрешённых арендаторов Agent 365.
  • Задайте сведения об агенте с идентификатором клиента экземпляра агента (а не идентификатором клиента схемы).
  • Проверьте сгенерированный URL для экспорта — он записывается в журнал при включённом ведении журнала. Убедитесь, что идентификатор агента в URL совпадает с идентификатором клиента экземпляра агента.
  • Чтобы включить журнал ведения диагностики для пакета SDK, см. Локальная проверка.

Ошибки 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.

Решение:

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

Связанные материалы

  • Последнее обновление: