Monitoring Node.js

The Instana Node.js 收集器

Instana Node.js 收集器是一個 npm 套件，您可以新增至 Node.js 應用程式的相依關係，以啟用度量值收集及自動追蹤，以及向 Instana 報告度量值和追蹤資料。

僅限 伺服器

此套件用於監視具有 Instana 的 Node.js 伺服器應用程式 。 如果您想要監視在瀏覽器中執行的 JavaScript 應用程式，請參閱 網站監視上的文件。

安裝

若要安裝 Instana Node.js 收集器並讓 Instana 監視您的 Node.js 應用程式，請透過下列方式安裝 npm 套件 @instana/collector :

npm install --save @instana/collector

既然已安裝收集器，則需要從應用程式內啟動它。 作法是要求 並起始設定 它作為應用程式中的第一個陳述式:

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

如需更深入的資訊，請參閱 安裝頁面。

Kubernetes

如果 Node.js 應用程式只在 Kubernetes上執行，請考慮改用 Instana AutoTrace WebHook 方法，這不需要修改您的應用程式。

附註: 如果您使用 Instana AutoTrace Webhook 並計劃使用 Instana Node.js SDK ，請檢閱 搭配使用 API 與 AutoTrace WebHook 區段。

Apigee Microgateway

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

配置

如需如何 配置 Instana Node.js 收集器的相關資訊，請參閱 配置頁面。

Kubernetes & OpenShift

如果 Node.js 應用程式及 Instana 代理程式在 Kubernetes 叢集裡執行，請檢查 Kubernetes 網路存取權 上的說明文件，以取得此設定中必要配置的相關資訊。

Cloud Foundry

附註: 本節假設 Instana 代理程式目前正在 Cloud Foundry 基礎的 Diego Cell 上執行。 如果沒有在基礎 Diego Cell 上執行代理程式，則不支援監視 Cloud Foundry 應用程式。 此外，從 Tile 1.177.0版開始， instana_buildpack 會在 Cloud Foundry上自動設定 Node.js 應用程式。 如需相關資訊，請參閱 Instana 建置套件 說明文件。

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

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

API

Instana Node.js 收集器套件提供用於自訂追蹤等的 API。 如需相關資訊，請參閱 API 頁面 。

支援的 Node.js 版本

Instana Node.js 收集器支援下列 Node.js 版本:

Node.js 版本 收集器版本
20.3.0 及更高版本 2.26.0 -最新
18.0.0 及以上版本 2.4.0 -最新
16.0.0 及以上版本 1.125.0 -最新
14.0.0 及以上版本 1.97.0 -最新
12.0.0 及以上版本 1.67.0 -最新
10.4.0 及以上版本 1.38.0 -最新
8.2.1 及以上版本 1.28.0 - 1.x
6.0.0 及以上版本 1.0.0 - 1.x
4.5 及以上版本 1.0.0 - 1.103.0
5.10 及以上版本 1.0.0 - 1.103.0

主要收集器版本

  • 現行主要版本: v2
  • 舊版主要: v1

附註: 對於舊版主要版本，只會發行 高 嚴重性安全及錯誤修正程式。 建議儘快切換至現行主要版本。

長期支援

遵循官方 LTS & end-of-life (EOL) timeline from Node.js 。

只要 Node.js 版本達到其 EOL 日期， 就會提供至少一年且最多兩年的支援。 定期更新 Node.js 版本以避免問題。

附註: Node v6 & v8 support has been dropped in @instana/collector@2.x. 如果您想要與 v6 或 v8一起使用，請使用 @instana/collector@1 。

版本化

遵循 semver 規格 。

附註: 請注意， npm install @instana/collector@latest 一律會安裝 最新主要版本。

附註: package.json 中的收集器版本應該固定至例如 @instana/collector: ^2.x.y。 這表示您將自動接收新特性 (次要版本) 及錯誤修正程式 (修補程式版本) ，但主要版本更新 (例如從 v1 至 v2) 需要手動步驟。 一律建議閱讀我們的 重大變更清單。

如需 AWS Fargate 和 Google Cloud 執行儲存器基本映像檔版本化架構的詳細資料，請參閱個別小節:

岔斷變更

您可以在 Github 變更日誌中找到所有變更。

從 v1 升級至 v2

