Instana Node.js API

CommonJS

您只需要呼叫 @instana/collector 所匯出的起始設定函數一次，但您必須在 Node.js 應用程式的開頭，在任何其他 require 陳述式之前，以及在執行任何其他程式碼之前，這樣做:

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

起始設定函數會傳回本身的參照，如果您想要存取 Instana Node.js 收集器所提供的其他匯出項目，這會相關。 也就是說，下列兩個 Snippet 是相等的:

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

與下列相同:

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

起始設定函數接受一個選用參數，即配置物件:

const instana = require('@instana/collector')({
  // ... configuration object, see configuration documentation
});

如需配置物件的詳細資料，請參閱 配置頁面 。

如需安裝及起始設定 Instana Node.js 收集器的詳細資料，請參閱 安裝 及 一般陷阱 小節。

ESCMAScript 模組

對於使用 ECMAScript 模組系統的 Node.js 應用程式，起始設定 Instana Node.js 收集器的建議方法是 實驗性載入器旗標。 如果您想要在以 Node.js 應用程式為基礎的 ECMAScript 模組中使用 Instana Node.js SDK ，則可以取得 instana API 的參照，如下所示:

import instana from '@instana/collector';

您不需要再次起始設定 Instana Node.js 收集器，因為它由啟動時提供的 --experimental-loader 旗標來處理。

Kubernetes

當您使用 Instana AutoTrace WebHook時， Node.js 收集器會自動安裝在 /opt/instana/instrumentation/nodejs/node_modules/@instana/collector 目錄中。

如果您想要在 Kubernetes型 Node.js 應用程式中使用 Instana Node.js SDK ，建議您在專案中 安裝 @instana/collector 作為直接相依關係。

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

附註: 起始設定 Instana Node.js 收集器需要一些時間。 若要立即使用 SDK 開始建立跨距，請新增短暫延遲 (例如， 500 毫秒) ，以確保 Instana Node.js 收集器已備妥並已建立與 Instana 主機代理程式的連線。

手動結束跨距 (訊息分配管理系統項目)

我們之前提到 Instana 的自動化追蹤會為您處理 支援的程式庫 的所有項目，而且不需要干擾。 此規則有一個小型異常狀況: 從訊息分配管理系統 (Kafka、 RabbitMQ、NATS、NATS 串流、 Google Cloud PubSub) 耗用訊息所觸發的追蹤作業。 由於耗用來自訊息分配管理系統的訊息時沒有回應或回覆的記號，因此在特定訊息所觸發的所有作業都已完成時，沒有任何事件可以告知 Instana Node.js 收集器 (相對於一律具有相關聯回應的送入 HTTP 要求，可區分交易結束)。

當處理程序收到新訊息時，它會開始進入跨距。 Instana 的追蹤功能需要一些事件，表示此跨距已完成。 其他呼叫只有在啟動登錄跨距與完成它之間觸發時，才會指派給相同的追蹤。 因此，當處理送入訊息完成時，應用程式碼必須告知 Instana。 基於此目的，可以使用可使用 instana.currentSpan() 取得的目前作用中跨距的控點 (請參閱上述)。 此控點提供兩種與此使用案例相關的方法:

span.disableAutoEnd(): 停用自動完成跨距，並將此跨距標示為稍後透過呼叫 span.end() 手動完成的跨距。

span.end(errorCount): 完成先前已呼叫 span.disableAutoEnd() 的跨距。 errorCount 引數是選用的。 如果在處理訊息時發生錯誤，請傳遞 1 。 如果未傳遞任何內容，則 errorCount 預設為 0。

以下是 RabbitMQ的範例:

channel.consume(queueName, function(msg) {
  var span = instana.currentSpan();
  span.disableAutoEnd();

  // The setTimeout is a placeholder for any number of asynchronous operations
  // that are executed when processing this particular message. It could also be
  // database access calls or outgoing HTTP calls or really anything else.
  setTimeout(function() {

    // call span.end when processing of the incoming message has finshed. Make
    // sure to also call in case an error happens while processing the message.
    span.end();

  }, 5000);
});

