Microsoft OpenTelemetry Distro

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

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

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

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

Установка и конфигурация

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

Установка библиотеки

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

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

pip install microsoft-opentelemetry

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

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

Вызовите 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().

Параметр Описание По умолчанию
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, убедитесь, что выполнены следующие требования:

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

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

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

Покрытие инструментирования

Language Инструментирование распространенных приложений Инструментирование распространенных агентов и генеративного ИИ
Python Ресурсы, процессоры, ридеры, ведение журналов, метрики и трассировки OpenTelemetry. Semantic Kernel, OpenAI Agents SDK, Agent Framework, LangChain, багаж Microsoft Agent 365 и области действия Microsoft Agent 365.
Node.js HTTP, Azure SDK, функции Azure, MongoDB, MySQL, PostgreSQL, Redis, Bunyan и Winston. OpenAI Agents SDK, LangChain, багаж Microsoft Agent 365 и области действия Microsoft Agent 365.
.NET ASP.NET Core, HttpClient, SQL Client, Azure SDK, обнаружение ресурсов, метрики и журналы. Semantic Kernel, OpenAI and Azure OpenAI, Agent Framework, багаж Microsoft Agent 365 и области действия Microsoft Agent 365.

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

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

Важно

Автоматическая инструментализация заполняет только стандартные атрибуты OpenTelemetry. Он не включает все атрибуты, требуемые Agent 365. Вы должны добавить атрибуты, характерные для Microsoft, через BaggageBuilder. Чтобы узнать, какие атрибуты требуются, см. Сохраните атрибуты проверки.

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

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

Платформа Python Node.js .NET
Semantic Kernel Поддерживается Неподдерживаемые Поддерживается
OpenAI и SDK агентов OpenAI Поддерживается Поддерживаемые Поддерживается
Agent Framework Поддерживается Неподдерживаемые Поддерживается
LangChain Поддерживается Поддерживается Отсутствует в списке

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

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

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

Действия Для чего используется
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

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

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

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

Примечание.

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

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

Примечание.

Этот подход поддерживает только потоки аутентификации OBO («от имени»). Для аутентификации 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 с Agent 365.

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

Совет

Руководство по устранению неполадок 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

    Примечание.

    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, так как эти значения далее направляются сопоставителю маркеров.
  • Для агентов, размещенных на Azure, проверьте, что управляемый идентификатор имеет необходимые разрешения API для области наблюдаемости.
  • Для .NET-приложений, использующих пакет хостинга Agent Framework, обмен маркерами автоматически происходит через DI. Если маркеры отсутствуют, убедитесь, что Microsoft.Agents.A365.Observability.Hosting установлен и зарегистрирован.

HTTP 401 Не авторизовано

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

Решение:

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

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

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

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

Решение:

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

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

  • Agent 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 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.

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

  • Last updated on