使用 Application Insights 監視 Node.js 服務和應用程式

發行項
10/15/2024

Application Insights 會在部署後監視您的元件，以探索效能和其他問題。您可以對在資料中心、Azure VM 和 Web 應用程式，和甚至其他公用雲端中託管的 Node.js 服務使用 Application Insights。

接收、儲存及探索您的監視資料，包含程式碼中 SDK。然後在 Azure 中設定對應的 Application Insights 資源。 SDK 會將資料傳送至該資源，進行進一步的分析和探索。

Node.js 用戶端程式庫可自動監視傳入和傳出 HTTP 要求、例外狀況、和一些系統計量。從 0.20 版開始，用戶端程式庫也可監視一些常見的第三方套件，像是 MongoDB、MySQL 和 Redis。

與傳入 HTTP 要求相關的所有事件都會相互關聯，以進行快速疑難排解。

您可以使用 TelemetryClient API 手動檢測和監視您的應用程式及系統的其他層面。我們將在本文稍後更詳細說明 TelemetryClient API。

警告

我們建議為新應用程式或客戶提供 Azure 監視器 Application Insights 的 Azure 監視器 OpenTelemetry 散發版本。 Azure 監視器 OpenTelemetry 散發版本提供與 Application Insights SDK 類似的功能和體驗。您可以使用適用於 .NET、Node.js 和 Python 的移轉指南，從 Application Insights SDK 移轉，但我們仍在努力新增更多功能以提供回溯相容性。

開始使用

完成下列工作來設定應用程式或服務的監視。

必要條件

開始之前，請確定您有 Azure 訂用帳戶或免費取得一個新訂用帳戶。如果您的組織已經有 Azure 訂用帳戶，系統管理員可以依照這些指示將您新增至該訂用帳戶。

設定 Application Insights 資源

登入 Azure 入口網站。
建立 Application Insights 資源。

注意

針對檢測金鑰擷取的支援將在 2025 年 3 月 31 日結束。檢測金鑰擷取將會繼續運作，但我們不再提供該功能的更新或支援。轉換至連接字串以利用新功能。

設定 Node.js 用戶端程式庫

在您的應用程式中包含 SDK，以便收集資料。

從您的新資源複製資源的連接字串。 Application Insights 會使用連接字串將資料對應至您的 Azure 資源。您必須先在環境變數或程式碼中指定連接字串，SDK 才可使用您的連接字串。
接著，透過 package.json，將 Node.js 用戶端程式庫新增至您應用程式的相依性。從您應用程式的根資料夾，執行︰
```
npm install applicationinsights --save
```
注意

若您正在使用 TypeScript，請勿安裝個別的 "typings" 套件。此 NPM 套件有內建 typings。
在您的程式碼中明確地載入此程式庫。因為 SDK 會將檢測插入其他許多程式庫中，請儘早載入程式庫，甚至插入在其他 require 陳述式之前。
```
let appInsights = require('applicationinsights');
```
您也可以透過環境變數 APPLICATIONINSIGHTS_CONNECTION_STRING 來提供連接字串，而非以手動方式將其傳遞至 setup() 或 new appInsights.TelemetryClient()。此做法可讓您將連接字串保留在認可的原始程式碼外，而您可以針對不同的環境指定不同的連接字串。若要手動設定，請呼叫 appInsights.setup('[your connection string]');。

如需更多設定選項，請參閱下列各節。

藉由設定 appInsights.defaultClient.config.disableAppInsights = true，您可以嘗試 SDK，而不需要傳送遙測。
藉由呼叫 appInsights.start(); 來開始自動收集和傳送資料。

注意

在使用 Application Insights 檢測的過程中，我們會收集診斷資料並且傳送給 Microsoft。此資料可協助我們執行及改善 Application Insights。您可以選擇停用非必要的資料收集。深入了解。

監視應用程式

SDK 會自動蒐集有關 Node.js 執行階段和一些常見第三方模組的遙測。使用您的應用程式來產生一些資料。

然後，在 Azure 入口網站中，前往您稍早建立的 Application Insights 資源。在概觀時間表中，尋找您的前幾個資料點。若要查看更詳細的資料，請在圖表中選取不同的元件。

