Microsoft OpenTelemetry 发行版

Microsoft OpenTelemetry 发行版是一个统一的可观测性发行版，可提供从智能体和非智能体应用程序收集跟踪、指标和日志的单一入门体验。 它为 Microsoft Agent 365、Microsoft Foundry、Azure Monitor 以及任何兼容 OpenTelemetry 协议 (OTLP) 的后端提供可观测性支持。 该发行版支持 .NET、Node.js 和 Python，并通过一次导入和一次配置调用替代跨多个可观测性堆栈的碎片化设置。

关键优势

Microsoft OpenTelemetry 发行版提供以下优势：

  • 一个包，一个 API：将多个导出程序和检测包替换为单个依赖项。
  • 多后端支持：同时将遥测数据发送到 Azure Monitor、任何兼容 OpenTelemetry 协议 (OTLP) 的终结点（例如 Datadog、Grafana 或 New Relic）以及 Microsoft Agent 365。
  • 内置检测：将自动检测用于 HTTP、数据库、Azure SDK、Azure Functions 等，无需额外配置。
  • 基于标准：基于 OpenTelemetry，这是行业标准可观测性框架。
  • 最少样板：向应用程序入口点添加一个导入和一个函数调用。

安装和配置

本指南向您显示如何使用 Microsoft OpenTelemetry 发行版向您的应用程序添加可观测性。 Distro 会自动收集包含内置检测的跟踪、指标和日志，并将遥测导出到 Azure Monitor、任何 OpenTelemetry 协议 (OTLP) 终结点或 Microsoft Agent 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_* kwargs 传递给 use_microsoft_opentelemetry() 自定义导出程序行为。

参数 描述 默认值
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 监视体验。

Baggage 属性

使用 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

要从 TurnContext 自动填充 BaggageBuilder，请在 microsoft-opentelemetry 包中使用 populate 辅助程序。 此帮助程序会自动从活动中提取调用者、智能体、租户、渠道和会话详细信息。

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

Baggage 中间件

如果您的智能体使用托管集成包，请注册 Baggage 中间件，以便自动为每个传入请求填充 Baggage。 此步骤无需在每个活动处理程序中手动调用 BaggageBuilder。

在 Python 中，通过 ObservabilityHostingManager.configure()（而不是直接在适配器上）注册 Baggage 中间件。

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 精选的检测组合。 发行版可以根据语言和配置收集应用遥测数据、基础结构遥测数据以及智能体或生成式 AI 遥测数据。

类别 涵盖内容
信号管道 跟踪、指标和日志。
资源检测 服务、主机、云和 Azure 运行时上下文（视支持情况而定）。
基础结构检测 HTTP、ASP.NET Core、Azure SDK、数据库客户端和记录框架（视支持情况而定）。
生成式 AI 检测 OpenAI、Azure OpenAI、语义内核、LangChain、OpenAI Agents SDK 和 Agent Framework（视支持情况而定）。
手动智能体范围 智能体调用、工具执行、推理和输出遥测数据（视支持情况而定）。
导出程序和处理器 Azure Monitor、Microsoft Agent 365、OTLP、控制台输出、Span 处理器、日志处理器和指标读取器。

检测覆盖范围

语言 常见应用程序检测 常见的智能体与生成式 AI 检测
Python OpenTelemetry 资源、处理器、读取器、日志记录、指标和跟踪。 语义内核、OpenAI 智能体 SDK、Agent Framework、LangChain、Microsoft Agent 365 负载和 Microsoft Agent 365 范围。
Node.js HTTP、Azure SDK、Azure Functions、MongoDB、MySQL、PostgreSQL、Redis、Bunyan 和 Winston。 OpenAI 智能体 SDK、LangChain、Microsoft Agent 365 负载和 Microsoft Agent 365 范围。
.NET ASP.NET Core、HttpClient、SQL 客户端、Azure SDK、资源检测、指标和日志。 语义内核、OpenAI 和 Azure OpenAI、Agent Framework、Microsoft Agent 365 负载和 Microsoft Agent 365 范围。

