AWS Native Lambda-Traceerstellung für Node.js

Diese Seite enthält Informationen zur Konfiguration von Instana AutoTrace für AWS -Lambda-Funktionen, die in Node.jsgeschrieben sind.

Unterstützte Laufzeiten

  • nodejs20.x
  • nodejs18.x
  • nodejs16.x
  • nodejs14.x

Installation

In dieser Dokumentation wird erläutert, wie die Traceerstellung für Node.js -Lambda-Funktionen konfiguriert wird. Stellen Sie sicher, dass Sie auch die Konfiguration des AWS -Agenten für die Lambda-Überwachung durchgeführt haben , um sicherzustellen, dass erforderliche Informationen zu Versionen und einigen Laufzeitmetriken erfasst werden, die Instana nicht aus der Lambda-Laufzeit von AWS erfassen kann.

Die bevorzugte Methode zum Aktivieren der AWS -Lambda- Node.js -Traceerstellung ist die Ausführung der Anweisungen unter AutoTrace . Wenn aus irgendeinem Grund, der aufgrund von Einschränkungen der Laufzeitversion oder anderer lokaler Einschränkungen nicht möglich ist, gibt es weitere Optionen, die nachfolgend aufgelistet sind.

Konfiguration von Instana AutoTrace

Mit der Instana AutoTrace-Konfiguration für Node.js können Sie Ihre AWS Lambda-Funktionen verfolgen, indem Sie das Instana Lambda-Layer und einen angepassten Funktionshandler verwenden. Dieser Ansatz erfordert keine Änderung des Lambda-Funktionscodes und erfolgt allein über die Konfiguration. Er eignet sich auch für die Automatisierung oder für eine Lambda-Implementierungspipeline.

Führen Sie die folgenden Schritte aus, um das Tracing für Node.js-Lambda-Funktionen zu aktivieren:

  1. Fügen Sie das Instana Lambda-Layer zu Ihrer Funktion hinzu.

    1. Klicken Sie auf der Konfigurationsseite für Ihre Lambda-Funktion auf das Feld Layers und anschließend auf Add a layer Schicht .
    2. Wählen Sie im Popup-Fenster, das geöffnet wird, "Geben Sie eine Ebenenversion an ARN" aus und kopieren Sie die ARN für die Instana-Lambda-Schicht, die Ihrer Region entspricht. Sie finden die richtige ARN für die Instana-Lambda-Schicht im Abschnitt Instana-Lambda-Schichten . Schichtauswahl
  2. Konfigurieren Sie den Lambda-Handler. Setzen Sie den Handler auf instana-aws-lambda-auto-wrap.handler , wenn Sie CommonJSverwenden. Setzen Sie den Handler auf instana-aws-lambda-auto-wrap-esm.handler , wenn Sie ES Modules (ES6) verwenden (verfügbar ab Version 223).

    Um die Einstellung für den Lambda-Handler zu ändern, suchen Sie den Abschnitt "Grundeinstellungen" auf der Konfigurationsseite.

    Basiseinstellungen, Schaltfläche 'Bearbeiten'

    Klicken Sie auf "Bearbeiten" und fügen Sie instana-aws-lambda-auto-wrap.handler in das Feld "Handler" ein.

    Basiseinstellungen bearbeiten, um die Steuerroutine von Instana festzulegen

    Die Instana-Lambda-Schicht löst automatisch den standardmäßigen Node.js -Laufzeithandler index.handleraus. Wenn Sie einen angepassten Handler verwenden, geben Sie Ihren Handler in der Umgebungsvariablen LAMBDA_HANDLER an, um die Instana Lambda Layer zu benachrichtigen. Im nächsten Abschnitt finden Sie Informationen zu allen Umgebungsvariablen, die festgelegt werden müssen.

    Auf der Lambda-Konfigurationsseite wird möglicherweise eine Warnung wie die folgende angezeigt: "Lambda kann die Datei instana-aws-lambda-auto-wrap.jsnicht finden." Diese Nachricht wird möglicherweise auch später angezeigt, wenn Sie zur Konfigurationsseite zurückkehren. Lassen Sie sich von dieser Warnung nicht ablenken. Der Handler ist im Instana Lambda-Layer enthalten, aber die AWS Lambda-Konfigurationsseite berücksichtigt dies nicht.

  3. Konfigurieren Sie Umgebungsvariablen. Fügen Sie die folgenden Umgebungsvariablen hinzu:

    • INSTANA_ENDPOINT_URL: Dies ist Ihr serverloser Überwachungsendpunkt. Stellen Sie sicher, dass Sie den richtigen Wert für Ihre Region verwenden, der mit https://serverless- beginnt.
    • INSTANA_AGENT_KEY: Ihr Agentenschlüssel
    • LAMBDA_HANDLER: Legen Sie Ihren angepassten Handler fest. Wenn Ihre Hauptdatei myModule.jsist, die die Funktion myHandlerexportiert, setzen Sie die Umgebungsvariable auf myModule.myHandler. Der Standardwert ist index.handler.

    Im folgenden Beispiel ist der ursprüngliche Lambda-Haupthandler index.jsund Sie müssen daher die Umgebungsvariable LAMBDA_HANDLERnicht festlegen. Einstellungen für Standardumgebungsvariablen

    Im folgenden Beispiel ist der ursprüngliche Lambda-Haupthandler server.jsund Sie müssen daher die Umgebungsvariable LAMBDA_HANDLER auf server.handlersetzen. Einstellungen für angepasste Umgebungsvariablen

    Sie können auch die richtigen Werte für diese Umgebungsvariablen erhalten, indem Sie Ihre Instana-Installation aufrufen und auf " ... Mehr "->" Agenten "->" Instana-Agenten installieren "-> Plattform:"AWS"-> Technologie:"AWS Lambda "

  4. Definition der Lambda-Funktion speichern. sichern

