JavaScript 代理程序 API

参数

下表列出了参数：

函数 ineum 从不返回任何内容（命令 getPageLoadId 除外）。

监测关键

可通过 key 命令设置监控密钥。 在 Instana 用户界面配置网站时，可以看到监控密钥。

ineum('key', trackingKey);

if (window.location.hostname === 'example.com') {
  ineum('key', 'production monitoring key');
} else if (window.location.hostname === 'qa.example.com') {
  ineum('key', 'QA monitoring key');
} else {
  ineum('key', 'test monitoring key');
}

报告 URL

信标通过 HTTP GET 和 POST 传输到报告 URL ，将监测数据传送到 Instana。

ineum('reportingUrl', reportingUrl);

多个后端

在某些情况下，可能需要让 JavaScript 代理向多个后端报告。 在这种情况下，使用 reportingBackends 命令使 JavaScript 代理向多个后端报告。

ineum('reportingBackends', reportingBackends);

{
  reportingUrl: 'http://example.com',  // The URL to which to send website monitoring data to.
  key: 'monitoring key'                // The monitoring key for the website configuration in Instana.
}

ineum('reportingBackends', [
      { reportingUrl: 'http://backend1.example.com', key: 'monitoring key 1' },
      { reportingUrl: 'http://backend2.example.com', key: 'moniroting key 2' }
    ]);

页面

Instana 可按逻辑页面细分网站指标。 为此，它需要关于用户正在查看的页面的提示。 该页面名称可通过 page 命令设置。 尽早设置 page 。 您可以更改 page 来呈现文档更改（例如，单页应用程序）。 这使得 Instana 除了可以跟踪页面加载之外，还可以跟踪页面转换。

ineum('page', pageName);

除了在页面加载阶段首次调用此 API 外，只要通过 API 更改页面名称，就会记录页面转换事件。

要定义页面，请使用 product detail page 或 payment selection 这样的逻辑名称，而不是 window.title 或 window.href。 使用 product detail page 或 payment selection 会减少与现有代码直接相关的页面。 而使用 window.title 或 window.href 则会产生许多跟踪页面，这些页面在大多数情况下都能提供价值，因为 window.title 包含产品名称。

Instana 提供了示例项目 ，展示如何为各种框架和库收集有意义的页面名称。 为缺失的框架或库提出拉取或支持请求。

ineum('page', 'shopping-cart');

// Do you want to change meta data and the page name at the same time?
// Make sure to change the page name last as this immediately
// triggers a page transition beacon.
ineum('meta', 'product', 'skateboard');
ineum('page', 'article-details');

ineum('autoPageDetection', true);
// page changes will be detected once set to true

ineum('autoPageDetection', {mappingRule: [[/.*urlRegex.*/i, 'Page Name']]});

ineum('autoPageDetection', {titleAsPageName: true});

ineum('autoPageDetection',  {ignorePopstateEvent: true});

ineum('autoPageDetection',  {mappingRule: [[/.*checkuserdetails.*/i, 'User Details']]});
// Matches the regex and sets page name as User Details
// .*checkuserdetails.* matches the characters in the URL while 'i' modifier represents a case insensitve match.

ineum('autoPageDetection',  {mappingRule: [[/.*product[0-9]+contains-[A-Za-z]+-productID-account-([A-Za-z].*)\1+/, 'Product Page : id $1'],[/.*aboutPage.*-([A-Za-z].*)/, 'About Page id: $1']]});

标识用户

用户特定信息可以选择与传输到 Instana 的数据一起发送。 然后可以使用此信息解锁更多功能，例如：

• 计算受错误影响的用户数量
• 过滤特定用户的数据
• 查看哪个用户启动了页面加载或 Ajax 调用。

缺省情况下，Instana 不会将任何用户可标识信息与信标关联。 当您选择这样做时，请注意相关的数据保护法律。 在 Instana 中，用户 ID 是一个透明的 string ，仅用于计算某些指标。 因此，用户的身份识别是通过用户 ID 来完成的。 userName 和 userEmail 也可用于访问更多过滤器和有效展示用户信息。

已经传送到Instana服务器的数据不能追溯更新。 因此，必须在页面加载过程中尽快调用此 API。

在页面加载过程中同步调用此 API，例如在服务器端将信息渲染到 HTML 文档中，有助于确保所有信标都携带用户信息，确保唯一用户或受影响用户的统计数据正确无误，并在分析时对信标进行正确过滤和分组。

ineum('user', userId, userName, userEmail);

// Report everything to Instana
ineum('user', 'hjmna897k1', 'Tom Mason', 'tom@example.com');

// or only some data points
ineum('user', 'hjmna897k1');
ineum('user', null, null, 'tom@example.com');

