Node.js -Kollektor installieren

Instana Host Agent installieren

Sie müssen den Instana-Hostagenten installieren, bevor Sie den Node.js -Collector installieren. Weitere Informationen zur Installation eines Hostagenten finden Sie unter Hostagenten installieren.

Installierte Node.js -Version überprüfen

Stellen Sie sicher, dass der Node.js -Collector die installierte Node.js -Version unterstützt. Informationen zu den unterstützten Node.js -Versionen finden Sie unter Node.js.

Allgemeine Hinweise zur Installation

Lesen Sie die folgenden Hinweise, um potenzielle Probleme bei der Installation und Verwendung des Kollektors Node.js zu vermeiden:

Bundlers (Webpack oder Rollup)

Wenn Sie Ihre Node.js -Serveranwendung mit einem Bundle wie Webpack oder Rollup vorverarbeiten, können Sie eine der folgenden Installationsmethoden verwenden:

• Node.js -Kollektor installieren, ohne Ihre Anwendung zu ändern.
• @instana/collector als normale Abhängigkeit installieren.

Die bevorzugte Installationsmethode ist Node.js -Collector ohne Änderung Ihrer Anwendung installieren.

In beiden Fällen müssen Sie sicherstellen, dass Sie nur Ihren eigenen Code und nicht den Code Ihrer Abhängigkeiten aus dem Ordner node_modules bündeln.

Sie müssen die Abhängigkeiten aus den folgenden Gründen ausschließen:

• Das Modul @instana/collector unterstützt keine Vorverarbeitung mit Webpack. Unter anderem werden dynamische require -Anweisungen, die in Ihrem Code verwendet werden, nicht ordnungsgemäß aufgelöst.
• Zur Instrumentierung von Bibliotheken anderer Anbieterfängt das npm-Paket @instana/collector den require -Prozess von Node.jsab. Wenn diese Bibliotheken jedoch nicht zur Laufzeit geladen werden und stattdessen zur Buildzeit mit Ihrem eigenen Code gebündelt werden, wird kein require -Prozess ausgeführt und die Instrumentierung wird nicht angewendet. Daher funktioniert die Instana-Traceerstellung nicht oder teilweise, d. h., die Traceerstellung funktioniert nur für Node.js -Kernmodule wie http , da diese Module standardmäßig von der Bündelung ausgeschlossen sind.

Daher müssen Sie Ihren Bundler mithilfe des Moduls webpack-node-externals konfigurieren, damit alles in node_modules von allen Codeumsetzungen ausgeschlossen wird:

// your webpack.config.js:

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

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

Wenn Sie Angular CLI verwenden, insbesondere mit Angular Universal oder SSR, müssen Sie "externalDependencies": ["@instana/collector"] (und möglicherweise andere Bibliotheken, die @instana/collector -Instrumente sind) zu Ihrer angular.json -Datei hinzufügen, um sie von der Bündelung auszuschließen.

Transpiler (Babel oder Traceur)

Wenn Sie einen Transpiler (wie Babel, Traceur oder den TypeScript -Compiler tsc) verwenden, können Sie eine der folgenden Installationsmethoden verwenden:

• Node.js -Kollektor installieren, ohne Ihre Anwendung zu ändern.
• @instana/collector als normale Abhängigkeit installieren.

Die bevorzugte Methode ist die Installation des Node.js -Collectors ohne Änderung der Anwendung.

Wenn Sie @instana/collector als normale Abhängigkeit installieren möchten, müssen Sie genau darauf achten, wie import -und require -Anweisungen von Ihrem Transpiler behandelt werden. Wenn Ihr Transpiler ES6 import -Anweisungen verarbeitet, wird der Kollektor durch das Hinzufügen von import instana from '@instana/collector'; am Anfang der Hauptdatei nicht installiert:

import instana from '@instana/collector';

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

import express from 'express';

Die Installation funktioniert nicht, da gemäß der Spezifikation ES6 alle Importe ausgewertet werden, bevor der Hauptteil des Moduls ausgeführt wird. Babel und andere Transpiler erfüllen diese Regel und verschieben alle Importe an den Anfang, wenn sie Quellendateien transpilieren. Alle tatsächlichen Anweisungen werden nach den Importen eingefügt. Daher wird der Import für express im folgenden Beispiel vor dem Aufruf instana(); in Ihrer transpiled-Datei platziert:

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.

...

Der tatsächliche Aufruf der Initialisierungsfunktion von @instana/collector erfolgt nach allen require -Anweisungen in der transpiled-Datei.

Stattdessen können Sie import './instanaInit'; am Anfang Ihrer Hauptdatei und anschließend alle anderen Importe wie folgt einfügen:

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

Die Datei instanaInit.js (oder instanaInit.ts , wenn Sie TypeScriptverwenden) muss die folgende Anweisung enthalten:

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