請注意，如果您呼叫 span.disableAutoEnd() ，但忘記對它呼叫 span.end() ，則絕不會將跨距傳送至後端。

另請注意，對於訊息分配管理系統 (例如 Kafka、 RabbitMQ 及 NATS) ，如果您未在訊息處理函數中同步呼叫 span.disableAutoEnd() ，則會在訊息處理函數傳回之後 立即 結束並自動傳輸跨距。 這會岔斷該追蹤，亦即，在處理該訊息時所執行的作業 (DB 存取、送出 HTTP 呼叫、傳送其他訊息) 將不會顯示為 Instana 中的呼叫。

當 傳送/發佈 訊息至訊息分配管理系統時，不需要執行任何動作。

術語

SDK 提供功能來建立進入跨距、中間跨距及結束跨距。 簡而言之:

• 輸入文字段代表 進入 受監視應用程式的呼叫。 這些可能是應用程式 從其他服務接收 的 HTTP 要求，或應用程式從佇列中挑選的訊息。 (當然，自動追蹤已涵蓋 HTTP 要求。) 一般而言，項目跨距代表在 Node.js 應用程式內觸發處理的項目。 追蹤一律需要從項目跨距開始 (由自動檢測或透過 SDK 建立)。 Node.js 追蹤程式會保持非作用中，除非有作用中的進入跨距，否則不會擷取任何中間或結束跨距。 如需相關詳細資料，請參閱 當沒有作用中項目跨距時，追蹤處於非作用中狀態 一節。
• 結束跨距代表應用程式所進行的呼叫。 這些可能是應用程式 發出 (並由其他服務回應) 或資料庫呼叫的 HTTP 要求。 (同樣地，自動檢測已涵蓋送出的 HTTP 要求及許多常用資料庫。)
• 中間跨距是 在 受監視應用程式內發生的事情，亦即，它們既未進入也未離開處理程序，如進入跨距及結束跨距所執行。 如果您想要提供自動化設備測試未提供的其他屬性 (稱為 標籤) ，也可以使用中間文字段來包裝自動建立的文字段。

如需專有名詞的詳細資料，特別是 跨距 如何與您將在 Instana 使用者介面中看到的 呼叫 相關，請參閱我們的 追蹤文件。

在開始使用 SDK 實作自訂追蹤之前，還有一個關於 追蹤最佳作法 的章節值得閱讀。

最後，您可以在本端啟動示範應用程式，並檢查以協助您開始使用 Instana Node.js SDK: https://github.com/instana/instana-nodejs-demos/tree/master/sdk。

回呼型 API、Promise 型 API 及非同步 API

SDK 提供三種不同類型的 API: 一個回呼型 (instana.sdk.callback)、一個 promise 型 (instana.sdk.promise) ，以及一個使用 async/await 樣式的程式碼 (instana.sdk.async)。 用哪一個純粹是口味的問題。 基本上，這三個 API 都提供各種方法來啟動跨距及完成跨距。 您需要在執行您要跨距代表的工作之前直接啟動跨距，並在工作完成之後完成跨距。

使用回呼 API 時，每當您啟動新的跨距並在該回呼內執行與該跨距相關聯的所有工作時 (或在該回呼所觸發的任何非同步作業的回呼中) ，您都需要傳遞回呼。 範例如下：

instana.sdk.callback.startEntrySpan('my-custom-span', () => {
  // The actual work needs to happen inside this callback (or in the callback
  // of any asynchronous operation transitively triggered from this callback).
  ...
  doSomethingAsynchronous((err, result) => {
    if (err) {
      instana.sdk.callback.completeEntrySpan(err);
      logger.error(err);
      return;
    }
    instana.sdk.callback.completeEntrySpan();
    logger.info('Yay! 🎉', result);
  });
});

請注意，會立即同步呼叫提供給 startXxxSpan 的回呼，而不使用引數。 在該回呼內可以觸發其他非同步作業。