若要檢視應用程式找到的拓撲，您可以使用應用程式對應。

無資料

因為 SDK 會分批提交資料，所以項目可能會延遲顯示在入口網站中。如果未在您的資源中看到資料，請嘗試以下一些修正方式：

繼續使用應用程式。採取更多動作以產生更多遙測。
選取入口網站資源檢視中的 [重新整理]。圖表會自行定期重新整理，但手動重新整理會強制圖表立即重新整理。
確認所需的連出連接埠已開啟。
使用搜尋來尋找特定的事件。
查看常見問題集。

基本使用方式

針對現成可用的 HTTP 要求集合、熱門的第三方程式庫事件、未處理的例外狀況和系統計量：


let appInsights = require("applicationinsights");
appInsights.setup("[your connection string]").start();

注意

如果連接字串是在環境變數 APPLICATIONINSIGHTS_CONNECTION_STRING 中設定的，則可以在沒有引數的情況下呼叫 .setup()。這可讓您輕鬆地針對不同的環境使用不同的連接字串。

在載入其他套件之前，盡快在指令碼中載入 Application Insights 程式庫 require("applicationinsights")。這是必要步驟，讓 Application Insights 程式庫可以準備稍後的套件以進行追蹤。如果您與執行類似準備的其他程式庫發生衝突，請稍後再嘗試載入 Application Insights 程式庫。

由於 JavaScript 處理回呼的方式，因此需執行更多工作，才能跨外部相依性和後續回呼追蹤要求。根據預設，會啟用此額外追蹤。如 SDK 設定一節所述，可藉由呼叫 setAutoDependencyCorrelation(false) 來停用該功能。

從 0.22 之前的版本移轉

0.22 版以前的版本和以後的版本之間有重大變更。這些變更的設計目的是要與其他 Application Insights SDK 保持一致性，並允許未來的擴充性。

一般而言，您可以使用下列動作進行移轉：

將 appInsights.client 的參考取代為 appInsights.defaultClient。
將 appInsights.getClient() 的參考取代為 new appInsights.TelemetryClient()。
將 client.track* 方法的所有引數取代為包含具名屬性作為引數的單一物件。如需每個遙測類型的例外物件，請參閱您的 IDE 內建類型提示或 TelemetryTypes。

若您存取 SDK 設定函式而未將其鏈結至 appInsights.setup()，則現在可以在 appInsights.Configurations 找到這些函式。例如 appInsights.Configuration.setAutoCollectDependencies(true)。檢閱下一節中預設組態的變更。

SDK 組態

appInsights 物件提供許多設定方法。會以預設值列在下列程式碼片段中。

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(false)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI)
    .start();

若要使服務中的事件完全相互關聯，請務必設定 .setAutoDependencyCorrelation(true)。利用設定這個選項，可讓 SDK 追蹤 Node.js 中所有非同步回呼的內容。

如需選擇性次要引數的詳細資訊，請檢閱 IDE 內建類型提示或 applicationinsights.ts 中的描述。

注意

根據預設，會將 setAutoCollectConsole 設定為「排除」對 console.log 及其他主控台方法的呼叫。只會收集對支援第三方記錄器的呼叫 (例如 winston 和 bunyan)。您可以使用 setAutoCollectConsole(true, true) 來變更此行為，以包含對 console 方法的呼叫。

取樣

根據預設，SDK 會將所有收集的資料傳送至 Application Insights 服務。如果您想要啟用取樣以減少資料量，請在用戶端的 config 物件上設定 samplingPercentage 欄位。將 samplingPercentage 設定為 100 (預設值) 表示將會傳送所有資料，而 0 表示不會傳送任何資料。

如果您使用自動相互關聯，則與單一要求相關聯的所有資料都會以單位形式包含或排除。

新增如下的程式碼以啟用取樣：

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.config.samplingPercentage = 33; // 33% of all telemetry will be sent to Application Insights
appInsights.start();

多元件應用程式的多個角色