Alle oben beschriebenen Schritte können entweder über die AWS-Webkonsole oder eines der üblichen AWS-Management-Tools erfolgen, wie z. B.:

Hier ein Beispiel für einen aws-CLI-Befehl, der als Ausgangspunkt dienen kann, wenn Sie die Instana-Integration Ihrer AWS Lambdas automatisieren möchten:

# 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=... , ...}""

Instanziierung von Lambda-Schichten

Architektur x86_64

Die ARNs der neuesten Version der AWS -Lambda-Schichten für die unter Unterstützte Laufzeiten aufgelisteten Lambda-Laufzeiten sind für jede Region die folgenden:

Bereich ARN @instana/aws-lambda-Version
af-south-1 arn:aws:lambda:af-south-1:410797082306:layer:instana-nodejs:25 3.3.0
ap-east-1 arn:aws:lambda:ap-east-1:410797082306:layer:instana-nodejs:25 3.3.0
ap-northeast-1 arn:aws:lambda:ap-northeast-1:410797082306:layer:instana-nodejs:181 3.3.0
ap-northeast-2 arn:aws:lambda:ap-northeast-2:410797082306:layer:instana-nodejs:179 3.3.0
ap-northeast-3 arn:aws:lambda:ap-northeast-3:410797082306:layer:instana-nodejs:25 3.3.0
ap-south-1 arn:aws:lambda:ap-south-1:410797082306:layer:instana-nodejs:179 3.3.0
ap-south-2 arn:aws:lambda:ap-south-2:410797082306:layer:instana-nodejs:25 3.3.0
ap-southeast-1 arn:aws:lambda:ap-southeast-1:410797082306:layer:instana-nodejs:179 3.3.0
ap-southeast-2 arn:aws:lambda:ap-southeast-2:410797082306:layer:instana-nodejs:179 3.3.0
ap-southeast-3 arn:aws:lambda:ap-southeast-3:410797082306:layer:instana-nodejs:25 3.3.0
ap-southeast-4 arn:aws:lambda:ap-southeast-4:410797082306:layer:instana-nodejs:25 3.3.0
ca-central-1 arn:aws:lambda:ca-central-1:410797082306:layer:instana-nodejs:179 3.3.0
cn-north-1 arn:aws-cn:lambda:cn-north-1:107998019096:layer:instana-nodejs:12 3.3.0
cn-northwest-1 arn:aws-cn:lambda:cn-northwest-1:107998019096:layer:instana-nodejs:12 3.3.0
eu-central-1 arn:aws:lambda:eu-central-1:410797082306:layer:instana-nodejs:178 3.3.0
eu-central-2 arn:aws:lambda:eu-central-2:410797082306:layer:instana-nodejs:24 3.3.0
eu-north-1 arn:aws:lambda:eu-north-1:410797082306:layer:instana-nodejs:178 3.3.0
eu-south-1 arn:aws:lambda:eu-south-1:410797082306:layer:instana-nodejs:24 3.3.0
eu-south-2 arn:aws:lambda:eu-south-2:410797082306:layer:instana-nodejs:24 3.3.0
eu-west-1 arn:aws:lambda:eu-west-1:410797082306:layer:instana-nodejs:178 3.3.0
eu-west-2 arn:aws:lambda:eu-west-2:410797082306:layer:instana-nodejs:178 3.3.0
eu-west-3 arn:aws:lambda:eu-west-3:410797082306:layer:instana-nodejs:178 3.3.0
il-central-1 arn:aws:lambda:il-central-1:410797082306:layer:instana-nodejs:21 3.3.0
me-central-1 arn:aws:lambda:me-central-1:410797082306:layer:instana-nodejs:23 3.3.0
me-south-1 arn:aws:lambda:me-south-1:410797082306:layer:instana-nodejs:23 3.3.0
sa-east-1 arn:aws:lambda:sa-east-1:410797082306:layer:instana-nodejs:177 3.3.0
us-east-1 arn:aws:lambda:us-east-1:410797082306:layer:instana-nodejs:177 3.3.0
us-east-2 arn:aws:lambda:us-east-2:410797082306:layer:instana-nodejs:177 3.3.0
us-west-1 arn:aws:lambda:us-west-1:410797082306:layer:instana-nodejs:177 3.3.0
us-west-2 arn:aws:lambda:us-west-2:410797082306:layer:instana-nodejs:177 3.3.0