請參閱 v2 岔斷變更 這裡。

  • 所有 Instana npm 套件 (@instana/collector、 @instana/aws-fargate、 @instana/aws-lambda 及 @instana/google-cloud-run) 2.0.0 版已捨棄對節點 v6 及 v8 的支援。 將 Node.js 版本升級至至少 v10.4.0。
  • 已移除對 reportUncaughtException 的支援。 此 (接受) 特性自 1.112.0版開始已淘汰。 如果您先前已使用此功能，則可以改為依賴 異常處理程序終止偵測 功能。 依預設會開啟異常處理程序終止偵測。
  • 配置選項 timeBetweenHealthcheckCalls 已從 instana({ tracing: { timeBetweenHealthcheckCalls: Boolean }}) 移至 instana({ tracing: { metrics: { timeBetweenHealthcheckCalls }}})。 如需相關資訊，請參閱 完整配置參照。
  • 已移除 logger 的配置選項。 您無法再使用 instana({logger: logger})。 請改用 instana.setLogger(logger) 。 如需相關資訊，請參閱 起始設定之後設定日誌程式。
  • 已移除配置選項 disableAutomaticTracing 。 您無法再使用 instana({ tracing: { disableAutomaticTracing: Boolean }})。 請改用 instana({ tracing: { automaticTracingEnabled: Boolean }}) 。 如需相關資訊，請參閱 停用自動追蹤。

支援的檔案庫

HTTP

標示為「自收集器版本」的直欄表示給定特性所需的 @instana/collector 最低版本。 如需詳細資料，請檢查 變更日誌 。

程式庫 自收集器版本
快速 錯誤處理 & 路徑範本 1.32.0, 1.43.0
Fastify 1.x 路徑範本 1.44.0
HTTP (s) 用戶端 1.10.0
HTTP (s) 伺服器 1.10.0
HTTP/2 用戶端 1.103.0
HTTP/2 伺服器 1.103.0
hapi 路徑範本 1.68.0
koa-router 路徑範本 1.56.0
要求-承諾 1.10.0
要求 1.10.0
超級代理程式 1.102.0

RPC

標示為「自收集器版本」的直欄表示給定特性所需的 @instana/collector 最低版本。 如需詳細資料，請檢查 變更日誌 。

程式庫 自收集器版本
Apollo 聯合 1.87.0
gRPC 1.63.1 [^ 10]
JavaScript gRPC 1.5.7
GraphQL 1.69.0

附註: 從 2021 年 4 月開始，原生 gRPC 程式庫已淘汰。 建議使用 @grpc/grpc-js。

資料庫

標示為「自收集器版本」的直欄表示給定特性所需的 @instana/collector 最低版本。 如需詳細資料，請檢查 變更日誌 。

程式庫 自收集器版本
AWS SDK v2 S3 1.115.0
AWS SDK v3 S3 1.129.0
AWS SDK v2 DynamoDB， 1.116.0
AWS SDK v3 DynamoDB， 1.127.0
Elasticsearch 舊式用戶端 (elasticsearch)) 1.10.0
Elasticsearch 現代用戶端 (@elastic/elasticsearch)) 1.96.0
Memcached (memcached) (>= 2.2.2) 1.126.0
MongoDB (mongodb) (>= 2.2) 1.13.0
Mongoose (mongoose) 1.13.0
MySQL (mysql) 1.29.0
MySQL (mysql2) 1.37.1
MSSQL (mssql) 1.47.0
普里斯馬 2.11.0
Postgres (pg) 1.44.2
Postgres (pg-native) 1.86.0
Redis (redis) 1.31.0
Redis (ioredis) 1.33.0
循序化 取決於驅動程式[1] [^ 10]
IBM DB2 2.2.0
Couchbase 2.21.0

傳訊

標示為「自收集器版本」的直欄表示給定特性所需的 @instana/collector 最低版本。 如需詳細資料，請檢查 變更日誌 。

程式庫 自收集器版本
AWS SNS SDK 第 2 版[2] [3] 1.136.0
AWS SQS SDK 第 2 版[2: 1] [3: 1] 1.114.0
AWS SQS SDK 第 3 版[2: 2] [3: 2] 1.132.0
AWS SDK v2 Kinesis 1.120.0
AWS SDK v3 Kinesis 2.30.0
Google Cloud PubSub[2: 3] (> = 1.2.0) 1.107.0
NATS 串流[2: 4] [4] 1.72.0
NATS[2: 5] [4: 1] 1.72.0
RabbitMQ/amqplib[2: 6] 1.51.0
kafka-node[2: 7] [4: 2] 1.20.0
kafkajs[2: 8] 1.83.0
node-rdkafka[2: 9] [4: 3] [5] [^ 10] 1.139.0
kafka-avro[2:10] [4: 4] 1.139.0
Bull[6] 1.119.0