在某些情況下，您的應用程式可能包含您想要使用相同連接字串檢測的多個元件。而您仍想要在入口網站中將這些元件視為個別單位，就像是其使用個別連接字串一樣。範例是應用程式對應上的個別節點。您必須手動設定 RoleName 欄位，以區別某個元件的遙測，以及將資料傳送至 Application Insights 資源的其他元件。

使用下列程式碼來設定 RoleName 欄位：

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = "MyRoleName";
appInsights.start();

瀏覽器 SDK 載入器

注意

以公開預覽版提供。 Microsoft Azure Preview 補充使用規定

您可透過設定 JavaScript (Web) SDK 載入器指令碼插入，為節點伺服器啟用自動 Web 檢測，

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .enableWebInstrumentation(true)
    .start();

或者設定環境變數 APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = true 進行。

符合所有下列需求時，節點伺服器回應便會啟用 Web 檢測：

回應的狀態碼為 200。
回應方法為 GET。
伺服器回應有 Content-Type HTML。
伺服器回應包含 <head> 和 </head> 標籤。
如果壓縮回應，則必須只有一個 Content-Encoding 類型且編碼類型必須為 gzip、br 或 deflate 的其中一個。
回應不應包含目前/備份 Web 檢測 CDN 端點。 (目前和備份 Web 檢測 CDN 端點如這裡所述)

您可透過設定環境變數 APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints" 以變更檢測 CDN 端點。您可透過設定環境變數 APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string" 以變更檢測連線

注意

Web 檢測可能減緩伺服器回應時間，特別是當回應大小過大或壓縮回應時。若已套用某些中間層，則可能會導致 Web 檢測無法運作且將傳回原始回應。

自動第三方檢測

若要跨非同步呼叫追蹤內容，則協力廠商程式庫中需要一些變更，例如 MongoDB 與 Redis。根據預設，Application Insights 會使用 diagnostic-channel-publishers 來透過猴子修補程式修補其中一些程式庫。您可以藉由設定 APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL 環境變數來停用此功能。

注意

藉由設定該環境變數，事件可能無法與正確的作業正確建立關聯。

可藉由將 APPLICATION_INSIGHTS_NO_PATCH_MODULES 環境變數設定為所要停用套件的逗號分隔清單，來停用個別的 Monkey 修補檔。例如，使用 APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis 來避免修補 console 與 redis 套件。

目前，已檢測九個套件：bunyan、console、mongodb、mongodb-core、mysql、redis、winston、pg 與 pg-pool。如需已修補套件確切版本的詳細資訊，請參閱 diagnostic-channel-publishers 的讀我檔案。

bunyan、winston 和 console 修補程式會根據 setAutoCollectConsole 啟用與否來產生 Application Insights 追蹤事件。其餘項目會根據是否啟用 setAutoCollectDependencies 來產生 Application Insights 相依性事件。

即時計量

若要從您的應用程式將即時計量傳送至 Azure，請使用 setSendLiveMetrics(true)。目前，不支援在入口網站中篩選即時計量。

擴充計量

注意

已於 1.4.0 版中新增傳送擴充原生計量的功能。

若要啟用從您的應用程式將擴充原生計量傳送至 Azure，請安裝個別的原生計量套件。 SDK 會在安裝時自動載入，並開始收集 Node.js 原生計量。

npm install applicationinsights-native-metrics

目前，原生計量套件會執行記憶體回收 CPU 時間、事件迴圈刻度和堆積使用量的自動收集：

記憶體回收：花費在每個類型記憶體回收的 CPU 時間量，以及每個類型的發生次數。
事件迴圈：發生多少刻度以及總共花費多少 CPU 時間。
堆積與非堆積的比較：您的應用程式記憶體使用量在堆積或非堆積中各是多少。

分散式追蹤模式

根據預設，SDK 將會傳送可由使用 Application Insights SDK 檢測的其他應用程式或服務所辨識的標頭。除了現有的 AI 標頭之外，您也可以啟用傳送及接收 W3C 追蹤內容標頭。如此一來，您就不會中斷與任何現有舊版服務的相互關聯。啟用 W3C 標頭，將允許您的應用程式與其他未使用 Application Insights 檢測但確實採用此 W3C 標準的服務相互關聯。