Das Muster lautet also arn:aws:lambda:${region}:410797082306:layer:instana-nodejs:${layer-version} (oder arn:aws-cn:lambda:${region}:107998019096:layer:instana-nodejs:${layer-version} für AWS -Regionen in China).

Stellen Sie sicher, dass Sie immer die neuesten Versionen verwenden und die verwendete Ebenenversion in regelmäßigen Intervallen aktualisieren, um von neuen Features und Fixes zu profitieren, die wir bei der Veröffentlichung einer neuen Version der Ebene bereitstellen.

Ab Version 71/1.121.0enthält die Node.js -Schicht die Instana-Erweiterung AWS Lambda. Überwachungsdaten und -traces werden lokal in die Lambda-Erweiterung von Instana ausgelagert, die sie dann an das Instana-Back-End weiterleitet. Dies bietet den folgenden Vorteil: Die Antwort der Lambda-Funktion wird sofort nach Beendigung des Handlers an den aufrufenden Client zurückgesendet, ohne darauf zu warten, dass Daten an das Instana-Back-End gesendet werden. Diese Funktion ist derzeit auf Lambda-Funktionen beschränkt, die mit 256 MB Speicher oder mehr konfiguriert wurden. Die Verwendung der Instana-Lambda-Erweiterung kann inaktiviert werden, indem die Umgebungsvariable INSTANA_DISABLE_LAMBDA_EXTENSION auf eine nicht leere Zeichenfolge für die Lambda-Funktion gesetzt wird.

Architektur arm64

