Python记录的custom events为何无法在Azure API Explorer中查询到

根因定位 #

opencensus-ext-azure属于社区贡献的非官方SDK，默认上报customEvents时的元数据填充逻辑和Azure Application Insights官方JS/TS SDK不一致，缺少API查询链路要求的必填系统字段，导致上报的数据仅对Azure门户内置查询链路可见，无法被API Explorer、Open API等外部查询接口索引到。官方JS/TS的trackEvent接口默认会自动补全所有要求的系统属性，因此没有该问题。

可落地解决步骤 #

• 第一步：升级opencensus-ext-azure到最新稳定版本，同时在初始化AzureExporter时强制开启全量元数据上报配置，代码示例：

from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace.tracer import Tracer

exporter = AzureExporter(
    connection_string="你的App Insights连接串",
    # 开启全量元数据上报，对齐官方SDK逻辑
    enable_standard_metrics=True,
    export_interval=5.0
)
tracer = Tracer(
    exporter=exporter,
    sampler=ProbabilitySampler(1.0)
)

如果是使用日志扩展上报自定义事件，初始化AzureLogHandler时添加相同配置即可。

• 第二步：上报事件时手动补全系统级必填属性，对齐官方SDK默认上报逻辑，避免数据被查询链路过滤：

# 上报自定义事件时补充属性
tracer.add_annotation(
    name="你的自定义事件名称",
    attributes={
        # 业务自定义属性
        "custom_business_field": "对应值",
        # 系统必填属性
        "ai.operation.name": "当前操作名称",
        "ai.cloud.role": "当前服务角色名称",
        "ai.cloud.roleInstance": "当前服务实例标识"
    }
)

如果是通过日志上报自定义事件，将上述属性添加到日志的extra参数中即可。

• 第三步：调整API Explorer查询逻辑，优先使用Kusto语句查询而非默认的事件列表查询，示例查询语句：

customEvents
| where timestamp > ago(24h)
| where name == "你的自定义事件名称"
| project timestamp, name, customDimensions, operation_Name, cloud_RoleName

该查询逻辑可以命中所有上报成功的自定义事件索引，不会遗漏社区SDK上报的数据。

• 第四步：如果调用的是旧版Application Insights REST API（非基于Kusto的查询接口），需要在请求头中添加x-ms-app: opencensus-python标识，避免请求被系统默认过滤非官方SDK上报的数据。

非门户查询通用方案 #

除API Explorer外，还有两种稳定的Azure门户外查询日志的方式：

1. 使用Azure Monitor官方Python SDK执行Kusto查询，直接拉取结构化的事件、链路、异常数据供自定义仪表盘使用
2. 开启Application Insights的连续导出功能，将全量日志自动同步到Azure存储账户或Event Hub，自主消费数据构建仪表盘

内容的提问来源于stack exchange，提问作者Raymond Wang