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 代理 365。
  • 内置检测：对 HTTP、数据库、Azure SDK、Azure Functions等使用自动检测，无需额外配置。
  • 基于标准的：基于 OpenTelemetry 构建的行业标准可观测性框架。
  • 最小样本：向应用程序入口点添加一个导入和一个函数调用。

安装和配置

本指南介绍如何使用 Microsoft OpenTelemetry 发行版向应用程序添加可观测性。 发行版会自动收集包含内置工具的跟踪、指标和日志，并将遥测数据导出到 Azure Monitor、任何 OpenTelemetry 协议（OTLP）终结点或 Microsoft 代理 365。

安装库

若要开始使用 Microsoft OpenTelemetry 发行版，请使用语言的包管理器为开发平台安装相应的库。

Prerequisites： Python 3.10 或更高版本。

pip install microsoft-opentelemetry

Configuration

代理 365 导出程序无需使用连接字符串。 它根据租户自动发现其终结点。 若要启用导出到代理 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()自定义导出程序行为。

Parameter Description 默认
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

传播上下文

若要跨分布式代理 365 操作保持可观测性，需要传播上下文。 通过代理和服务传播上下文时，可确保跟踪、日志和指标在整个请求生命周期中正确关联。 若要获得完整而有效的 Microsoft 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 发行版将标准 OpenTelemetry 管道与 Microsoft 精心策划的仪器化相结合。 发行版可以根据语言和配置收集应用程序遥测数据、基础设施遥测数据以及代理或生成 AI 的遥测数据。

类别 它涵盖的内容
信号管道 跟踪、指标和日志。
资源检测 支持的服务、主机、云和Azure运行环境上下文。
基础结构检测 支持 HTTP、ASP.NET Core、Azure SDK、数据库客户端和日志记录框架。
生成式 AI 工具 OpenAI、Azure OpenAI、语义内核、LangChain、OpenAI Agents SDK，以及在支持的情况下的代理框架。
手动代理范围 支持的代理调用、工具执行、推理和遥测输出。
出口商和加工商 Azure Monitor、Microsoft Agent 365、OTLP、控制台输出、跨度处理器、日志处理器和指标读取器。

工具化覆盖率

语言 常见应用程序检测 通用代理和生成 AI 工具
Python OpenTelemetry 资源、处理器、读取器、日志记录、指标和跟踪。 语义内核、OpenAI 代理 SDK、代理框架、LangChain、Microsoft 代理 365 负载和 Microsoft 代理 365 范围。
Node.js HTTP、Azure SDK、Azure Functions、MongoDB、MySQL、PostgreSQL、Redis、Bunyan 和 Winston。 OpenAI Agents SDK、LangChain、Microsoft Agent 365 配件和 Microsoft Agent 365 范围。
.NET ASP.NET Core、HttpClient、SQL 客户端、Azure SDK、资源检测、指标和日志。 语义内核、OpenAI 和 Azure OpenAI、Agent Framework、Microsoft Agent 365 baggage 和 Microsoft Agent 365 scopes。

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

当您的应用程序发出不在内置仪器涵盖范围内的遥测数据时，请添加自定义的 OpenTelemetry 源、计量器、处理器或读取器。

内置检测库

自动化仪器化监听由支持的框架发出的遥测数据，并通过发行版的 OpenTelemetry 管道转发这些数据。 对于代理情形，请在检测框架创建跨度之前设置行李，例如租户 ID 和代理 ID。

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

手动仪器

当自动监测无法详尽描述代理操作时，请使用手动监测。 通过手动范围，应用程序可以跨语言以一致的方式描述常见代理活动。

Scope 用于
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 调用、代理调用范围、工具执行范围或推理范围。 特定目的地的验证应包含在该目的地的产品文档中。

手动设置身份验证

使用代理 365 导出程序时，必须提供一种提供身份验证令牌的机制。 令牌解析器根据活动行李上下文中的代理 ID 和租户 ID 进行导出批次工作。 发行版支持三种方法。

手动的令牌解析器

在代理框架管道外部获取令牌或生成非代理框架应用时，请使用手动解析程序。

解析程序必须是 同步的。 获取异步活动处理程序中的令牌，并将其缓存给解析程序。

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 应用，未设置自定义IExporterTokenCache<AgenticTokenStruct>时，发行版会自动通过 DI 注册TokenResolver。 代理在运行时调用 RegisterObservability() 以提供凭据，缓存处理令牌获取和刷新。

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。 每个范围都需要以下属性或可选属性。

InvokeAgentScope

属性 Status
gen_ai.agent.id Required
gen_ai.agent.name Required
gen_ai.operation.name Required
gen_ai.input.messages Required
gen_ai.output.messages Required
gen_ai.conversation.id Required
microsoft.tenant.id Required
microsoft.a365.agent.blueprint.id Required
microsoft.agent.user.id Required
microsoft.agent.user.email Required
microsoft.channel.name Required
user.id Required
user.email Required
client.address Required
server.address Required
server.port Required
error.type Optional
gen_ai.agent.description Optional
gen_ai.agent.version Optional
microsoft.a365.agent.platform.id Optional
microsoft.channel.link Optional
microsoft.conversation.item.link Optional
microsoft.session.id Optional
microsoft.session.description Optional
user.name Optional
microsoft.a365.caller.agent.id Optional
microsoft.a365.caller.agent.name Optional
microsoft.a365.caller.agent.blueprint.id Optional
microsoft.a365.caller.agent.platform.id Optional
microsoft.a365.caller.agent.user.email Optional
microsoft.a365.caller.agent.user.id Optional
microsoft.a365.caller.agent.version Optional

