AWS Lambda Native Trace for Node.js

Instana AutoTrace 設定

Node.js 的 Instana AutoTrace 設定可讓您追蹤 AWS Lambda 函數，以使用 Instana Lambda 層 和自訂函數處理程式。 此方法不需要修改 Lambda 函數碼，且完全透過配置來完成。 它也適合自動化或包含在 Lambda 部署管線中。

若要啟用 Node.js Lambda 函數的追蹤，請執行下列步驟:

1. 將 Instana Lambda 層新增至您的函數。

   1. 在 Lambda 函數的配置頁面中，按一下 Layers 方框，然後按一下 Add a layer。
   2. 在開啟的蹦現畫面中，選取「提供層版本 ARN」，然後複製並貼上符合您區域之 Instana Lambda 層的 ARN; 您可以在 Instana Lambda 層 區段中找到 Instana Lambda 層的右側 ARN。

2. 配置 Lambda 處理程式。 如果您使用 CommonJS，請將處理程式設為 instana-aws-lambda-auto-wrap.handler 。 如果您使用 ES 模組 (ES6) (可從第 223 版取得) ，請將處理程式設為 instana-aws-lambda-auto-wrap-esm.handler 。

   若要變更 Lambda 處理程式的設定，請在配置頁面上尋找「基本設定」區段。

   

   按一下編輯，並將 instana-aws-lambda-auto-wrap.handler 插入標籤為 "Handler" 的欄位。

   

   Instana Lambda 層會自動觸發預設 Node.js 執行時期處理程式 index.handler。 如果您使用自訂處理程式，請在環境變數 Lambda_handler 中指定處理程式，以通知 Instana Lambda 層。 請參閱下一節，以瞭解需要設定的所有環境變數。

   附註: Lambda 配置頁面可能會顯示類似「Lambda 找不到 instana-aws-lambda-auto-wrap.js檔案」的警告。 稍後回到配置頁面時也可能會顯示此畫面。 不要讓這個警告讓你分心。 處理程式包含在 Instana Lambda 層中，但 AWS Lambda 配置頁面不會將此納入考量。

3. 配置環境變數。 新增下列環境變數：

   • INSTANA_ENDPOINT_URL: 這是您的 無伺服器監視端點。 請務必對以 https://serverless-開頭的地區使用正確的值。
   • INSTANA_AGENT_KEY: 您的 代理程式金鑰。
   • LAMBDA_HANDLER: 設定自訂處理程式。 如果您的主要檔是 myModule.js(匯出函數 myHandler) ，請將環境變數設為 myModule.myHandler。 預設值為 index.handler。

   在下列範例中，原始主要 Lambda 處理程式是 index.js，因此您不需要設定環境變數 LAMBDA_HANDLER。

   在下列範例中，原始主要 Lambda 處理程式是 server.js，因此您需要將環境變數 Lambda _handler 設為 server.handler。

   您也可以移至 Instana 安裝架構，按一下「...」，以取得這些環境變數的正確值。 其他 "->" 代理程式 "->" 安裝 Instana 代理程式 "-> 平台:"AWS"-> 技術:"AWS Lambda "。

4. 儲存 Lambda 函數定義。

上述所有步驟都可以透過 AWS Web 主控台或任何一般 AWS 管理工具來完成，例如:

• aws 指令行介面
• 無伺服器架構 CLI
• AWS Cloud Development Kit

如果您想要自動化 AWS Lambdas 的 Instana 整合，以下是可能作為起點的 aws CLI 指令範例:

# Do not copy and paste this verbatim!
# It will overwrite any previously defined collection of layers and
# environment variables.
aws --region $YOUR_REGION lambda update-function-configuration \
  --function-name $YOUR_LAMBDA_FUNCTION_NAME \
  --layers $INSTANA_LAYER_ARN \
  --handler instana-aws-lambda-auto-wrap.handler \
  --environment ""Variables={INSTANA_ENDPOINT_URL=... , INSTANA_AGENT_KEY=... , ...}""

Instana Lambda 圖層

儲存器型函數的 Instana Lambda 層

如果您的團隊使用儲存器型 Lambda 部署，您可以在 icr.io/instana/aws-lambda-nodejs 上使用我們的基本儲存器，或在 Dockerfile 中包含下列 Snippet ，並將 建置時間引數 設為適當的版本。

# This is the container image that delivers Instana's monitoring capabilities.
# It will not become the base image for your Lambda container image, it just provides a few files.
FROM icr.io/instana/aws-lambda-nodejs:latest as instana-layer

# This is the actual base image for your Lambda container image. You can also use any other base image that is suitable
# for container image based Lambda functions.
FROM public.ecr.aws/lambda/nodejs:14

# Copy Instana's Node.js monitoring components into your Lambda container image.
COPY --from=instana-layer /opt/extensions/ /opt/extensions/
COPY --from=instana-layer /opt/nodejs/ /opt/nodejs/