使用 promise API 時，所有啟動新跨距的方法都會傳回 promise。 與該跨距相關聯的所有工作都需要在該承諾鏈中進行 (亦即，在 startXxxSpan 所傳回之承諾的 then 中，或在該承諾鏈更往下的任何 then 處理程式中)。 範例如下：

instana.sdk.promise.startEntrySpan('my-custom-span').then(() => {
  // The actual work needs to happen inside the promise chain, that is, either
  // here or in any `then` handler further down the promise chain.
  return anotherPromise();
}).then(result => {
  instana.sdk.promise.completeEntrySpan();
  logger.info('Yay! 🎉', result);
}).catch(err => {
  instana.sdk.promise.completeEntrySpan(err);
  logger.error(err);
});

請注意， startXxxSpan 所傳回的承諾從未遭到拒絕，它會在沒有值的情況下立即解決。 其他非同步作業可以在其 then 處理程式內觸發。

對於非同步/等待樣式程式碼， SDK 提供 instana.sdk.async (從 1.81.0版開始):

await instana.sdk.async.startExitSpan('my-custom-span');
try {
  await someOtherAsynchronousOperation();
  instana.sdk.async.completeExitSpan();
} catch (err) {
  instana.sdk.async.completeExitSpan(err);
  logger.error(err);
}

在 hood 下， instana.sdk.async 只是 instana.sdk.promise的別名，因為 async/await 程式碼是透過 Node.js 運行環境中的 Promises 來處理。

completeXxxSpan 方法對於所有三個 API 內容都是相同的。

如果上述範例不夠，請確保跳至我們完全成熟的工作展示應用程式，展示 Node.js SDK: https://github.com/instana/instana-nodejs-demos/tree/master/sdk。

API 方法

SDK 方法接受下列 一般參數 :

• name: 跨距的名稱。 當啟動新的文字段時，此參數是必要的。 它應該是一個簡短且易於說明的字串。
• tags: 包含跨距的其他 meta 資料的選用 JS 物件。 您可以在開始跨距時及/或完成跨距時提供標籤。 如果您在開始及完成跨距時提供標籤，則會合併這兩個物件。 標籤將顯示在 Instana 使用者介面中。 您需要確保不要將任意大型物件新增至您建立的文字段。 應該使用短鍵值組。 如果跨距變得太大，可能會捨棄一批跨距，而不是傳送至 Instana 代理程式。
• error: 執行與現行跨距相關聯的工作時發生錯誤，完成跨距時可能會將此錯誤附加至跨距。
• traceId: 這僅與項目跨距相關，用於使項目跨距成為已在另一個處理程序中啟動的現有追蹤的一部分。 如果您提供 traceId，則還需要提供 parentSpanId。
• parentSpanId: 這僅適用於已在另一個程序中啟動之現有追蹤的項目跨距。 它用來參照觸發此進入跨距的結束跨距。 如果您提供 parentSpanId，則還需要提供 traceId。

下列 方法 由所有三個 API 提供:

• instana.sdk.callback.startEntrySpan(name [, tags[, traceId, parentSpanId]], callback)，
  instana.sdk.{promise|async}.startEntrySpan(name [, tags[, traceId, parentSpanId]]):
  啟動項目跨距。 您需要為跨距提供 name 。 您可以選擇性地提供 tags 物件。 traceId和 parentSpanId 也是選用項目，但您需要同時提供兩個 ID 或完全不提供 ID。
• instana.sdk.callback.completeEntrySpan([error, tags])，
  instana.sdk.{promise|async}.completeEntrySpan([error, tags]):
  完成項目跨距。 可以提供錯誤及其他標籤。 如果您想要提供其他標籤，但沒有錯誤，請傳遞 null 作為第一個引數。
• instana.sdk.callback.startIntermediateSpan(name[, tags], callback)，
  instana.sdk.{promise|async}.startIntermediateSpan(name[, tags]):
  開始中間跨距。 您需要為跨距提供 name ，並且可以選擇性地提供 tags 物件。 函數呼叫會傳回已啟動的跨距。