ExecuteToolScope

属性 Status
gen_ai.agent.id Required
gen_ai.agent.name Required
gen_ai.operation.name Required
gen_ai.tool.name Required
gen_ai.tool.call.id Required
gen_ai.tool.call.arguments Required
gen_ai.tool.call.result Required
gen_ai.tool.type Required
gen_ai.conversation.id Required
microsoft.tenant.id Required
microsoft.a365.agent.blueprint.id Required
microsoft.agent.user.id Required
microsoft.agent.user.email Required
microsoft.channel.name Required
user.id Required
user.email Required
client.address Required
error.type Optional
gen_ai.agent.description Optional
gen_ai.agent.version Optional
gen_ai.tool.description Optional
microsoft.a365.agent.platform.id Optional
microsoft.channel.link Optional
microsoft.conversation.item.link Optional
microsoft.session.id Optional
microsoft.session.description Optional
server.address Optional
server.port Optional
user.name Optional

InferenceScope

属性 Status
gen_ai.agent.id Required
gen_ai.agent.name Required
gen_ai.operation.name Required
gen_ai.input.messages Required
gen_ai.output.messages Required
gen_ai.request.model Required
gen_ai.provider.name Required
gen_ai.conversation.id Required
microsoft.tenant.id Required
microsoft.a365.agent.blueprint.id Required
microsoft.agent.user.id Required
microsoft.agent.user.email Required
microsoft.channel.name Required
user.id Required
user.email Required
client.address Required
error.type Optional
gen_ai.agent.description Optional
gen_ai.agent.version Optional
gen_ai.response.finish_reasons Optional
gen_ai.usage.input_tokens Optional
gen_ai.usage.output_tokens Optional
microsoft.a365.agent.platform.id Optional
microsoft.a365.agent.thought.process Optional
microsoft.channel.link Optional
microsoft.conversation.item.link Optional
microsoft.session.id Optional
microsoft.session.description Optional
server.address Optional
server.port Optional
user.name Optional

OutputScope

属性 Status
gen_ai.agent.id Required
gen_ai.agent.name Required
gen_ai.operation.name Required
gen_ai.output.messages Required
gen_ai.conversation.id Required
microsoft.tenant.id Required
microsoft.a365.agent.blueprint.id Required
microsoft.agent.user.id Required
microsoft.agent.user.email Required
microsoft.channel.name Required
user.id Required
user.email Required
client.address Required
gen_ai.agent.description Optional
gen_ai.agent.version Optional
microsoft.a365.agent.platform.id Optional
microsoft.channel.link Optional
microsoft.conversation.item.link Optional
microsoft.session.id Optional
microsoft.session.description Optional
user.name Optional

使用可观测性测试代理

实现可观测性后，请验证是否正在捕获遥测信息：

  1. 转到 https://admin.cloud.microsoft/#/agents/all 。
  2. 选择代理人，然后选择活动。
  3. 验证是否显示会话和工具调用。

示例应用程序和高级配置

有关工作示例和高级配置选项，请参阅每种语言的GitHub存储库：

故障排除

本部分介绍在将 Microsoft OpenTelemetry Distro 与 Agent 365 一起使用时遇到的常见问题。

小窍门

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

可观测性数据不出现

症状：

  • 代理程序正在运行
  • 管理中心没有遥测
  • 看不到代理活动

根本原因：

  • 未启用 Agent 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 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 的消息。 其他人无需记录即可删除它们。

解决方法：

  • 在导出之前，发行版分区按租户和代理标识进行跨越。 缺少租户 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 错误可能有不同的原因。 按顺序检查以下解决方法。

解决方法：

  • 许可证丢失 — 验证租户是否在 Microsoft 365 管理中心 中分配了以下许可证之一：

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

  • 缺少 Agent365.Observability.OtelWrite 权限 — 必须向标识（托管标识或应用注册）授予此权限。 如果没有它，遥测导出会失败，并返回 HTTP 403。

    使用以下选项之一授予权限。

    Option A — Agent 365 CLI（需要配置目录中的 a365.config.json 和 a365.generated.config.json、全局管理员帐户以及 Agent 365 CLI v1.1.139-preview 或更高版本）

    a365 setup admin --config-dir "<path-to-config-dir>"

    选项 B — Entra Portal （不需要配置文件;需要全局管理员访问蓝图应用注册）

    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 429 / 5xx — 暂时性错误

症状： 导出失败，出现暂时性 HTTP 状态代码，例如 429 或 5xx。

解决方法：

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

导出成功，但遥测不会显示在 Defender 或 Purview 中

Symptoms： 日志显示成功导出（HTTP 200），但遥测在Microsoft Defender或Microsoft Purview中不可见。

解决方法：

  • 验证是否满足查看导出日志的先决条件：
  • 成功导出后，遥测数据可能需要几分钟才能显示。 请稍候，然后进行进一步调查。
  • 验证 span 是否包含有效的 microsoft.tenant.id 和 gen_ai.agent.id 属性。 即使 HTTP 导出返回 200，缺少身份属性也会导致服务器端忽略 span。
  • Last updated on