Node.js 收集器安裝

CommonJS

既然已安裝收集器，則需要從應用程式內啟動它。 作法是要求 並起始設定 它作為應用程式中的第一個陳述式。 請注意這是 第一個陳述式 ，否則收集器將無法存取特定資訊。

require('@instana/collector')();

// All other require statements must be done after the collector is initialized.
// Note the () after the require statement of the collector which initializes it.


// const express = require('express');

上面顯示的程式碼會使用預設配置選項來起始設定收集器。 您也可以在起始設定 Instana Node.js 收集器時傳入配置物件。 請參閱 配置頁面 ，以取得有效配置選項的清單，特別是 代理程式通訊 一節，以取得在受監視應用程式與 Instana 代理程式之間配置連線功能的詳細資料。

ECMAScript 模組

當 @instana/collector 安裝為相依關係時，您需要透過 --experimental-loaders 引數載入 Instana Node.js 收集器，以啟動應用程式的收集器。 如需相關資訊，請參閱 ECMAScript 模組。

使用多個追蹤程式追蹤

不支援使用 Instana 及協力廠商追蹤器 (例如，同時使用 New Relic、Dynatrace 或 Datadog) 來追蹤單一 Node.js 應用程式。

光學

不支援在相同的 Node.js 應用程式中同時使用 OpenTelemetry SDK 及 Instana 收集器。 它可能會導致下列問題:

• Instana 中遺漏通話
• Instana 中有重複的資料
• 中斷的檢測

不建議您在相同的 Node.js 應用程式中同時使用 OpenTelemetry SDK 及 Instana 收集器。 如果您想要使用 Opentelemetry SDK ，請參閱 Node.js OpenTelemetry 整合。

Kubernetes & OpenShift

Cloud Foundry

附註: 本節假設 Instana 代理程式目前正在 Cloud Foundry 基礎的 Diego Cell 上執行。 如果沒有在基礎 Diego Cell 上執行代理程式，則不支援監視 Cloud Foundry 應用程式。

如需如何設定 Instana 代理程式及相關 Cloud Foundry 或 Pivotal Platform 功能的相關資訊，請參閱 Cloud Foundry 及 Pivotal Platform 文件。

在 Cloud Foundry上，不需要在 cf push 層次及應用程式資訊清單上進行配置。 唯一必要的步驟是依照上述說明，將 @instana/collector 套件新增至 Cloud Foundry Node.js 應用程式。

Apigee Microgateway

如需如何搭配使用 Instana Node.js 收集器套件與 Apigee Microgateway (也稱為 edgemicro) 的相關資訊，請參閱 Apigee Microgateway 頁面 。

Next.js

對於 Next.js 應用程式，建議使用 安裝而不修改原始碼中說明的方法。

安裝而不修改原始碼

在某些情況下，您無法 (或不想) 修改受監視應用程式的原始碼。 對於這些實務範例，可以使用下列方法。 這也是使用 Webpack、Babel 或任何其他類型的 Bundler 或 transpiler 所建置的應用程式的偏好方法。 最後 (但並非最不重要) ，它是 Next.js 應用程式的建議方法。

此方法有兩種特性:

1. 將 @instana/collector 安裝為專案的 本端相依關係 ，或
2. 在目標系統上安裝 @instana/collector 廣域 。

這兩種特性的詳細說明如下。

--experimental-loader /path/to/instana/node_modules/@instana/collector/esm-loader.mjs

--experimental-loader /path/to/instana/node_modules/@instana/collector/esm-loader.mjs

連結器 (Webpack 及類似)

安裝而不修改原始碼中說明當您使用組合器 (例如 Webpack 或累積更新) 預先處理 Node.js 伺服器應用程式時，偏好的安裝方法。

或者，如果您也可以安裝 @instana/collector 作為一般相依關係。

在這兩種情況下，您都需要確保僅組合您自己的程式碼，而不是 node_modules 資料夾中相依關係的程式碼。 有兩個原因:

• 模組 @instana/collector 不支援使用 Webpack 預先處理。 在其他問題中，程式碼中使用的動態 require 陳述式將無法正確解決。
• 為了檢測 協力廠商程式庫， npm 套件 @instana/collector 會截取 Node.js的 require 處理程序。 但是如果那些程式庫在執行時期未載入，而是在建置時期與您自己的程式碼組合，則不會執行 require 程序，且不會套用檢測。 Instana 追蹤在這類設定中無法運作或局部運作。 (確切地說，追蹤僅適用於 Node.js 核心模組 (例如 http ) ，因為依預設會從組合中排除這些模組。)

因此，強烈建議您配置組合器，以便 node_modules 中的所有項目都排除在所有程式碼轉換之外。

您可以使用模組 webpack-node-externals 來達到此目的:

// your webpack.config.js:

const nodeExternals = require('webpack-node-externals');

module.exports = {
  ...
  // externals: nodeModules,
  externals: [nodeExternals()],
  ...
};

如果您是使用 Angular CLI (特別是搭配 Angular Universal/SSR) ，您應該將 "externalDependencies": ["@instana/collector"] (可能還有 @instana/collector 工具的其他程式庫) 新增至 angular.json 檔，以將它/它們從組合中排除 (請參閱 這裡)。

轉換器 (Babel 等)

使用 transpiler (例如 Babel、Traceur 或 TypeScript 編譯器 tsc) 時的偏好安裝方法在 安裝而不修改原始碼中有說明。

或者，您可以將 @instana/collector 安裝為一般相依關係，但不建議使用此方法。 它需要您密切注意您的 transpiler 如何處理 import 和 require 陳述式。 如果您的 transpiler 處理 ES6 import 陳述式，則這是特定的匯入。 在這類設定中，將類似這樣的內容放在主要檔的頂端 將無法運作 :

import instana from '@instana/collector';

// THIS WILL NOT WORK because transpilers change the order of imports and statements.
instana();

import express from 'express';

為何不行？ 根據 ES6 規格， 在執行模組主體之前評估所有匯入項目。 Babel 及其他轉換程式符合此規則，並在轉換原始檔時將 所有 匯入項目移至頂端。 將在匯入之後放置所有實際的陳述式。 因此，此範例中 express 的匯入將置於 instana(); 呼叫之前。 在您的已轉換檔案中，您最後會遇到類似如下的情況:

var _instana = _interopRequireDefault(require("@instana/collector"));

var _express = _interopRequireDefault(require("express"));

var _morgan = _interopRequireDefault(require("morgan"));

function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

(0, _instana.default)(); // <- This is too late, since all other modules will already have been required.

...

如您所見， @instana/collector init 函數的實際呼叫是在轉換檔中的所有 require 陳述式之後。

相反地，您可以執行如下的動作:

// Put this import at the top of your main file. Only the import here,
// don't change this to "import instana from './instanaInit'"!
import './instanaInit';

// Now all the other imports can follow:
import express from 'express';
import morgan from 'morgan';

// The following statement is optional; it is only required if you want to use
// Instana's Node.js API (https://www.ibm.com/docs/en/instana-observability/current?topic=nodejs-instana-api):
// @ts-ignore (in case you are using TypeScript, to avoid 'Could not find a declaration file for '@instana/collector')
import instana from '@instana/collector';

檔案 instanaInit.js (如果您使用 TypeScript，則為 instanaInit.ts ) 應該只有下列一個陳述式:

require('@instana/collector')();

如此一來，當處理程序啟動時，即會立即呼叫 init 函數。

一般而言，當使用任何 transpiler 時，最好在整合 @instana/collector時檢查 transpiler 的輸出檔。

沒有原生附加程式的協助，部分資訊無法供 Node.js 程式使用。 具體而言， Instana Node.js 收集器使用下列附加程式:

• 擷取記憶體回收的相關資訊
• 擷取事件迴圈活動的相關資訊
• 適用於 側寫

所有原生附加程式都是 選用相依關係。 在沒有這些原生附加程式的情況下，收集器將正常運作，但將停用上述特性。 如果遺漏任何這些相依關係，則在啟動時，會將日誌訊息列印至應用程式日誌，如下所示:

Could not load @instana/autoprofile. You will not get profiling information for this Node.js app in Instana, although
autoprofiling has been enabled. This typically occurs when native add-ons could not be built during module installation
(npm install/yarn) or when npm install --no-optional or yarn --ignore-optional have been used to install dependencies.
See the instructions to learn more about the requirements of the collector:
https://www.ibm.com/docs/de/obi/current?topic=nodejs-collector-installation#native-add-ons

附註: 如果其他記憶體回收及事件迴圈度量值與您無關，且您不打算在 Node.js上使用 Instana AutoProfile 特性，則可以放心地忽略這些訊息。

遺漏原生附加程式有兩個可能的原因:

• 安裝與 npm install --no-optional 或 yarn --ignore-optional的相依關係。 如果該旗標存在，則 npm/yarn 甚至不會嘗試安裝這些相依關係。 若要修正該問題，請從安裝步驟中移除 --no-optional/--ignore-optional 旗標，或在 npm install --no-optional/yarn --ignore-optional 步驟之後為有問題的相依關係新增明確安裝步驟:
  • npm install @instana/autoprofile / yarn add @instana/autoprofile
  • npm install event-loop-stats / yarn add event-loop-stats
  • npm install gcstats.js / yarn add gcstats.js
• 在 npm install/yarn 步驟期間，附加程式編譯失敗。 本節的其餘部分說明發生這種情況的原因，以及如何修正它。

當安裝 Instana Node.js 收集器相依關係時 (作為 npm install 或 yarn 步驟的一部分) ，會針對您的系統及 Node.js 版本自動編譯原生附加程式。 若要使編譯運作，系統需要安裝 make、 g++ 及 python 等工具。 通常可以使用稱為 build-essential 或類似的軟體組來安裝這些工具 (視您作業系統的套件管理程式及登錄而定)。 下列範例顯示如何對熱門 Linux 發行套件執行此動作:

# for Debian-based distributions (including Ubuntu)
apt-get install build-essential
# or, for Fedora-based distributions (CentOS, Red Hat, etc.)
yum groupinstall "Development Tools"
# or, for Alpine Linux
apk add build-base python

重要事項: 相依關係的安裝需要在將執行應用程式的機器上進行。 否則，原生附加程式可能與目標機器的系統架構或使用中的 Node.js 版本不相容。 因此，在建置伺服器上執行指令 npm install/yarn ，然後將應用程式 (包括相依關係) 複製到目標機器，以安裝相依關係是 不當作法 。

如果您在容器中執行 Node.js 應用程式，則這方面需要額外注意。 您可能想要檢查 Docker 建置的輸出是否有 node-gyp 錯誤 (尋找 gyp ERR! 和 node-pre-gyp ERR!)。 如果這些存在，您應該檢查並評估它們。 其中一些可以被安全地忽略。 例如，部分套件可能嘗試下載經過前置編譯的二進位檔，如果失敗，則它們會透過 node-gyp 回復編譯，也就是說，如果編譯步驟已運作，則可以忽略下載錯誤。 其他套件在編譯期間會發出大量附註和警告，也可以忽略。

如果選用相依關係的安裝以 gyp ERR! not ok結束，您可能想要查看它。 雖然 Instana 可能無法提供修正特定 Dockerfile的支援，但我們確實提供一些 範例 Dockerfiles。

如果在執行 npm install時未順利安裝原生附加程式相依關係 (例如 gcstats.js 和 event-loop-stats ) ，套件 @instana/collector 會自動嘗試使用符合作業系統、 Node.js 版本及 libc 變式的預先建置二進位檔。 此功能僅在 x64 Linux上可用。 您可以設定 INSTANA_COPY_PRECOMPILED_NATIVE_ADDONS=false來停用它。

if (process.env.NODE_ENV !== 'development') {
  require('@instana/collector')();
}

export NODE_ENV=development
# -or-
NODE_ENV=development node myApp.js