• instana.sdk.callback.completeIntermediateSpan([error, tags, span])，
  instana.sdk.{promise|async}.completeIntermediateSpan([error, tags, span]):
  完成中間跨距。 可以提供錯誤、其他標籤，以及要完成的跨距。 如果您想要提供沒有錯誤的其他標籤，請傳遞 null 作為第一個引數。
• instana.sdk.callback.startExitSpan(name[, tags], callback)
  ， instana.sdk.{promise|async}.startExitSpan(name[, tags]):
  開始結束跨距。 您需要為跨距提供 name ，並且可以選擇性地提供 tags 物件。
• instana.sdk.callback.completeExitSpan([error, tags])
  ， instana.sdk.{promise|async}.completeExitSpan([error, tags]):
  完成結束跨距。 可以提供錯誤及其他標籤。 如果您想要提供其他標籤，但沒有錯誤，請傳遞 null 作為第一個引數。
• instana.sdk.callback.bindEmitter(emitter)，
  instana.sdk.{promise|async}.bindEmitter(emitter):
  請參閱 如下。

請注意，以任何 startXxxSpan 方法開始的文字段，只有在呼叫對應的 completeXxxSpan 之後，才會傳輸至 Instana。 此外，對於巢狀跨距，呼叫必須以正確的順序進行。

為了說明這一點，請考量下列兩個範例。 以下是有效的:

const sdk = instana.sdk.callback;

sdk.startEntrySpan('my-custom-entry', () => {
  doSomethingAsynchronous(() => {
    sdk.startExitSpan('my-custom-exit', () => {
      doAnotherThingAsynchronous(() => {
        sdk.completeExitSpan();
        sdk.completeEntrySpan();
        logger.info('Yay! 🎉');
      });
    });
  });
});

但這不是有效的:

const sdk = instana.sdk.callback;

sdk.startEntrySpan('my-custom-entry', () => {
  doSomethingAsynchronous(() => {
    sdk.startExitSpan('my-custom-exit', () => {
      doAnotherThingAsynchronous(() => {
        // WRONG ORDER - you first need to complete the span you started last.
        // Think of the spans as stack.
        sdk.completeEntrySpan();
        sdk.completeExitSpan();
        logger.info('Yay! 🎉');
      });
    });
  });
});

使用 Promise API 建立巢狀跨距時，也必須小心。 下列是正確的:

instana.sdk.promise.startEntrySpan('custom-entry')
  // any number of other promises/async operations
  .then(() => {
    ...
  })
  .then(() => {
    return instana.sdk.promise.startExitSpan('custom-exit')
      // any number of other promises/async operations associated with the exit span
      .then(() => {
        ...
      })
      .then(() => {
        // Important: The exit span needs to be completed in the promise chain
        // started with startExitSpan, not in the outer promise chain started
        // with startEntrySpan.
        instana.sdk.promise.completeExitSpan();
      });
  })
  .then(() => {
    instana.sdk.promise.completeEntrySpan();
    logger.info('Yay! 🎉');
  });

但這不會成功:

instana.sdk.promise.startEntrySpan('custom-entry')
.then(() => {
  return instana.sdk.promise.startExitSpan('custom-exit');
})
.then(() => {
  // WRONG The currently active span in this context is the *entry* span, not
  // the exit span, so it is not possible to complete the exit span here.
  instana.sdk.promise.completeExitSpan();
  instana.sdk.promise.completeEntrySpan();
});

請參閱下列中間跨距的有效範例:

await instana.sdk.async.startIntermediateSpan('intermediate-span-name')

// trigger an internal request
await request(`http://127.0.0.1:${port}`)

instana.sdk.async.completeIntermediateSpan();

// This example demonstrates how to start two overlaping intermediate spans.
const span1 = await instana.sdk.async.startIntermediateSpan('intermediate-span-name-1')
await request(`http://127.0.0.1:${port}`)
const span2 = await instana.sdk.async.startIntermediateSpan('intermediate-span-name-2')
await request(`http://127.0.0.1:${port}`)

