Azure Application Insights JS SDK trackEvent如何添加自定义属性

可行性结论 #

你尝试的在trackEvent调用中传入customProperties字段携带业务参数的写法，对于通过页面snippet方式集成的经典Application Insights客户端JS SDK是完全可行的，属于SDK原生支持的标准用法，传入的字段会被正常上报到后端，可在Application Insights的事件分析面板中查看、筛选、聚合。

可直接使用的代码示例 #

• 基础版本（和你尝试的结构一致，可直接运行）：

appInsights.trackEvent({
  name: "WinGame",
  customProperties: {
    gameName: "Game 1",
    player: "my player 1"
  }
});

• 如果需要在事件中绑定数值类量化指标，可以在和name、customProperties平级的位置新增measurements字段，这类字段支持直接在查询中做求和、平均值等聚合计算，示例：

appInsights.trackEvent({
  name: "WinGame",
  customProperties: {
    gameName: "Game 1",
    player: "my player 1"
  },
  measurements: {
    levelClearDuration: 42.6,
    gainedScore: 1520
  }
});

使用时的注意事项 #

• 值类型限制：customProperties下的所有字段仅支持字符串、数字、布尔值这类基础类型，如果需要传入数组、嵌套对象这类复杂结构，必须提前手动序列化为字符串，否则SDK无法正确解析上报，会出现字段值丢失的问题。
• 结构嵌套要求：自定义业务字段必须完整嵌套在customProperties对象内部，不要直接把字段写在和name同级的事件对象顶层，这类字段会被SDK直接忽略，无法上报。

不生效的反例写法：

// 业务字段直接挂在事件对象顶层，没有放入customProperties
appInsights.trackEvent({name: "WinGame", gameName: "Game 1"});

• 版本差异提示：如果后续将snippet集成替换为npm方式安装的新版OpenTelemetry架构Browser SDK，自定义属性的挂载字段会从customProperties调整为attributes，该差异和你当前的snippet集成场景无关，后续版本升级时再适配即可。

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