Bereich ARN @instana/aws-lambda-Version
af-south-1 arn:aws:lambda:af-south-1:410797082306:layer:instana-nodejs-arm64:23 3.3.0
ap-east-1 arn:aws:lambda:ap-east-1:410797082306:layer:instana-nodejs-arm64:23 3.3.0
ap-northeast-1 arn:aws:lambda:ap-northeast-1:410797082306:layer:instana-nodejs-arm64:62 3.3.0
ap-northeast-2 arn:aws:lambda:ap-northeast-2:410797082306:layer:instana-nodejs-arm64:62 3.3.0
ap-northeast-3 arn:aws:lambda:ap-northeast-3:410797082306:layer:instana-nodejs-arm64:23 3.3.0
ap-south-1 arn:aws:lambda:ap-south-1:410797082306:layer:instana-nodejs-arm64:62 3.3.0
ap-south-2 arn:aws:lambda:ap-south-2:410797082306:layer:instana-nodejs-arm64:23 3.3.0
ap-southeast-1 arn:aws:lambda:ap-southeast-1:410797082306:layer:instana-nodejs-arm64:62 3.3.0
ap-southeast-2 arn:aws:lambda:ap-southeast-2:410797082306:layer:instana-nodejs-arm64:62 3.3.0
ap-southeast-3 arn:aws:lambda:ap-southeast-3:410797082306:layer:instana-nodejs-arm64:23 3.3.0
ap-southeast-4 arn:aws:lambda:ap-southeast-4:410797082306:layer:instana-nodejs-arm64:23 3.3.0
ca-central-1 arn:aws:lambda:ca-central-1:410797082306:layer:instana-nodejs-arm64:62 3.3.0
cn-north-1 arn:aws-cn:lambda:cn-north-1:107998019096:layer:instana-nodejs-arm64:12 3.3.0
cn-northwest-1 arn:aws-cn:lambda:cn-northwest-1:107998019096:layer:instana-nodejs-arm64:12 3.3.0
eu-central-1 arn:aws:lambda:eu-central-1:410797082306:layer:instana-nodejs-arm64:62 3.3.0
eu-central-2 arn:aws:lambda:eu-central-2:410797082306:layer:instana-nodejs-arm64:23 3.3.0
eu-north-1 arn:aws:lambda:eu-north-1:410797082306:layer:instana-nodejs-arm64:62 3.3.0
eu-south-1 arn:aws:lambda:eu-south-1:410797082306:layer:instana-nodejs-arm64:23 3.3.0
eu-south-2 arn:aws:lambda:eu-south-2:410797082306:layer:instana-nodejs-arm64:23 3.3.0
eu-west-1 arn:aws:lambda:eu-west-1:410797082306:layer:instana-nodejs-arm64:62 3.3.0
eu-west-2 arn:aws:lambda:eu-west-2:410797082306:layer:instana-nodejs-arm64:62 3.3.0
eu-west-3 arn:aws:lambda:eu-west-3:410797082306:layer:instana-nodejs-arm64:62 3.3.0
il-central-1 arn:aws:lambda:il-central-1:410797082306:layer:instana-nodejs-arm64:21 3.3.0
me-central-1 arn:aws:lambda:me-central-1:410797082306:layer:instana-nodejs-arm64:23 3.3.0
me-south-1 arn:aws:lambda:me-south-1:410797082306:layer:instana-nodejs-arm64:23 3.3.0
sa-east-1 arn:aws:lambda:sa-east-1:410797082306:layer:instana-nodejs-arm64:62 3.3.0
us-east-1 arn:aws:lambda:us-east-1:410797082306:layer:instana-nodejs-arm64:62 3.3.0
us-east-2 arn:aws:lambda:us-east-2:410797082306:layer:instana-nodejs-arm64:62 3.3.0
us-west-1 arn:aws:lambda:us-west-1:410797082306:layer:instana-nodejs-arm64:62 3.3.0
us-west-2 arn:aws:lambda:us-west-2:410797082306:layer:instana-nodejs-arm64:62 3.3.0

Instana Lambda-Schicht für containerbasierte Funktionen

Wenn Ihr Team containerbasierte Lambda-Implementierungen verwendet, können Sie unsere Basiscontainer unter icr.io/instana/aws-lambda-nodejs verwenden oder das folgende Snippet in Ihre Dockerfile einschließen und die Buildzeitargumente auf die entsprechenden Versionen setzen.

# 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" ]

Anstelle von icr.io/instana/aws-lambda-nodejs:latestkönnen Sie auch eine bestimmte Version des Instana npm-Moduls @instana/aws-lambda verwenden, die größer-gleich 1.137.2 ist (siehe CHANGELOG). Beispiel:

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

Oder Sie können nur die Hauptversion pinnen, während Sie neuere Minor/Patch-Releases zulassen:

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