雲端服務

標示為「自收集器版本」的直欄表示給定特性所需的 @instana/collector 最低版本。 如需詳細資料，請檢查 變更日誌 。

程式庫 自收集器版本
AWS SDK v2 SQS[2:11] [3: 3] 1.114.0
AWS SDK v3 SQS[2:12] [3: 4] 1.132.0
AWS SDK v2 S3 1.115.0
AWS SDK v3 S3 1.129.0
AWS SDK v2 DynamoDB 1.116.0
AWS SDK v3 DynamoDB 1.127.0
AWS SDK v2 SNS 1.136.0
AWS SDK v2 Kinesis 1.120.0
AWS SDK v3 Kinesis 2.30.0
Google Cloud Storage 1.105.0
Google Cloud PubSub[2:13] (> = 1.2.0) 1.107.0

記載

標示為「自收集器版本」的直欄表示給定特性所需的 @instana/collector 最低版本。 如需詳細資料，請檢查 變更日誌 。

程式庫 自收集器版本
Bunyan 1.54.0
express-winston[7] 1.88.0
log4js 1.84.0
皮諾 1.52.0
Winston (> = 3.x) 1.53.0
溫斯頓 (<= 2.x) 1.88.0

非同步

標示為「自收集器版本」的直欄表示給定特性所需的 @instana/collector 最低版本。 如需詳細資料，請檢查 變更日誌 。

程式庫 自收集器版本
非同步 1.10.0
Bluebird 1.35.0
原生 Promise 1.10.0
Q 1.10.0
計時器 1.10.0

其他

標示為「自收集器版本」的直欄表示給定特性所需的 @instana/collector 最低版本。 如需詳細資料，請檢查 變更日誌 。

程式庫 自收集器版本 評論
Apigee Microgateway/edgemicro (2.4， 2.5，> = 3.x) 1.89.0 需要其他安裝步驟。[8]

OpenTelemetry 檢測

Instana 使用特定 OpenTelemetry 工具來增加程式庫涵蓋面。

下表中的「自收集器版本」直欄表示特性所需的 Instana Node.js 收集器最低版本。 如需相關資訊，請參閱 變更日誌。

程式庫 自從收集器版本
socket.io [^ 11] 2.24.0
socket.io-client 2.24.0
restify[9] 2.24.0
fs 2.24.0

附註: 如果您遇到 OpenTelemetry 整合的問題，可以停用它。 如需如何停用整合的相關資訊，請參閱 停用 OpenTelemetry 整合。

[^ 10] 程式庫目前與 Node.js v20不相容。

[^ 11] 閱讀 此區段。

度量值集合

若要檢視度量值，請在「Instana 使用者」介面的資訊看板中選取 基礎架構 ，按一下特定的受監視主機，然後您可以看到具有所有已收集度量值及受監視處理程序的主機儀表板。

追蹤配置 度量值
執行時期版本 GC 活動
已部署的應用程式 記憶體用量
名稱 資料堆空間
版本 事件迴圈
說明 HTTP 伺服器-要求/回應時間
引數 性能檢查狀態及前次狀態變更的時間
相依關係
HTTP 伺服器配置
性能檢查 (透過 admin-plugin-healthcheck)

Node.js 處理程序的相依關係也可以從 軟體版本 API 端點擷取。

性能簽章

  • 記憶體回收活動
  • 延遲
  • 呼叫
  • 錯誤
  • 性能檢查失敗 (請參閱性能檢查支援，如下所示)

性能檢查支援

Instana Node.js 收集器將處理自訂性能檢查，並每十秒執行一次。 如果檢查失敗至少 30 秒，則會引發問題來通知使用者。

從已安裝的 admin-plugin-healthcheck 模組收集性能檢查。

性能檢查

Node.js 儀表板中列出的性能檢查。

問題

因性能檢查失敗而提出的問題。

Node.js EOL 版本警告

從 1.136.0版開始，當應用程式在 Node.jsEOL (壽命結束) 版本下執行時，收集器會傳送 問題事件 。

EOL Node.js 版本不再接收更新項目，這會讓應用程式容易遭到安全問題的攻擊，並錯過重要的執行時期改進，例如 CPU 及記憶體耗用最佳化。

建議依賴這些版本的客戶更新至 Node.js 的 作用中版本

請務必注意，儘管建議使用主動維護的運行環境， Instana 仍支援 舊版 Node.js。