自动检测侦听由支持的库和框架发出的遥测信号。 当应用程序需要描述特定于智能体的操作（例如调用、工具执行、推理或异步输出）时，使用手动检测。

当您的应用程序发出内置检测未覆盖的遥测数据时，添加自定义 OpenTelemetry 源、计量器、处理器或读取器。

重要提示

自动检测仅填充标准的 OpenTelemetry 属性。 它不包含 Agent 365 所需的所有属性。 您必须通过 BaggageBuilder 添加特定于 Microsoft 的属性。 若要查看需要哪些属性，请参阅存储验证属性。

内置检测库

自动检测监听由支持的框架发出的遥测，并通过 Distro 的 OpenTelemetry 管道转发数据。 对于智能体场景，在检测的框架创建跨度之前设置负载，如租户 ID 和智能体 ID。

框架 Python Node.js .NET
语义内核 受支持 不支持 受支持
OpenAI 和 OpenAI 智能体 SDK 受支持 支持 受支持
Agent Framework 受支持 不支持 受支持
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},
    },
)

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 AI 模型推理操作。
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 导出程序时，必须提供获取身份验证令牌的机制。 令牌解析器使用活动负载上下文中的智能体 ID 和租户 ID 按导出批次工作。 发行版支持两种方法。

提示

如果您正在使用 Microsoft 365 智能体 SDK 生成智能体，请参考 智能体 SDK 的可观测性身份验证设置，以获取有关为智能体的和非智能体的智能体配置 OBO 和 S2S 令牌获取的分步说明。

手动令牌解析器