Zukünftige Versionen von icr.io/instana/aws-lambda-nodejs werden die Unterstützung für ältere Lambda- Node.js -Laufzeiten löschen. Ab Version icr.io/instana/aws-lambda-nodejs:2.0.0wird beispielsweise die Unterstützung für nodejs8.x gelöscht. Es wird empfohlen, die Hauptversion zu pinnen, wenn ältere Lambda-Laufzeiten verwendet werden.

Instana Lambda Layer & Manuelles Wrapping

Sie können das Instana Lambda-Layer auch wie oben beschrieben zu Ihrer Funktion hinzufügen, ohne instana-aws-lambda-auto-wrap.handler zu verwenden. Dies ist insbesondere der empfohlene Ansatz für AWS Lambdas, die auf der Laufzeit 'Node.js 8.10' basieren. Hier sind die erforderlichen Schritte für diese Konfiguration:

  1. Fügen Sie das Instana Lambda-Layer zu Ihrer Funktion hinzu. Sie finden den ARN der Instana-Lambda-Schicht in der Tabelle über.
  2. Fügen Sie die Umgebungsvariablen INSTANA_ENDPOINT_URL und INSTANA_AGENT_KEY mit den erforderlichen Werten hinzu.
  3. Ändern Sie den Funktionscode entsprechend dem Abschnitt Handler manuell einschließen.

@instana/aws-lambda Manuell Installieren

Anstatt das Instana Lamda-Layer zu verwenden, können Sie das npm-Paket @instana/aws-lambda auch manuell installieren:

  1. Fügen Sie die Abhängigkeit @instana/aws-lambda zu Ihrem Projekt hinzu, indem Sie npm install -S @instana/aws-lambda (oder yarn add @instana/aws-lambda) in Ihrem Projektverzeichnis ausführen. Dadurch wird das Paket zu Ihrem Ordner node_modules hinzugefügt und die Abhängigkeit in der Datei package.json gespeichert.
  2. Fügen Sie die Umgebungsvariablen INSTANA_ENDPOINT_URL und INSTANA_AGENT_KEY mit den erforderlichen Werten hinzu.
  3. Ändern Sie den Funktionscode entsprechend dem Abschnitt Handler manuell einschließen.

Handler manuell einschließen

Wenn Sie den Handler für automatisches Wrapping nicht verwenden wollen oder können, müssen Sie den Code Ihrer Node.js AWS -Lambda-Funktion geringfügig ändern, um die Instana-Traceerstellung dafür zu aktivieren.

Die in diesem Abschnitt beschriebenen Codeänderungen sind nicht erforderlich, wenn Sie die Instana-Lambda-Schicht und den Handler für automatisches Wrapping wie im Abschnitt AutoTrace AWS Lambdasbeschrieben verwenden.

Wenn Sie Ihren Lambda-Handler mit Webpack bündeln, wird dieser Ansatz nicht empfohlen, da das Kernpaket von Instana die Vorverarbeitung mit Webpack nicht unterstützt. Der Ansatz AutoTrace AWS Lambdas ist für Lambdas mit dem Webpack geeignet. Alternativ dazu können Sie manuelles Wrapping verwenden und zumindest das Paket @instana/aws-lambda (oder alle Abhängigkeiten) von der Vorverarbeitung durch Webpack ausschließen. Siehe diesen Abschnitt in der Node.js -Dokumentation. Informationen zum serverlosen Framework finden Sie auch im Abschnitt Serverless Framework.

  1. Fügen Sie die Zeile const instana = require('@instana/aws-lambda'); ganz oben in Ihrer Handler JavaScript -Datei hinzu.
  2. Schließen Sie Ihre Handlerfunktion in den Aufruf instana.wrap() ein.
  3. Konfigurieren Sie die Umgebungsvariablen für die Verbindung zum Instana-Back-End wie in der Dokumentation zu Instana AutoTrace für AWS Lambda beschrieben.

Hier finden Sie einige Vorher-/Nachher-Beispiele für die verschiedenen Handler-Funktionsstile, die für auf Node.js basierende AWS Lambdas verwendet werden können:

Handler für asynchrone Funktionsdarstellung

Wenn Sie eine async-Funktion als Handler verwenden, sollte dies wie folgt aussehen:

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

Der daraus resultierende Code sollte wie folgt aussehen:

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

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