会话跟踪

会话跟踪可用于深入了解终端用户在页面加载过程中的活动。 会话跟踪特别使 Instana 能够在没有定义用户信息的情况下确定最终用户的影响。

要跟踪会话， JavaScript 代理在调用 localStorage 浏览器 API 调用 trackSessions 。 从技术上讲，会话是一个随机 ID，与两个时间戳一起存储在浏览器的 localStorage 中，密钥为 in-session。

遵守隐私法规的责任由此 API 的调用者承担。

ineum('trackSessions', sessionInactivityTimeout, sessionTerminationTimeout);

// Starts tracking sessions with the default timeouts
ineum('trackSessions');

// or specify custom timeouts
ineum('trackSessions', 900000 /* 15min */, 3600000 /* 1h */);

ineum('terminateSession');

// Starts tracking sessions with the default timeouts
ineum('trackSessions');

// after some time…
ineum('terminateSession');

元数据

元数据可用于注释页面加载和 Ajax 调用。 使用元数据来跟踪用户界面配置值、设置、功能标志或任何对分析有用的附加上下文。

ineum('meta', key, value);

ineum('meta', 'version', '1.42.3');
ineum('meta', 'role', 'admin');

页面加载后台跟踪 ID

作为页面加载的一部分，可以定义一个后台跟踪 ID，以便进行前端或后台关联。 更多信息，请参阅后台相关性。 需要定义后端跟踪 ID，以便在页面加载的后端和前端处理之间建立关联。 XMLHttpRequest 或 fetch 请求之间的相关性并不需要它。 跟踪 ID 必须是 16 或 32 个字符的十六进制字符串。

ineum('traceId', traceId);

ineum('traceId', '89jkbds891jkn321');

将 URL 排除在跟踪之外

您可以使用此 API 定义多种正则表达式。 如果至少有一个匹配，则不会向 Instana 传输数据。 正则表达式在以下情况下进行评估：

• 根据文档的 URL（地址栏中可见的 URL，即 window.location.href ）进行评估。当其中一个正则表达式匹配时，所有向 Instana 传输的数据都将被禁用。
• 根据资源的 URL（例如 JavaScript 和 CSS 文件的 URL）进行评估。 与正则表达式之一匹配的资源信息不会传输到 Instana。
• 根据 HTTP 调用的目标 URL 进行评估，例如通过 XMLHttpRequest 和 fetch。 与正则表达式之一相匹配的 HTTP 调用信息不会传送给 Instana。

ineum('ignoreUrls', ignoreUrls);

Instana 还支持从文档 URL（即浏览器地址栏中可见的 URL ）中剥离秘密（请参阅秘密 API）。 但要注意的是，存储在文档 URL 中的秘密几乎会泄露给所有第三方。 我们有一个具有描述的专用示例应用程序，它显示了存储在文档 URL 中的私钥容易泄露给所有第三方的原因。 更多详情，请参阅本示例应用程序和说明。 不过，您可以选择忽略通过此 API 对这些 URL 收集的所有监控数据。

ineum('ignoreUrls', [
  /\/comet.+/i,
  /\/ws.+/i,
  /.*(&|\?)secret=.*/i
]);

重新编辑 URL 中的秘密

收集到的 URL 中的查询参数可能包含敏感数据。 因此， JavaScript 代理支持为其值被编辑的查询参数键指定模式。 Redaction 发生在 JavaScript 代理中，即网络浏览器中。 因此，秘密无法到达 Instana 服务器进行处理，也无法在用户界面中进行分析或通过 API 进行检索。

ineum('secrets', secrets);

如果查询参数与列表中的条目匹配，那么会编辑该值，并且不会将其发送到 Instana 后端。 如果未定义 ineum('secrets')，那么缺省情况下 Instana 会使用 [/key/i, /secret/i, /password/i] 作为匹配规则。

ineum('secrets', [/account/i, /user/i]);

编辑 URL 片段

收集到的 URL 片段可能包含敏感信息。 因此， JavaScript 代理支持根据 URL 路径指定可编辑的片段值模式。 这种编辑是在网络浏览器 JavaScript 代理中进行的。 因此，敏感信息无法到达 Instana 服务器进行处理。 敏感信息仍无法通过用户界面进行分析或通过应用程序接口进行检索。

ineum('fragment', fragment);

如果 URL 路径的某个片段与列表中的某个条目相匹配，该片段值将被编辑，不会发送到 Instana 后台。 默认情况下，Instana 不会编辑 URL 片段。

ineum('fragment', [/example.com/i]);

将用户计时排除在跟踪之外