const appInsights = require("applicationinsights");
appInsights
  .setup("<your connection string>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .start()

TelemetryClient API

如需 TelemetryClient API 的完整說明，請參閱自訂事件和度量的 Application Insights API。

您可以使用適用於 Node.js 的 Application Insights 用戶端程式庫來追蹤任何要求、事件、計量或例外狀況。下列程式碼範例示範您可以使用的一些 API：

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming connection string in env var. start() can be omitted to disable any non-custom data
let client = appInsights.defaultClient;
client.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
client.trackException({exception: new Error("handled exceptions can be logged with this method")});
client.trackMetric({name: "custom metric", value: 3});
client.trackTrace({message: "trace message"});
client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});
client.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

let http = require("http");
http.createServer( (req, res) => {
  client.trackNodeHttpRequest({request: req, response: res}); // Place at the beginning of your request handler
});

追蹤相依項目

您可以使用下列程式碼來追蹤相依項目：

let appInsights = require("applicationinsights");
let client = new appInsights.TelemetryClient();

var success = false;
let startTime = Date.now();
// execute dependency call here....
let duration = Date.now() - startTime;
success = true;

client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:duration, resultCode:0, success: true, dependencyTypeName: "ZSQL"});;

使用 trackMetric 測量事件迴圈排程所花費時間的範例公用程式：

function startMeasuringEventLoop() {
  var startTime = process.hrtime();
  var sampleSum = 0;
  var sampleCount = 0;

  // Measure event loop scheduling delay
  setInterval(() => {
    var elapsed = process.hrtime(startTime);
    startTime = process.hrtime();
    sampleSum += elapsed[0] * 1e9 + elapsed[1];
    sampleCount++;
  }, 0);

  // Report custom metric every second
  setInterval(() => {
    var samples = sampleSum;
    var count = sampleCount;
    sampleSum = 0;
    sampleCount = 0;

    if (count > 0) {
      var avgNs = samples / count;
      var avgMs = Math.round(avgNs / 1e6);
      client.trackMetric({name: "Event Loop Delay", value: avgMs});
    }
  }, 1000);
}

將自訂屬性新增至所有事件

您可以使用下列程式碼來將自訂屬性新增至所有事件：

appInsights.defaultClient.commonProperties = {
  environment: process.env.SOME_ENV_VARIABLE
};

追蹤 HTTP GET 要求

您可以使用下列程式碼來手動追蹤 HTTP GET 要求：

注意

預設會追蹤所有要求。若要停用自動收集，請在呼叫 start() 之前先呼叫 .setAutoCollectRequests(false)。
傳統 Application Insights 不會自動追蹤原生擷取 API 要求；需要手動相依性追蹤。

appInsights.defaultClient.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

或者，您可以使用 trackNodeHttpRequest 方法來追蹤要求：

var server = http.createServer((req, res) => {
  if ( req.method === "GET" ) {
      appInsights.defaultClient.trackNodeHttpRequest({request:req, response:res});
  }
  // other work here....
  res.end();
});

追蹤伺服器啟動時間

您可以使用下列程式碼來追蹤伺服器的啟動時間：

let start = Date.now();
server.on("listening", () => {
  let duration = Date.now() - start;
  appInsights.defaultClient.trackMetric({name: "server startup time", value: duration});
});

清除

根據預設，遙測會在傳送至擷取伺服器之前緩衝 15 秒。若您的應用程式只有短暫的生命週期 (例如 CLI 工具)，則可能需要在應用程式終止時，使用 appInsights.defaultClient.flush() 手動排清緩衝遙測。

若 SDK 偵測到您的應用程式損毀，則會使用 appInsights.defaultClient.flush({ isAppCrashing: true }) 為您呼叫排清。有了排清選項 isAppCrashing，您的應用程式會假設處於異常狀態，而不適用於傳送遙測。相反地，SDK 會將所有緩衝的遙測儲存到永續性儲存體，並讓應用程式終止。當您再次啟動應用程式時，便嘗試傳送任何儲存至永續性儲存體的遙測。