Promise Style Lambda-Handler

Wenn Sie einen Handler im Promise-Stil verwenden, sollte er wie folgt aussehen:

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

Der daraus resultierende Code sollte wie folgt aussehen:

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(

Lambda-Handler im Callback-Stil von

Wenn Sie einen Handler im Callback-Stil verwenden, sollte er wie folgt aussehen:

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

Der daraus resultierende Code sollte wie folgt aussehen:

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

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

-Konfigurationsobjekt

Sie können auch ein optionales configuration -Objekt als erstes Argument übergeben, wenn Sie Ihren Handler einschließen:

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

Konfigurationswerte, die bei der nativen Lambda-Traceerstellung nicht unterstützt werden (wie agentHost, agentPort und reportUnhandledPromiseRejections), werden im Hintergrund ignoriert.

Beachten Sie, dass Sie auch die Umgebungsvariablen verwenden können, die im Abschnitt Weitere Konfigurationsoptionen aufgelistet sind, und die meisten der Umgebungsvariablen, die auf der Node.js -Konfigurationsseiteaufgelistet sind.

Instanzerstellungstracing mit Serverless Framework integrieren

Bearbeiten Sie die Datei serverless.yml , um die Instana-Traceerstellung in Serverless Frameworkzu integrieren. Führen Sie die folgenden Schritte aus:

  1. Kopieren Sie Layer ARN aus der Liste und fügen Sie den ARN zum Abschnitt layers der Zielfunktionsdefinition hinzu.

  2. Fügen Sie die Umgebungsvariablen INSTANA_AGENT_KEY, INSTANA_ENDPOINT_URL und LAMBDA_HANDLERhinzu. Weitere Informationen finden Sie unter Instana AutoTrace setup.

Siehe das folgende Beispiel 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

Serverlos offline

Voraussetzung: Stellen Sie sicher, dass Sie die Schritte 1 und 2 im Abschnitt Instanzerstellungsverfolgung in Serverless Framework integrieren ausgeführt haben.

Bearbeiten Sie die Datei serverless.yml , um Instana mit Serverless Framework und Serverless Offlinezu verbinden. Führen Sie die folgenden Schritte aus:

  1. Setzen Sie die Umgebungsvariable NODE_PATH auf $NODE_PATH:/opt/nodejs/node_modules.
  2. Setzen Sie das Feld useDocker im Abschnitt custom auf true . Anschließend wird die Instanzerschicht automatisch in einen Docker -Container heruntergeladen.

Siehe das folgende Beispiel serverless.yml:

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

Serverloses Webpack

Voraussetzung: Stellen Sie sicher, dass Sie die Schritte 1 und 2 im Abschnitt Instanzerstellungsverfolgung in Serverless Framework integrieren ausgeführt haben.

Bearbeiten Sie die Datei serverless.yml , um Instana mit Serverless Framework und Serverless Webpackzu verbinden.

Fügen Sie entrypoint zur Definition der Lambda-Zielfunktion hinzu. Der Eingangspunkt ist Ihr ursprünglicher Node.js -Lambda-Handler, der automatisch von der Instana-Lambda-Schicht ausgelöst wird. Weitere Informationen finden Sie unter Instana AutoTrace setup.

Siehe das folgende Beispiel serverless.yml:

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

Anmerkungen:

Fire & Forget-Anrufe

Wenn Sie in Ihrer Node.js-Lambda-Funktion Aufrufe im "Fire-and-forget"-Stil verwenden, kann Instana nicht sicherstellen, dass diese zuverlässig erfasst werden. Ein 'Fire-and-forget'-Aufruf ist ein asynchroner Aufruf, bei dem nicht auf das Ergebnis gewartet wird. Hier ein Beispiel:

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()
  };
}

Dieser Lambda-Handler verwendet das Paket node-fetch, um zwei HTTP-Aufrufe vorzunehmen. Der zweite Aufruf wird mit dem Schlüsselwort async aufgerufen, sodass bei der Ausführung auf seine Fertigstellung gewartet wird. Dieser Aufruf wird zuverlässig verfolgt.