追蹤支援

OpenCensus Instana 追蹤匯出器

Instana 為以 Node.js撰寫的應用程式提供 OpenCensus Trace Exporter 。 使用 Instana 代理程式處理程序作為 Proxy ， Instana 會將使用 Census 檢測的應用程式所匯出的追蹤資料轉遞至其後端。

如需相關資訊，請參閱 OpenCensus Exporters 網站。

AutoProfile™

附註: 此特性目前正在進行測試版測試。

AutoProfile™ 會自動且連續地將程序設定檔產生並報告給 Instana。 在 分析設定檔 區段中進一步瞭解設定檔。

若要啟用 AutoProfile™，請參閱 Node.js 收集器配置。

監視問題

Node.js 未安裝收集器

監視問題類型: nodejs_collector_not_installed

Node.js 處理程序尚未與代理程式連接以傳送追蹤資料及度量值。 這可能是因為下列其中一個原因：

  1. @instana/collector 套件未正確安裝在 Node.js 應用程式中。
  2. 由於網路連線功能問題， Node.js 處理程序無法向相同主機上的主機代理程式報告

驗證處理程序是否受監測

如果 @instana/collector 套件已新增至應用程式並正確啟動，您會在應用程式日誌中看到類似下列的項目:

Attempting agent communication via <hostname>:<port>

如果您在應用程式日誌中未看到任何這類訊息，則可能未正確安裝及起始設定套件 @instana/collector 。 安裝 文件提供視您的應用程式而定要執行的步驟概觀，而 一般陷阱 文件提供我們在一段時間內所看到的 gotchas 概觀。

如果 Node.js 應用程式在 Kubernetes中執行，您應該試用 Instana AutoTrace WebHook，它會自動並透通地將 Node.js 檢測新增至 Pod。

網路問題

如果已安裝 Node.js 收集器 (請參閱前一節) ，且您在應用程式日誌中看到下列訊息，則 @instana/collector 套件無法與主機代理程式通訊，且可能是網路問題:

Announce attempt failed: <error>. Will retry in <seconds>s.

驗證 Node.js 處理程序可以連接至埠 42699上相同主機上的主機代理程式。 如需所需網路可見性的相關資訊，請參閱 Instana 主機代理程式的 網路需求 文件。

我們越來越常看到的是，在儲存器化平台中，儲存器與要追蹤的應用程式及 Instana 主機代理程式的儲存器之間有網路可見性問題。 另一個相同類型的問題是，由於某個套版網路設定，要追蹤之應用程式的儲存器未連接至相同主機上的 Instana 代理程式儲存器。

通常問題是 Node.js 收集器使用錯誤的 IP 位址或 DNS 名稱來與 Instana 代理程式交談。 您可以指示 Node.js 收集器透過 INSTANA_AGENT_HOST 環境變數來使用者特定的網址。

在極少數情況下，我們看到客戶已設定其網路，因此問題不是網路位址，而是收集器使用的埠。 如果您需要埠重新對映，因為主機代理程式不會在埠 42699 上接聽，但會進行其他作業，您可以透過 INSTANA_AGENT_PORT 環境變數來指示收集器使用不同的埠。

如果上述都無法協助您對問題進行疑難排解，請開立 支援問題單。

收集器延遲起始設定

監視問題類型: nodejs_collector_initialized_too_late

為了確保追蹤正常運作，需要先需要並起始設定套件 @instana/collector ，然後才需要任何其他 Node.js 套件。 不過，套件可以啟發式偵測到它已起始設定太晚。 如果此警告顯示在 Node.js 儀表板上，則此偵測機制已判定在起始設定之前已載入其他套件。 如需相關詳細資料，請參閱 安裝 文件，特別是 一般陷阱 一節。

通常，使用 安裝而不修改原始碼 中概述的方法也有助於在進階建置及部署實務範例中解決此問題，尤其是在使用組合器 (例如 Webpack) 或 transpiler (Babel ， TypeScript， ...) 時。

AutoProfile 套件無法使用

監視問題類型: nodejs_collector_native_addon_autoprofile_missing

您已配置 Node.js 程序來使用 Instana 的 AutoProfile 特性 特性，但無法載入套件 @instana/autoprofile 。 因此，您將不會在 Instana 中取得此 Node.js 應用程式的側寫資訊。 套件 @instana/autoprofile 是 @instana/collector的選用相依關係，並在可能時自動安裝。 但由於它是原生附加程式，其安裝可能會失敗。