使用遙測處理器前置處理資料

您可以先使用「遙測處理器」處理及篩選收集到的資料，然後將其傳送以供保留。遙測處理器會依新增的順序逐一呼叫，再將遙測項目傳送至雲端。

public addTelemetryProcessor(telemetryProcessor: (envelope: Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

若遙測處理器傳回 false，則不會傳送該遙測項目。

所有遙測處理器都會接收遙測資料及其信封，以檢查和修改。也會接收內容物件。呼叫手動追蹤遙測的追蹤方法時，contextObjects 參數會定義此物件的內容。針對自動收集的遙測，此物件會填入由 appInsights.getCorrelationContext() 提供的可用要求資訊和永續性要求內容 (如果已啟用自動相依性相互關聯)。

遙測處理器的 TypeScript 類型為：

telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean;

例如，從例外狀況中移除堆疊追蹤資料的處理器可能會寫入並新增，如下所示：

function removeStackTraces ( envelope, context ) {
  if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
    var data = envelope.data.baseData;
    if (data.exceptions && data.exceptions.length > 0) {
      for (var i = 0; i < data.exceptions.length; i++) {
        var exception = data.exceptions[i];
        exception.parsedStack = null;
        exception.hasFullStack = false;
      }
    }
  }
  return true;
}

appInsights.defaultClient.addTelemetryProcessor(removeStackTraces);

使用多個連接字串

您可以建立多個 Application Insights 資源，並且使用各自的連接字串將不同的資料傳送至各個資源。

例如：

let appInsights = require("applicationinsights");

// configure auto-collection under one connection string
appInsights.setup("Connection String A").start();

// track some events manually under another connection string
let otherClient = new appInsights.TelemetryClient("Connection String B");
otherClient.trackEvent({name: "my custom event"});

進階組態選項

用戶端物件包含 config 屬性，其中包含許多進階案例的選擇性設定。若要加以設定，請使用：

client.config.PROPERTYNAME = VALUE;

這些屬性是用戶端特定的，因此您可以從使用 new appInsights.TelemetryClient() 建立的用戶端分開設定 appInsights.defaultClient。

屬性	描述
connectionString	適用於您 Application Insights 資源的識別碼。
endpointUrl	要將遙測承載傳送至其中的擷取端點。
quickPulseHost	要將即時計量遙測傳送至其中的即時計量串流主機。
proxyHttpUrl	SDK HTTP 流量的 Proxy 伺服器。 (選擇性。自 `http_proxy` 環境變數提取預設值。)
proxyHttpsUrl	SDK HTTPS 流量的 Proxy 伺服器。 (選擇性。自 `https_proxy` 環境變數提取預設值。)
httpAgent	要用於 SDK HTTP 流量的 http.Agent。 (選擇性。預設值為未定義。)
httpsAgent	要用於 SDK HTTPS 流量的 https.Agent。 (選擇性。預設值為未定義。)
maxBatchSize	要包含在擷取端點之承載中的遙測項目數目上限。 (預設值為 `250`。)
maxBatchIntervalMs	等候承載到達 maxBatchSize 的時間長度上限。 (預設值為 `15000`。)
disableAppInsights	指出是否停用遙測傳輸的旗標。 (預設值為 `false`。)
samplingPercentage	應該傳輸的已追蹤遙測項目百分比。 (預設值為 `100`。)
correlationIdRetryIntervalMs	重試擷取跨元件相互關聯之前的等候時間。 (預設值為 `30000`。)
correlationHeaderExcludedDomains	要從跨元件相互關聯標頭插入排除的網域清單。 (預設。請參閱 Config.ts。)

常見問題集

如何停用遙測相互關聯？

若要停用遙測相互關聯，請使用設定中的 correlationHeaderExcludedDomains 屬性。如需詳細資訊，請參閱 ApplicationInsights-node.js。

疑難排解

如需移難排解資訊 (包含「無資料」案例和自訂記錄)，請參閱針對 Node.js 應用程式和服務的 AppInsights 監視進行疑難排解。

共用方式為