Im Gegensatz dazu wartet der Code nicht auf die Ergebnisse des ersten Aufrufs (fetch('https://example.com/fire-and-forget')). Dieser Aufruf wurde möglicherweise beendet, bis die Lambda-Ausführung beendet ist oder nicht. Wenn dieser Aufruf nicht beendet ist, wenn die Ausführung des gesamten Lamba-Prozesses abgeschlossen ist, wird der Aufruf nicht an das Instana-Back-End gemeldet. Wenn Sie einen entsprechenden Trace in der Instana-Benutzerschnittstelle untersuchen, wird möglicherweise eine Warnung angezeigt, die besagt, dass die übergeordnete Spanne für einige der Einträge in diesem Trace während der Verarbeitung fehlt.

In diesem Beispiel wurde der async/await-Stil verwendet, es gibt aber ähnliche Beispiele für Code im Promise- und Callback-Stil.

SSM-Unterstützung

Verfügbar ab Version 99 der Ebene instana-nodejs/@instana/aws-lambda@1.138.0.

Sie können den Instanzagentenschlüssel auch über den Parameterspeicher AWS SSM (System Manager) bereitstellen.

  1. Fügen Sie den Instanzagentenschlüssel zum SSM-Parameterspeicher hinzu. Merken Sie sich den Parameternamen oder kopieren Sie ihn.
  2. Entfernen Sie INSTANA_AGENT_KEY aus Ihren Umgebungsvariablen.
  3. Fügen Sie INSTANA_SSM_PARAM_NAME zu Ihren Umgebungsvariablen mit dem kopierten Parameternamen hinzu.
  4. Wenn Sie den Parameter als "SecureString" hinzugefügt haben, müssen Sie auch INSTANA_SSM_DECRYPTION=truefestlegen. Wenn Sie den Typ "String" verwendet, muss keine weitere Variable festgelegt werden.

Wenn Sie INSTANA_AGENT_KEY nicht aus Ihren Umgebungsvariablen entfernen, werden die SSM-Umgebungsvariablen ignoriert.

Älter Node.js Lambda-Laufzeiten

Zum Zeitpunkt dieser Veröffentlichung stellt Amazon Node.js 14, 12 und 10 als Lambda-Laufzeiten bereit. Instana unterstützt keine älteren Node.js-Lambda-Laufzeiten, die bereits von AWS außer Betrieb genommen wurden (z. B. Knoten 4 und 6). Wenn Sie weiterhin Lambdas implementiert haben, die diese Laufzeiten verwenden, aktualisieren Sie sie auf eine aktuellere Node.js -Lambda-Laufzeit, bevor Sie sie für die native Instana-Traceerstellung konfigurieren. Node.js 8 wird derzeit noch unterstützt, obwohl die Version bereits am Ende des Lebenszyklus ist.

Instana-API in Lambda-Funktionen verwenden

Sie können auf die gesamte Instana-API in Ihrem Lambda-Code zugreifen und sie verwenden, wie in einer einfachen Node.js -App mit @instana/collector.

Wenn Sie die Lambda-Schicht Instana Node.js und den Handler für automatisches Wrappingverwenden, müssen Sie Ihrem Code die folgende Zeile hinzufügen:

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

Wenn Sie manuelles Umbrechenverwenden, ist diese Zeile bereits in Ihrer Lambda-Handlerdatei enthalten.

Wenn Sie die Lambda-Schicht Node.js von Instana verwenden, fügen Sie das Paket @instana/aws-lambda nicht als Abhängigkeit zu Ihrer Datei package.json hinzu. Dieses Paket wird von der Instana-Lambda-Schicht Node.js bereitgestellt. Das Hinzufügen als Abhängigkeit unter Verwendung der Lambda-Schicht wird nicht unterstützt.

Wenn Ihr Lambda-Funktionscode aus mehreren Quellendateien besteht, können Sie auch die Anweisung const instana = require('@instana/aws-lambda'); in anderen Quellcodedateien hinzufügen, um dort auf die Instana-API Node.js zuzugreifen.

Zusätzliche Umgebungsvariablen

Name Standard Wert Beschreibung
INSTANA_DISABLE_LAMBDA_EXTENSION false Jede nicht leere Zeichenfolge. Inaktivieren Sie die Lambda-Erweiterung oder nicht.