请在以下情况下使用手动解析器：在 Agent Framework 管道外部获取令牌时、生成非 Agent Framework 应用时，或使用服务到服务 (S2S) 身份验证（客户端凭据流）时。 智能体可以自行生成令牌，例如使用 Microsoft 身份验证库 (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 应用的智能体令牌缓存

对于使用代理 (OBO) 身份验证的 Agent Framework 应用，如果未设置自定义 TokenResolver，Distro 会通过 DI 自动注册 IExporterTokenCache<AgenticTokenStruct>。 您的智能体在运行时调用 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 时的常见问题。

难题 描述
可观测性数据未显示 遥测数据未显示，因为未启用 Agent 365 导出、设置未完成或令牌解析失败。
缺少租户 ID 或智能体 ID - 跨域被跳过 当缺少所需的租户或智能体标识属性时，将在导出前筛选出数据段。
令牌解析失败 - 导出被跳过或未授权 当令牌解析器在令牌获取过程中未返回令牌或错误时，会跳过或拒绝导出。
HTTP 401 未授权 请求到达服务，但由于令牌无效、过期或用于错误的访问群体，身份验证失败。
HTTP 403 已禁止 由于缺少租户许可或可观测性写入权限，授权失败。
HTTP 403 已禁止 - 智能体 ID 不匹配 当请求中的智能体 ID 与令牌授权的智能体标识不匹配时，服务会拒绝导出。
HTTP 429 或 5xx 错误 - 临时性错误 临时限制或后端不稳定可能导致导出中断，并可能需要重试或批量调优。
导出超时 由于网络延迟或终结点响应延迟，导出操作超出超时限制。
导出成功，但遥测数据未显示在 Defender 或 Purview 中 数据引入成功，但可见性因下游先决条件和架构要求而出现延迟或阻止。

提示

Agent 365 故障排除指南 包含高层次的故障排除建议、最佳实践，以及针对 Agent 365 开发生命周期各阶段的故障排除内容链接。

可观测性数据未显示

症状：

  • 智能体正在运行
  • 管理中心中无遥测数据
  • 看不到智能体活动

根本原因：

  • Agent 365 导出未启用
  • 配置错误
  • 令牌解析器问题

解决方案：请尝试以下步骤来解决问题：

  • 验证 Agent 365 导出是否已启用

    您必须明确启用 Agent 365 导出程序。 如果您未设置，Distro 可能会回退到控制台导出程序或完全不导出内容。 在代码中启用它：

    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 kwarg 控制它。

  • 检查令牌解析器配置

    导出程序需要一个有效的令牌解析器，该解析器会为每次导出请求返回一个持有者令牌。 如果令牌解析器缺失或返回 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"

缺少租户 ID 或智能体 ID — 跳过跨度

症状：系统会静默丢弃数据段，且从未导出。 某些平台会记录已跳过的数据段或消息计数，例如 No spans with tenant/agent identity found。 其他应用会将其删除，不会记录。

解决方法：

  • 在导出之前，Distro 会根据租户和智能体身份对跨度进行分区。 缺少租户 ID 或智能体 ID 的跨度会被删除，永远不会发送到服务。
  • 在创建跨度之前，请确保 BaggageBuilder 已配置租户 ID 和智能体 ID。 这些值会通过 OpenTelemetry 上下文传播，并附加到行李作用域内创建的所有跨度上。 有关特定于平台的 API，请参阅 Baggage 属性。
  • 如果您使用负载中间件，或启用托管集成包中的上下文助手，确认 TurnContext 活动有具有智能体身份的有效接收者。

令牌解析失败 — 导出被跳过或未授权

症状：令牌解析器返回 null 或引发错误。 导出要么完全跳过，要么因 HTTP 401 而失败，具体取决于平台。

解决方法：

  • 需要令牌解析器。 如果缺失，导出程序在启动时会引发错误。 验证令牌解析器已提供，并返回有效的持有者令牌。
  • 请确保将正确的租户 ID 和智能体 ID 传递到 BaggageBuilder，因为这些值会转发给令牌解析器。
  • 对于 Azure 托管的智能体，请验证托管身份是否具有可观测性作用域所需的 API 权限。
  • 对于使用 Agent Framework 托管包的 .NET 应用，令牌交换通过 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 门户

    无配置文件；需要全局管理员访问权限以访问蓝图应用注册。

    1. 转到 Entra 门户>应用注册>，然后选择您的蓝图应用。
    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 已禁止 - 智能体 ID 不匹配

症状：导出失败，返回 HTTP 403 错误及类似 403 Forbidden 的服务器消息，且在调用 Agent 365 跟踪端点时出现 agent-ID-mismatch 失败。

根本原因：在设置智能体详细信息时，如果使用蓝图客户端 ID 而不是智能体实例客户端 ID，会出现此错误。 导出 URL 中的智能体 ID 与令牌授权的标识不匹配，因此跟踪终结点会拒绝请求。

解决方法：

  • 验证租户 ID 是否已添加到 Agent 365 的允许租户列表中。
  • 使用智能体实例客户端 ID（而不是蓝图客户端 ID）设置智能体详细信息。
  • 验证生成的导出 URL - 如果启用日志记录器，它会被记录。 确认 URL 中的智能体 ID 与智能体实例客户端 ID 匹配。
  • 若要启用每个 SDK 的诊断日志记录，请参阅本地验证。

HTTP 429 或 5xx 错误 - 临时性错误

症状：导出因临时性 HTTP 状态代码（例如 429 或 5xx）而失败。

解决方法：

  • 这些错误通常是临时性的，会自行解决。 Python 和 JavaScript 发行版会自动针对 HTTP 408、429 和 5xx 状态代码进行重试。 .NET 发行版不会自动重试。
  • 如果错误仍然存在，请查看服务运行状况仪表板。
  • 考虑通过增加批次间的计划延迟或最大导出批次大小来降低导出频率。 对于 Python 和 JavaScript，使用在 GitHub 存储库中记录的相关 exporterOptions 或 a365_* 参数。 对于 .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
)

    有关 a365_* 选项的完整列表，请参阅 Python 存储库。

导出成功，但遥测数据未显示在 Defender 或 Purview 中

症状：日志显示导出成功 (HTTP 200)，但遥测数据在 Microsoft Defender 或 Microsoft Purview 中不可见。

解决方法：

  • 验证您满足查看已导出日志的先决条件：
  • 遥测数据在成功导出后，可能需要几分钟才能填充。 稍等片刻，然后再进一步调查。
  • 验证数据段包含有效的 microsoft.tenant.id 和 gen_ai.agent.id 属性。 缺少身份属性会导致服务器端忽略跨度，即使 HTTP 导出返回 200。

相关内容

  • Last updated on