Monitoring API 开发者指南

利用 Monitoring API，您可以构建工具来监控代码的行为和效果。这是通过 addEventCallback 自定义模板 API 方法完成的。在此方法中，您可以指定要在事件结束时调用的事件回调函数。该回调函数将接收事件相关信息，您可根据这些信息创建自己的代码监控方案。您还可以向代码添加元数据，用于进行更精细的监控。

Monitoring API 可支持多种监控用例，例如代码状态、执行时间和元数据。这些监控像素的最终目标是将数据发送到您选择的端点。之后，可通过访问来自此端点的日志来收集监控数据，而收集到的数据随后可显示在信息中心内或用于触发警报系统。

代码状态

此示例所展示的“代码状态”技术使用 addEventCallback 来记录页面上代码的触发状态。该技术会遍历针对相应事件触发的所有代码，并统计成功、失败、引发异常或超时这几类代码的数量。之后这些总数会作为查询参数添加到监控像素网址中。监控像素的网址类似于以下网址：

https://www.example.com/monitoring?ctid=GTM-XXXXXX&success=4&failure=1&exception=1&timeout=0

您可以使用以下代码示例来设置像素网址：

const addEventCallback = require('addEventCallback');
const sendPixel = require('sendPixel');

addEventCallback(function(containerId, eventData) {
  let successCount = 0;
  let failureCount = 0;
  let exceptionCount = 0;
  let timeoutCount = 0;

  const tagData = eventData['tags'];
  const timingData = [];
  for (let i in tagData) {
    let entry  = tagData[i];
    switch (entry.status) {
      case 'success':
        successCount++;
        continue;
      case 'failure':
        failureCount++;
        continue;
      case 'exception':
        exceptionCount++;
        continue;
      case 'timeout':
        timeoutCount++;
        continue;
    }
  }
  let url = 'https://www.example.com/monitoring?ctid=' + containerId +
      '&success=' + successCount +
      '&failure=' + failureCount +
      '&exception=' + exceptionCount +
      '&timeout=' + timeoutCount;
  sendPixel(url);
});
data.gtmOnSuccess();

执行时间

此技术使用 addEventCallback 来帮助收集有关代码执行时间的数据。对于针对此事件触发的每个代码，系统都会将一个查询参数添加到包含代码 ID 和执行时间的像素网址中，并发送类似于以下内容的像素：

https://www.example.com/monitoring?ctid=GTM-XXXXXX&tag12=1200&tag50=400&tag1=6000

您可以使用以下代码示例来设置像素网址：

const addEventCallback = require('addEventCallback');
const sendPixel = require('sendPixel');

addEventCallback(function(containerId, eventData) {
  let url = 'https://www.example.com/monitoring?ctid=' + containerId;
  const tagData = eventData['tags'];
  const timingData = [];
  for (let i in tagData) {
    let entry = tagData[i];
    timingData.push('&tag' + entry['id'] + '=' + entry['executionTime']);
  }
  url += timingData.join('');
  sendPixel(url);
});
data.gtmOnSuccess();

元数据

您可以使用 Monitoring API 提供的基础数据构建实用的信息中心。不过，在某些情况下，您可能只想监控一部分代码。为了方便起见，您可以使用代码元数据部分，在代码定义中指定任意键值对。发生事件回调时，这些值将包含在事件数据对象中。

例如：您针对新的广告系列将某代码添加到容器中。该容器内已有很多代码，但您只想监控这个新添加的代码。

若要从事件回调中识别此代码，请向代码中添加元数据：

1. 在代码定义中，依次点击高级设置 > 更多代码元数据。
2. 点击包含代码名称复选框以将其选中。
3. 在代码名称的键中，输入一个值。此示例使用“name”作为值。这会在发送事件数据时包括此代码名称。
4. 点击 + 添加元数据，然后输入键和值对。此示例使用键“group”和值“Campaign 2019”。
5. 根据需要，使用 + 添加元数据添加更多行键值对。

在自定义模板中，开发者可以通过检查在元数据中设置的值来识别此代码：

const addEventCallback = require('addEventCallback');
const sendPixel = require('sendPixel');

addEventCallback(function(containerId, eventData) {
  let url = 'https://www.example.com/monitoring/campaignPixel?ctid=' + containerId;
  const tagData = eventData['tags'];
  for (let i in tagData) {
    let entry = tagData[i];
    if (entry['name'] === 'Conversion Pixel 2019') {
      url += '&status=' + entry['status'];
      break;
    }
  }
  sendPixel(url);
});
data.gtmOnSuccess();

这将生成类似于以下内容的像素网址：

https://www.example.com/monitoring/campaignPixel?ctid=GTM-XXXXXX&status=success

如果需要，您可以接着监控“Campaign 2019”组的所有代码：

const addEventCallback = require('addEventCallback');
const encode = require('encodeUriComponent');
const sendPixel = require('sendPixel');

addEventCallback(function(containerId, eventData) {
  let url = 'https://www.example.com/monitoring/campaign2019?ctid=' + containerId;
  const tagData = eventData['tags'];
  for (let i in tagData) {
    let entry = tagData[i];
    if (entry['group'] === 'Campaign 2019') {
      url += '&' + encode(entry['name']) + '=' + entry['status'];
      break;
    }
  }
  sendPixel(url);
});
data.gtmOnSuccess();

这将生成类似于以下内容的监控像素：

https://www.example.com/monitoring/campaign2019?ctid=GTM-XXXXXX&Conversion%20Pixel%202019=failure