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 時除外。

一般而言，我們建議不要使用 window.title 或 window.href 來定義頁面。 這將導致大量追蹤頁面在大多數情況下不會提供值，例如，因為 window.title 包含產品名稱。 相反地，我們建議使用頁面的邏輯名稱。 例如 product detail page 或 payment selection。 這會導致與實際現有程式碼有直接關係的頁面較少。

我們提供 範例專案 ，以顯示如何收集各種架構和程式庫的有意義頁面名稱。 如果您的架構/程式庫遺漏，請隨時提出取回或支援要求。

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');

識別使用者

使用者特定資訊可以選擇性地與傳輸至 Instana 的資料一起傳送。 然後可以使用此資訊來解除鎖定其他功能，例如:

• 計算受錯誤影響的使用者數目，
• 過濾特定使用者的資料
• 以查看哪個使用者起始頁面載入 /AJAX 呼叫。

依預設， Instana 不會將任何使用者識別資訊關聯至信標。 在選擇這樣做時，請注意個別的資料保護法。 我們通常建議透過使用者 ID 來識別使用者。 對於 Instana ，這是完全透通的 string ，僅用於計算特定度量值。 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 在沒有已定義的 使用者資訊的情況下，判斷一般使用者的影響。

為了追蹤階段作業，在發出 trackSessions 呼叫之後， JavaScript 代理程式將使用 localStorage 瀏覽器 API。 技術上來說，階段作業是隨機 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');

meta 資料

meta 資料可用來標註頁面載入和 AJAX 呼叫。 請考量使用此項目來追蹤使用者介面配置值、設定、特性旗標 ... 任何可能有助於分析的其他環境定義。

ineum('meta', key, value);

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

頁面載入後端追蹤 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);

我們也支援從文件 URL 中刪除密鑰，亦即瀏覽器位址列中可見的 URL (請參閱 密鑰 API)。 不過，請注意，儲存在文件 URL 中的密鑰幾乎肯定會 洩漏 給所有協力廠商。 我們有一個 具有說明的專用範例應用程式 ，其顯示儲存在文件 URL 中的密鑰為何容易洩漏給所有協力廠商的原因。 如需詳細資料，請參閱此範例應用程式及說明。 不過，您可以選擇透過此 API 忽略這些 URL 的所有監視資料收集。

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

從 URL 編寫密碼

所收集 URL 中的查詢參數可能包含機密資料。 因此， JavaScript 代理程式支援查詢參數索引鍵的型樣規格，其值將被編寫。 在 JavaScript 代理程式內 (亦即，在 Web 瀏覽器內) 發生編寫。 因此，密鑰將無法呼叫到 Instana 伺服器進行處理，並且將無法在使用者介面中進行分析或透過 API 進行擷取。

ineum('secrets', secrets);

如果查詢參數符合清單中的項目，則會編寫值，且不會傳送至 Instana 後端。 如果未定義 ineum('secrets') ，依預設， Instana 會使用 [/key/i, /secret/i, /password/i] 作為比對規則。

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

從追蹤排除使用者計時

我們會自動收集透過 User-Timing API 所做的標記和測量，並將它們轉換成 自訂事件。 這表示 User-Timing API 可以用來作為供應商中立的方式，將純計時資料報告給 Instana。

此 API 可讓您定義數個正規表示式，當至少有一個相符項時，將不會產生特定使用者計時的集合。 依預設，我們會忽略 ...

• React 's 使用者計時，亦即以 ⚛️ 或 ⛔ 表情符號開頭的標記和測量。
• Angular 的使用者計時，亦即以 Zone 和
• 其名稱以 start 或 end 開頭的標記和測量。

ineum('ignoreUserTimings', ignoreUserTimings);

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

配置頁面載入之後的等待上限

為了收集其他度量值，例如第一個輸入延遲和累積佈置移位， JavaScript 代理程式將等待直到 ...

• 所有度量都可用
• 頁面已卸載 (例如，標籤已關閉) 或
• 直到最長的等待時間已經過去。

您可以使用此 API 來重新配置等待時間上限。 依預設，在頁面載入完成之後，我們最多會等待一秒，亦即， onLoad 事件已結束。

ineum('maxMaitForPageLoadMetricsMillis', durationMillis);

ineum('maxMaitForPageLoadMetricsMillis', 500);

擷取頁面載入 ID

有時手動接收頁面載入的 ID 會很有用，例如當想要執行自訂相關性時。 只要尚未載入 JavaScript 代理程式，此函數就會傳回 undefined 。 載入之後，它一律會傳回相同的 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
});

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'
  }
});

跨原點要求後端相關性

Instana 的後端相關性透過在 XMLHttpRequest / fetch 要求上設定自訂標頭來運作。 JavaScript 代理程式會設定這些標頭，然後由伺服器讀取。 在瀏覽器內，相同原點原則會限制自訂標頭的傳輸。 更具體地說，只能針對相同來源要求或其他來源的要求 (容許傳輸自訂標頭) 設定自訂標頭。 例如，依預設， https://example.com:443 所提供的網站無法將 XMLHttpRequest設為 https://shop.example.com:443 ，因為這些是兩個不同的來源。

為了暫行解決此安全限制，可以使用 跨原點資源共用 (CORS)。 使用 CORS ，可以容許來源進行跨來源資源存取。 如果您在應用程式內已有跨原點資源存取權，則很可能已使用部分 CORS 標頭。

若要啟用 Instana 後端相關性，需要執行下列動作:

1. 在伺服器端使用下列標頭回應，以容許 Instana 的相關性標頭進行跨原點要求。

   請注意，您的伺服器必須同時回應 Preflight requests 和一般要求的這些標頭。 預檢要求 (可透過 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 代理程式可以擷取 XMLHttpRequest / fetch 要求上的 HTTP 要求/回應標頭。 您可以定義 captureHeaders 指令要 JavaScript 代理程式擷取的 HTTP 標頭。

在瀏覽器內，相同來源原則會限制存取自訂標頭。 如果沒有 跨原點資源共用 (CORS) 配置， JavaScript 代理程式可能無法擷取所有 HTTP 標頭。 若要啟用 CORS ，請參閱 跨原點要求後端相關性。 使用 CORS 時， JavaScript 代理程式只能收集 COSR 滿足的要求/回應標頭，以及在 Access-Control-Expose-Headers 中定義的標頭。

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