Wenn Sie diese Anweisung verwenden, wird die Initialisierungsfunktion sofort aufgerufen, wenn der Prozess gestartet wird.

Im Allgemeinen müssen Sie bei Verwendung eines Transpilers die Ausgabedateien des Transpilers überprüfen, wenn Sie @instana/collectorintegrieren.

Kubernetes und Red Hat OpenShift

Wenn Ihre Node.js-Anwendung in einer Kubernetes- und Red Hat OpenShift-Umgebung läuft, können Sie den Instana AutoTrace-Webhook verwenden oder den Node.js Kollektor, um Ihre Anwendung zu überwachen.

Cloud Foundry

Sie können Cloud Foundry -Anwendungen nur überwachen, wenn der Instantagent aktiv in den Diego-Zellen der Cloud Foundry -Basis ausgeführt wird. Ohne den Agenten, der in der zugrunde liegenden Diego-Zelle ausgeführt wird, wird die Überwachung nicht unterstützt.

Weitere Informationen zum Einrichten von Instantagenten und der zugehörigen Cloud Foundry -oder Pivotal Platform-Funktionalität finden Sie in der Cloud Foundry und Pivotal-Plattform -Dokumentation.

Auf Cloud Foundry ist keine Konfiguration auf der Ebene von cf push und beim Anwendungsmanifest erforderlich. Der einzige erforderliche Schritt besteht darin, das Paket @instana/collector zur Cloud Foundry Node.js hinzuzufügen, wie im Abschnitt Node.js -Collector installieren beschrieben.

Apigee Microgateway

Weitere Informationen zur Verwendung des Instana-Pakets Node.js -Collector mit Apigee Microgateway (auch bekannt als edgemicro) finden Sie unter Apigee Microgateway überwachen.

Next.js

Verwenden Sie für Next.js -Anwendungen den Ansatz, der im Abschnitt Node.js -Kollektor ohne Änderung Ihrer Anwendung installieren beschrieben ist.

CommonJS

Wenn die AnwendungCommonJS, Aktivieren Sie den Collector innerhalb der Anwendung, indem Sie ihn als erste Anweisung in Ihrer Anwendung anfordern und initialisieren.

Stellen Sie sicher, dass diese Zeile die erste Anweisung ist. Andernfalls kann der Collector nicht auf bestimmte Informationen zugreifen. Weitere Informationen zum ordnungsgemäßen Hinzufügen dieser Zeile finden Sie unter Falsche Kollektorintegration.

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

Der vorangehende Code initialisiert den Kollektor mit den Standardkonfigurationsoptionen. Sie können auch ein Konfigurationsobjekt übergeben, wenn Sie den Instana Node.js Kollektor initialisieren. Eine Liste der gültigen Konfigurationsoptionen finden Sie unter Node.js Collector Configuration. Weitere Informationen zur Konfiguration der Konnektivität zwischen Ihrer überwachten Anwendung und dem Instana-Agenten finden Sie unter Agentenkommunikation.

ECMAScript

Wenn Ihre Anwendung ECMAScript verwendet und der @instana/collector-Kollektor als Abhängigkeit installiert ist, aktivieren Sie den Kollektor für die Anwendung, indem Sie den Instana Node.js-Kollektor über die Node.js-Kommandozeilenflags laden. Folgen Sie den Anweisungen im Abschnitt ECMAScript.

Installieren des Kollektors als lokale Abhängigkeit

Um den Collector als lokale Abhängigkeit zu installieren, führen Sie die folgenden Schritte aus:

1. Fügen Sie das Paket @instana/collector zu den Abhängigkeiten Ihres Projekts hinzu:

   • Wenn Sie npm verwenden, führen Sie den folgenden Befehl aus:

     npm install --save @instana/collector`
     

   • Wenn Sie yarn verwenden, führen Sie den folgenden Befehl aus:

     yarn add @instana/collector
     

   Fügen Sie die Funktion require('@instana/collector')(); nicht in Ihren Code ein. Keine Ihrer JavaScript oder TypeScript Dateien muss das @instana Paket erwähnen.

2. Aktivieren Sie den Node.js -Collector:

   Um den Collector in Ihrer Node.js-Anwendung zu aktivieren, lesen Sie die Abschnitte CommonJS und ECMAScript.

--import file:///path/to/instana/node_modules/@instana/collector/esm-register.mjs
or
--experimental-loader file:///path/to/instana/node_modules/@instana/collector/esm-loader.mjs

Kollektor global installieren

Führen Sie die folgenden Schritte aus, um den Collector global zu installieren:

1. Installieren Sie das Paket @instana/collector auf dem Zielsystem:

   • Wenn Sie npm verwenden, führen Sie den folgenden Befehl aus:

     npm install -g @instana/collector
     

   • Wenn Sie yarn verwenden, führen Sie den folgenden Befehl aus:

     yarn global add
     

   Wenn Sie den Kollektor in einer containerisierten Anwendung installieren, können Sie die vorherige Anweisung zu Dockerfilehinzufügen.

2. Ermitteln Sie die Position, an der der Befehl npm install -g das Paket installiert. Die Position hängt vom Betriebssystem ab. Weitere Informationen dazu, wo npm installierte Pakete stellt, finden Sie in der Node.js -Dokumentation zu Ordnern.

3. Stellen Sie sicher, dass das Paket @instana/collector mit allen zugehörigen Abhängigkeiten auf dem Zielsystem an einer bekannten Position wie /path/to/instana/node_modules/@instana/collectorverfügbar ist.

4. Aktivieren Sie den Node.js -Collector:

   • CommonJS: Wenn die AnwendungCommonJS, folgen Sie den Schritten in derCommonJS Abschnitt.

   • ECMAScript-Module: Wenn die Anwendung ECMAScript-Module verwendet, befolgen Sie die Schritte im ECMAscript Abschnitt.

Abhängigkeiten ohne optionale Abhängigkeiten installieren

Wenn Sie Ihre Abhängigkeiten mit dem Befehl npm install --no-optional oder yarn --ignore-optional installieren, versucht npm oder yarn nicht, die nativen Add-ons zu installieren.

Um das Problem zu beheben, dass die nativen Add-ons nicht über npm oder yarn installiert werden, entfernen Sie entweder die Flags aus dem Installationsschritt oder fügen Sie die folgenden Installationsschritte hinzu:

• npm install @instana/autoprofile oder yarn add @instana/autoprofile
• npm install event-loop-stats oder yarn add event-loop-stats
• npm install gcstats.js oder yarn add gcstats.js

@instana/autoprofile konnte nicht geladen werden

Der folgende Fehler tritt auf, wenn der Client oder Kunde AutoProfile™aktivieren muss:

Could not load @instana/autoprofile. You will not get profiling information for this Node.js app in Instana, although autoprofiling has been enabled.

Überprüfen Sie zur Behebung des Fehlers, ob Ihre Node.js -Version unterstützt wird und führen Sie den Befehl npm rebuild aus.

Vorkompilierten Build kopieren

Der folgende Fehler tritt normalerweise auf, wenn Node.js Tracer versucht, die vorkompilierten Binärdateien zu entpacken und der Ordner tmp nicht beschreibbar ist (z. B. in Kubernetes -Pods):

Copying the precompiled build for event-loop-stats (linux/x64/musl/ABI 108) failed. [Error: ENOENT: no such file or directory, lstat '/tmp/event-loop-stats'] {
  errno: -2,
  code: 'ENOENT',
  syscall: 'lstat',
  path: '/tmp/event-loop-stats'
}

Um den Fehler beim Kopieren des vorkompilierten Builds zu beheben, überprüfen Sie, ob sich das System im nicht schreibgeschützten Modus befindet.

Beheben des Ecmascript-URL-Schemafehlers unter Windows

Der folgende Fehler tritt häufig auf, wenn Sie den Instana-Collector in einer Windows ECMAScript-Anwendung aktivieren:

Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only file and data URLs are supported by the default ESM loader.

Dieser Fehler tritt auf, wenn Sie in den Loader-Befehlen einen absoluten Pfad angeben. Um dieses Problem zu beheben, stellen Siefile:/// zum Pfad. Weitere Informationen finden Sie im Collector unter Windows aktivieren Abschnitt.

runtime-version-switch module not foundFehlermeldung

Der folgende Fehler wird angezeigt, wenn die AutoTrace Webhook-Instrumentierungsversion veraltet ist, aber der Node.js-Kollektor auf die neueste Version aktualisiert wurde. Dieser Fehler tritt auf, wenn das runtime-version-switch Skript aus dem AutoTrace Webhook entfernt wird.

Error: Cannot find module '/opt/instana/instrumentation/nodejs/runtime-version-switch'
Require stack:
- internal/preload
  at Module._resolveFilename (node:internal/modules/cjs/loader:1144:15)
  at Module._load (node:internal/modules/cjs/loader:985:27)
  at Function.patchedModuleLoad [as _load] (/opt/instana/instrumentation/nodejs/node_modules/@instana/core/src/util/requireHook.js:93:34)

Obwohl Sie den neuesten AutoTrace Webhook verwenden, verweisen die bereits bereitgestellten Kubernetes Artefakte möglicherweise auf ein veraltetes Instrumentierungs-Image.

Zur Lösung des Problemsruntime-version-switch module not found Fehlermeldung, führen Sie die folgenden Schritte aus: 1. Deinstallieren Sie den AutoTrace Webhook. 2. Stellen Sie den AutoTrace Webhook erneut bereit, um die Änderungen zu übernehmen.