Instana 可自动收集通过用户计时应用程序接口（User-Timing API ）进行的标记和测量，并将其转化为自定义事件。 这意味着，用户计时 API 可以用作向 Instana 报告纯计时数据的与供应商无关的方式。

通过使用用户计时 API，您可以定义多个正则表达式，当至少有一个正则表达式匹配时，就不会产生特定用户计时集合。 默认情况下，以下条件将被忽略：

• React 的用户计时：以 ⚛️ 或 ⛔ 表情符开头的标记和计量单位
• Angular 的用户计时：以 Zone
• 名称以 start 或 end

ineum('ignoreUserTimings', ignoreUserTimings);

ineum('ignoreUserTimings', [
  /^\u269B/,
  /^\u26D4/,
  /^Zone(:|$)/,
  /mySecretTiming/i
]);

从跟踪中排除 URL 查询参数和片段

默认情况下， JavaScript 代理会收集完整的 URL ，其中包括所有参数。 您可以配置代理只收集与指定正则表达式列表匹配的 URL 的参数。 不跟踪排除 URL 的参数。

根据所提供的正则表达式列表， JavaScript 代理会对 URL 进行如下跟踪：

• 如果 URL 与列表中的一个条目匹配，则会收集包括所有参数在内的整个 URL。
• 如果 URL 与列表中的条目不匹配，则不会向 Instana 后台发送查询参数和 URL 的片段。
• 如果所提供的列表为空，则应用默认行为，并跟踪带有参数的完整 URL。

ineum('queryTrackedDomainList',queryTrackedDomainList);

如果 URL 中包含通过 ineum('secrets', secrets) 或 ineum('fragment', fragment) 编辑的秘密或片段，以下情况将予以说明：

• 如果 URL 与 queryTrackedDomainList 中的条目相匹配，则整个 URL 和经编辑的密文或片段会被发送到 Instana 后台。
• 如果 URL 与 queryTrackedDomainList 中的条目不匹配，则在向 Instana 后台发送 URL 之前，会排除所有参数。

ineum('queryTrackedDomainList', [
  /\/comet.+/i,
  /\/ws.+/i,
  /example.com/i
]);

支持 W3C 跟踪头，用于后端关联

当浏览器向远程服务器发送请求，而 Instana 代理监控远程服务器时，服务器的响应可能包含 HTTP 标头 Server-Timing，以便向浏览器中运行的 Instana 代理提供 backendTraceId 。 如果远程服务器启用了 OpenTelemetry ，则 tracestate HTTP 标头可包含 backendTraceId。

tracestate 和 traceparent 是 W3C-defined 标头，用于关联分布式跟踪 ID。 有关 W3C 跟踪头的更多信息，请参阅跟踪上下文级别。

如果预计远程服务器可以使用 OpenTelemetry 并在 tracestate 标头中提供 backendTraceId ，那么浏览器中的 Instana 代理就必须将 enableW3CHeaders API 设置为 true，以使用 W3C 标头中的 backendTraceId 值。

您可以在三个不同的地方设置 backendTraceId ：通过 Server-Timing 标头、 tracestate 标头，以及使用浏览器中的 traceId API 手动设置。 这些方法的顺序如下

• 如果启用了 enableW3CHeaders ，则有两种选择。 首先，从当前页面的元数据 traceparent 中提取 tracestate 值并使用它。 如果无法检索 tracestate ，则会生成并使用与 W3C 跟踪上下文兼容的 16 个字符的长字符串。
• 如果 enableW3CHeaders 已禁用，请首先验证是否调用了 traceId API。 如果调用 traceId API，则使用 ID 作为 backendTraceId。 如果未调用 traceId API，则解析 HTTP 标头 Server-Timing 以获取 backendTraceId。
• 如果上述值都不可用，则无法将信标与后台跟踪相关联。

ineum('enableW3CHeaders',true);

ineum('enableW3CHeaders', true);

配置页面加载后的最大等待时间

要收集更多指标， JavaScript 代理会等待，直到符合以下条件。 例如，首次输入延迟和累积布局偏移。

• 可提供所有指标
• 页面已卸载（例如标签已关闭）
• 直到最长等待时间结束

您可以使用此 API 来重新配置最大等待时间。 默认情况下，Instana 会在页面加载完成（即 onLoad 事件结束）后最多等待一秒钟。

ineum('maxMaitForPageLoadMetricsMillis', durationMillis);

ineum('maxMaitForPageLoadMetricsMillis', 500);

读取页面加载 ID

有时，手动接收页面加载的 ID 会很有用，例如，当需要进行自定义关联时。 该函数返回 undefined ，直至 JavaScript 代理未加载。 JavaScript 代理加载后，总是返回相同的 string。