# The remainder of your Dockerfile, as it was without adding the Instana layer. The following is just an example:
COPY index.js package.json package-lock.json /var/task/
WORKDIR /var/task
RUN npm install

# Override the CMD. This can also be done as a parameter override outside of the Dockerfile, for example in the AWS console.
# If you use ES modules, use CMD [ "instana-aws-lambda-auto-wrap-esm.handler" ] instead.
CMD [ "instana-aws-lambda-auto-wrap.handler" ]

Instead of icr.io/instana/aws-lambda-nodejs:latest, you can also use a specific version of the Instana npm module @instana/aws-lambda greater or equal to 1.137.2 (see CHANGELOG), so for example:

FROM icr.io/instana/aws-lambda-nodejs:1.140.1 as instana-layer

或者，您只能固定主要版本，同時容許更新的次要/修補程式版本:

FROM icr.io/instana/aws-lambda-nodejs:1 as instana-layer

附註: icr.io/instana/aws-lambda-nodejs 的未來版本將捨棄對舊版 Lambda Node.js 執行時期的支援。 例如，從 icr.io/instana/aws-lambda-nodejs:2.0.0版開始，將捨棄對 nodejs8.x 的支援。 建議您在使用較舊的 Lambda 執行時期時固定主要版本。

Instana Lambda 層及手動包裝

您也可以如上所述將 Instana Lambda 層新增至您的函數，但不要使用 instana-aws-lambda-auto-wrap.handler。 具體而言，這是基於 "Node.js 8.10" 執行時期的 AWS Lambdas 的建議方法。 以下是此設定的必要步驟:

1. 將 Instana Lambda 層新增至您的函數。 您可以在 上方表格中找到 Instana Lambda 層的 ARN。
2. 新增具有必要值的環境變數 INSTANA_ENDPOINT_URL 及 INSTANA_AGENT_KEY 。
3. 根據 手動包裝處理程式區段來修改函數的程式碼。

手動安裝 @instana/aws-lambda

您也可以選擇手動安裝 npm 套件 @instana/aws-lambda ，而不使用 Instana Lambda 層:

1. 透過在專案目錄中執行 npm install -S @instana/aws-lambda (或 yarn add @instana/aws-lambda) ，將相依關係 @instana/aws-lambda 新增至專案。 這會將套件新增至 node_modules 資料夾，並將相依關係儲存在 package.json 檔案中。
2. 新增具有必要值的環境變數 INSTANA_ENDPOINT_URL 及 INSTANA_AGENT_KEY 。
3. 根據 手動包裝處理程式區段來修改函數的程式碼。

手動包裝處理程式

如果您不想要或無法使用自動包裝處理程式，則需要稍微修改 Node.js AWS Lambda 函數的程式碼，以針對它啟用 Instana 追蹤。

附註: 如果您使用 Instana Lambda 層及自動包裝處理程式 (如 AutoTrace AWS Lambdas小節中所述) ，則不需要本節中說明的程式碼修改。

附註: 如果您將 Lambda 處理程式與 Web 套件組合在一起，則 不 建議使用此方法，因為 Instana 的核心套件不支援使用 Web 套件進行預先處理。 AutoTrace AWS Lambdas 方法適用於使用 Web 套件的 Lambdas。 作為替代方案，您可以使用手動包裝，並至少排除套件 @instana/aws-lambda (或所有相依關係) ，不由 Web 套件進行前置處理。 請參閱 Node.js 文件中的 本節 ; 如需無伺服器架構，也請參閱 無伺服器架構小節。

1. 將 const instana = require('@instana/aws-lambda'); 這一行新增至處理程式 JavaScript 檔案的最上層。
2. 在 instana.wrap() 呼叫中包裝處理程式函數。
3. 依照 AWS Lambda 的 Instana AutoTrace 說明文件的說明，配置 Instana 後端連線的環境變數。

以下是可用於 Node.js 型 AWS Lambdas 的不同處理程式函數樣式的一些之前/之後範例:

exports.handler = async (event, context) => {
  // your code
};

const instana = require('@instana/aws-lambda');

exports.handler = instana.wrap(async (event, context) => {
  // your code
}); // <- don't forget the closing ) for the instana.wrap(

exports.handler = (event, context) => {
  // your code, which returns a promise
};

const instana = require('@instana/aws-lambda');

exports.handler = instana.wrap((event, context) => {
  // your code, which returns a promise
}); // <- don't forget the closing ) for the instana.wrap(

exports.handler = (event, context, callback) => {
  // your code
};

const instana = require('@instana/aws-lambda');

exports.handler = instana.wrap((event, context, callback) => {
  // your code
}); // <- don't forget the closing ) for the instana.wrap(

exports.handler = instana.wrap({
    // ... your configuration, for example:
    tracing: {
      stackTraceLength: 10
    }
  },
  async (event, context) => {
  // your code
});

整合 Instana 追蹤與無伺服器架構

編輯 serverless.yml ，以整合 Instana 追蹤與 無伺服器架構。 請遵循下列步驟:

1. 從清單中複製 層 ARN ，並將 ARN 新增至目標函數定義的 層區段 。

2. 新增環境變數 INSTANA_AGENT_KEY、 INSTANA_ENDPOINT_URL 及 LAMBDA_HANDLER。 如需進一步資訊，請參閱 Instana AutoTrace 設定。

請參閱下列範例 serverless.yml:

service: service-a

provider:
  name: aws
  runtime: nodejs16.x
  stage: dev
  region: us-east-2

functions:
  with-layer:
    environment:
      INSTANA_ENDPOINT_URL: INSTANA_ENDPOINT_URL
      INSTANA_AGENT_KEY: INSTANA_AGENT_KEY
      LAMBDA_HANDLER: src/index.handler
    layers:
      - arn:aws:lambda:us-east-2:410797082306:layer:instana-nodejs:111
    handler: instana-aws-lambda-auto-wrap.handler

service: service-b

provider:
  name: aws
  runtime: nodejs12.x
  stage: dev
  region: us-east-2

plugins:
  - serverless-offline

custom:
  serverless-offline:
    useDocker: true

functions:
  with-serverless-offline:
    environment:
      NODE_PATH: $NODE_PATH:/opt/nodejs/node_modules
      INSTANA_ENDPOINT_URL: INSTANA_ENDPOINT_URL
      INSTANA_AGENT_KEY: INSTANA_AGENT_KEY
      LAMBDA_HANDLER: src/index.handler
    layers:
      - arn:aws:lambda:us-east-2:410797082306:layer:instana-nodejs:111
    handler: instana-aws-lambda-auto-wrap.handler

service: service-c

provider:
  name: aws
  runtime: nodejs12.x
  stage: dev
  region: us-east-2

plugins:
  - serverless-webpack

package:
  individually: true

functions:
  with-serverless-webpack:
    environment:
      INSTANA_ENDPOINT_URL: INSTANA_ENDPOINT_URL
      INSTANA_AGENT_KEY: INSTANA_AGENT_KEY
      LAMBDA_HANDLER: src/index.handler
    layers:
      - arn:aws:lambda:us-east-2:410797082306:layer:instana-nodejs:110
    handler: instana-aws-lambda-auto-wrap.handler
    entrypoint: src/index.handler

發動與忘記呼叫

如果您在 Node.js Lambda 函數中使用 fire-and-遺忘樣式呼叫， Instana 無法保證可靠地擷取那些呼叫。 發動並忘記呼叫是您不等待結果的任何非同步呼叫。 範例如下：

const fetch = require('node-fetch');

exports.handler = async event => {
  fetch('https://example.com/fire-and-forget'); // No await here!

  const response = await fetch('https://example.com/wait-for-me');

  return {
    message: response.text()
  };
}

這個 Lambda 處理程式使用 node-fetch 套件來進行兩個 HTTP 呼叫。 第二個呼叫是以 async 關鍵字來呼叫，因此執行會等待它完成。 將可靠地追蹤此呼叫。

與此相反，程式碼不會等待 第一個 呼叫 (fetch('https://example.com/fire-and-forget')) 的結果。 該呼叫可能已在 Lambda 執行完成或未完成時完成。 如果在整個 Lamba 執行終止時尚未完成，則不會將呼叫報告給 Instana 後端。 如果您在 Instana 使用者介面中檢查對應的追蹤，可能會看到一則警告，指出「在處理期間，此追蹤中的部分項目跨距遺漏母項跨距。」

此範例使用 async/await 樣式，但 promise-style 和 callback-style 程式碼也有類似的範例。

SSM 支援

可從第 99 版的層 instana-nodejs/@instana/aws-lambda@1.138.0取得。

您也可以透過 AWS SSM (System Manager) 參數儲存庫來提供 Instana 代理程式金鑰。

1. 將 Instana 代理程式金鑰新增至 SSM 參數儲存庫。 請記住或複製參數名稱。
2. 從環境變數中移除 INSTANA_AGENT_KEY 。
3. 使用所複製的參數名稱，將 INSTANA_SSM_PARAM_NAME 新增至您的環境變數。
4. 如果您已將參數新增為 "SecureString" ，則也需要設定 INSTANA_SSM_DECRYPTION=true。 如果您使用「字串」類型，則不需要設定其他變數。

附註: 如果您未從環境變數中移除 INSTANA_AGENT_KEY ，則會忽略 SSM 環境變數。

較舊 Node.js Lambda 執行時期

在撰寫本文時， Amazon 提供 Node.js 14、12 及 10 作為 Lambda 執行時期。 Instana 不支援已由 AWS (例如 Node 4 和 6) 解除任務的較舊 Node.js Lambda 執行時期。 如果您仍已部署使用那些執行時期的 Lambdas ，請將它們更新至較新的 Node.js Lambda 執行時期，然後再配置它們以進行原生 Instana 追蹤。 Node.js 8 目前仍受支援，雖然它已使用壽命結束。