// Pass "span1" as third argument to signalise which span to complete.
instana.sdk.async.completeIntermediateSpan(null, null, span1);
await request(`http://127.0.0.1:${port}`)
instana.sdk.async.completeIntermediateSpan(null, null, span2);

此時，您可能會想知道 SDK 的 API 為何如此設計，特別是 startXxxSpan 方法接受回呼/傳回承諾的業務可能看起來很尷尬。 重點是我們需要在追蹤時保留非同步環境定義。 由於 Node.js 是單一執行緒，並使用回呼來執行非同步作業，因此 Node.js 收集器需要一種方法來判斷哪些作業屬於回呼中所追蹤動作的跨距折返，或承諾會使其成為可能。

處理事件發射程式

如果與自訂 SDK 跨距相關聯的工作涉及 事件發射程式 ，且如果在跨距內執行的程式碼接聽發出的事件，則您需要 連結 事件發射程式，否則追蹤程式碼不會如預期般運作。 方式如下：

instana.sdk.callback.startEntrySpan('custom-span', () => {
  const emitter = ... // some event emitter
  instana.sdk.callback.bindEmitter(emitter);
  ...
  emitter.on('some-event', () => {
    instana.sdk.callback.completeEntrySpan();
    logger.info('Done! 🎉');
  });
});

當沒有作用中項目跨距時，追蹤處於非作用中

作為一般規則，當有作用中的進入跨距時， Instana 追蹤程式只會擷取結束或中間跨距。 這是一項重要的保護措施，不會擷取與處理商業相關交易無關的雜訊。 不過，在一些邊緣個案中，這項保障可能會妨礙我們的工作。 包括由 Instana 的 自動檢測不支援的機制所觸發之工作的範例:

• 這可能是來自我們 (尚) 不支援的傳訊程式庫的送入訊息。
• 或者它可能是透過不受支援的通訊協定所提出的要求，例如原始 TCP 訊息或 websocket 通訊 (這兩者不受自動設備測試支援)。
• 另一個範例是執行排定工作的應用程式，這些排定工作不是從外部觸發，而是由處理程序本身觸發 (例如，使用 setTimeout、 setInterval 或不受支援的 Node.js 排程程式庫)。

沒有任何進入跨距的結果是 Instana Node.js 追蹤器也不會針對在此環境定義中進行的呼叫擷取任何其他中間或結束跨距。 亦即：

• 如果透過 支援的程式庫觸發送出的 HTTP 要求、資料庫呼叫或會建立結束跨距的任何其他項目，但沒有作用中的進入跨距，則不會擷取該結束跨距。
• 如果使用 Instana Node.js SDK 來啟動中間或結束跨距，但沒有作用中的進入跨距，則 SDK 將拒絕以啟動該跨距。 將會記載此相關的警告。

這種狀況的解決方案是在工作片段開始時手動 開始進入跨距 ，並在完成時 完成它 。 這樣，將會擷取所有結束及中間跨距，因為有作用中的進入跨距。

您也可以 建立特性要求 ，以針對您正在使用的觸發程式類型實作現成可用的支援。

限制

• OpenTracing 未與 Instana 的自動追蹤整合。 尤其是使用 OpenTracing API 所建立的文字段，將不會與自動追蹤設備測試所建立的文字段屬於相同的追蹤。 如果您想要將 其他 文字段新增至自動建立的文字段，您應該偏好 SDK 而非 OpenTracing。 事實上，我們建議使用自動追蹤 (選擇性地由 SDK 文字段擴增) 或 OpenTracing，但不能在一個應用程式中同時使用兩者。
• Instana Node.js 收集器不支援 OpenTracing 二進位載波。 這個 OpenTracing 實作會無聲自動忽略 OpenTracing 二進位載波物件。
• OpenTracing 行李物品也要小心。 行李物品是跨網路界限透過承運方物件傳輸的 meta 資料。 此外，此 meta 資料由子項跨距 (及其子項跨距 ...) 繼承。. 這可能會產生一些額外負擔。 建議完全避免使用 OpenTracing 行李 API。