ineum('getPageLoadId');

var pageLoadId = ineum('getPageLoadId');
console.log(pageLoadId);

错误跟踪

ineum('reportError', error, opts);

{
  componentStack: '...' // an optional string

  meta: {               // An optional JavaScript object with `string` values which can be used
    widgetType: 'chart' // to send metadata to Instana just for this singular event. In contrast to
  }                     // the usage of the metadata API, this metadata is not included in subsequent
                        // beacons.
}

ineum('reportError', new Error('Something failed'), {
  componentStack: '…',
  meta: {
    widgetType: 'chart'
  }
});

componentDidCatch(error, info) {
  ineum('reportError', error, {
    componentStack: info.componentStack
  });

  // your regular error boundary code
}

import { ErrorHandler, NgModule } from '@angular/core';

class CustomErrorHandler implements ErrorHandler {
  handleError(error) {
    ineum('reportError', error);

    // Continue to log caught errors to the console
    console.error(error);
  }
}

@NgModule({
  providers: [{ provide: ErrorHandler, useClass: CustomErrorHandler }],
})
class MyModule {
  // the rest of your application code…
}

app.config.errorHandler = (err, instance, info) => {
  ineum('reportError', err);
  // your regular error handling code
}

ineum('ignoreErrorMessages', ignoreErrorMessages);

ineum('ignoreErrorMessages', [/^script error/i]);

ineum('wrapEventHandlers', enabled);

ineum('wrapEventHandlers', true);

ineum('wrapTimers', enabled);

ineum('wrapTimers', true);

ineum('ignoreErrorMessages', [/^script error/i]);

报告自定义事件

有关全局自定义事件的更多信息，请参阅事件页面。

自定义事件可以向 Instana 报告非标准活动、重要交互和自定义时间。 这对分析未捕获错误（面包屑）和跟踪更多性能指标特别有用。

ineum('reportEvent', eventName, {
  duration: duration,
  timestamp: timestamp,
  backendTraceId: backendTraceId,
  error: error,
  componentStack: componentStack,
  meta: meta,
  customMetric: customMetric
});

ineum('reportEvent', 'login');

ineum('reportEvent', 'full example', {
  timestamp: Date.now(),
  duration: 42,
  backendTraceId: '31ab91fc109223fe',
  error: new Error('whooops – sorry!'),
  componentStack: 'a component stack',
  meta: {
    state: 'running'
  },
  customMetric: 123.2342
});

跨源请求后台相关性

Instana 的后台相关性通过在 XMLHttpRequest / fetch 请求上设置自定义头来实现。 JavaScript 代理会设置这些标头，然后由服务器读取。 在浏览器中，同一源策略限制了定制头的传输。 更具体地说，自定义标头只能针对同源请求或允许传输自定义标头的其他源请求进行设置。 例如，默认情况下，由 https://example.com:443 提供服务的网站不能将 XMLHttpRequests 转至 https://shop.example.com:443 ，因为这是两个不同的来源。

要解决此安全限制，请使用跨源资源共享 (CORS)。 使用 CORS 时，可以允许源进行跨源资源访问。 如果已在应用程序中具有跨源资源访问权，那么您很可能已使用某些 CORS 头。

要启用 Instana 后台相关性，请完成以下步骤：

1. 通过在服务器端使用以下头进行响应，允许将 Instana 的关联头用于跨源请求。

   对于预检请求和常规请求，服务器都必须使用这些标头进行响应。 预检请求（可通过 OPTIONS HTTP 方法识别）由浏览器执行，以验证是否可向服务器发出请求。

   Access-Control-Allow-Origin: https://your-origin.example.com
   Access-Control-Allow-Headers: X-INSTANA-T, X-INSTANA-S, X-INSTANA-L
   

2. 通知 JavaScript 代理 CORS 已正确配置，它必须设置这些相关标头：

   ineum('allowedOrigins', urls);
   

ineum('allowedOrigins', [/.*api\.example\.com.*/]);

捕捉 HTTP 请求或响应标头

JavaScript 代理可捕获 HTTP 请求或 XMLHttpRequest 或 fetch 请求的响应标头。 可以定义您希望 JavaScript 代理程序通过 captureHeaders 命令捕获的 HTTP 头。

在浏览器中，同一源策略会限制对定制头的访问。 在没有跨源资源共享 (CORS) 配置的情况下，JavaScript 代理程序可能无法捕获所有 HTTP 头。 要启用 CORS，请参阅跨源请求后端关联。 使用 CORS 时， JavaScript 代理只能收集满足 CORS 要求的请求或响应标头，以及在 Access-Control-Expose-Headers 中定义的标头。

ineum('captureHeaders', [/content-type/i]);