此情況的常見原因 (特別是儲存器化應用程式) 是目標機器或目標儲存器映像檔中遺漏用於建置 C++ 程式碼的必要作業系統套件。

另一個可能的主要原因是容器映像檔的建置方式。 需要在目標映像檔中安裝 Node.js 套件。 在建置系統上執行 npm install 或 yarn ，然後將整個 node_modules 資料夾複製到具有可能不同架構或作業系統的容器映像檔，將無法運作; 此步驟需要在目標映像檔內進行。

最後，如果已使用指令 npm install --no-optional 或 yarn --ignore-optional 來安裝相依關係，也會遺漏套件。

如需主題的相關資訊，請參閱 原生附加程式。

由於不受支援的觸發程式而遺漏呼叫

作為一般規則， Instana 追蹤程式只會在有作用中項目跨距時擷取送出呼叫。 在某些邊緣情況下，這可能會導致未擷取您預期要擷取的呼叫; 例如，當工作由我們的自動檢測不支援的機制所觸發時。 這些使用案例的解決方案是使用 Instana 的 Node.js SDK ，透過自訂追蹤來建立項目跨距。 如需詳細資料，請參閱 Node.js SDK 文件中的 本節 。

另請參閱

  1. Instana 不會直接檢測 Sequelize ，而是基礎資料庫驅動程式。 循序轉換的方式取決於您與 Sequelize 一起使用的資料庫程式庫 (mysql、 mysql2、 mssql、 pg、'pg-native ' 等)。 ↩︎

  2. 若要在耗用/接收具有 AWS SQS、 kafkajs、 kafka-node、 node-rdkafka、 kafka-avro、 RabbitMQ/amqplib、NATS、NATS 串流或 Google Cloud PubSub的訊息之後正確擷取後續呼叫，您需要使用 span.disableAutoEnd() 及 span.end()。 如需相關資訊，請參閱 手動結束跨距。 ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎

  3. 若要支援 AWS SDK v2 SQS ，當使用 async 或 await 函數的 promise 時，您需要 手動還原非同步環境定義 。 ↩︎ ↩︎ ↩︎ ↩︎ ↩︎

  4. 不支援 追蹤連續性

    • for NATS (因為 NATS 沒有訊息標頭，請參閱 NATS 追蹤文件) ，
    • 對於 NTS 串流 (因為 NAT 串流沒有訊息標頭，請參閱 NAT 追蹤文件) ，以及
    • 使用 npm 套件 kafka-node 來傳送或耗用訊息時，因為該套件不支援 Kafka 記錄標頭: 請參閱 kafka-node#763 及 kafka-node#1309)。 從其他執行時期 Kafka 0.11 版開始，以及使用套件 kafkajs時，一般支援 Kafka 的追蹤連續性。 因此，我們強烈建議在 Node.js 應用程式中使用 Kafka 及 Instana 時，使用 kafkajs 而非 kafka-node 。
    • 使用 node-rdkafka 或 kafka-avro 將訊息產生為 串流 時，其中 objectMode 選項未設定為 true。
    • 當使用 node-rdkafka 或 kafka-avro 來產生訊息時，由於 node-rdkafka 's header support of Buffer types發生問題，收集器的 headerFormat 選項會設為二進位。 請注意，當修正程式核准並在下一版 node-rdkafka中登陸時，問題將會消失。
    ↩︎ ↩︎ ↩︎ ↩︎ ↩︎

  5. 如果在起始設定 Producer時將選項 dr_cb 設為 true ，則檢測可以偵測是否已實際傳送訊息，且在該情況下只會建立對應的跨距。 如果 dr_cb 是 false 或取消設定，當 Producer.produce 方法終止時，檢測會假設已傳送訊息 (並建立對應的文字段)。 在極少數情況下，雖然呼叫 Producer.produce 實際上不會導致傳送訊息，但可能會產生跨距。 ↩︎

  6. 由於 API 未預期會適當檢測屬於大量的 Bull 可重複工作。 預期為 在最新版本的 Bull 中禁止 ↩︎

  7. 需要使用 statusLevels: true來配置 express-winston ，因為 Instana 只會擷取嚴重性為 warn 或更高的日誌訊息。 ↩︎

  8. 搭配使用 Apigee Microgateway/edgemicro 與 @instana/collector 需要其他安裝步驟。 請參閱此使用案例的 安裝指示 。 ↩︎

  9. OpenTelemetry 僅支援 restify 主要版本 8。 如需相關資訊，請參閱此 GitHub 問題。 ↩︎