Node.js

CommonJS

Po zainstalowaniu modułu gromadzącego dane należy go aktywować z poziomu aplikacji. W tym celu należy ją i zainicjować jako pierwszą instrukcję w aplikacji. Należy zwrócić uwagę, że jest to pierwsza instrukcja , ponieważ w przeciwnym razie kolektor nie będzie mógł uzyskać dostępu do pewnych informacji.

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

Powyższy kod inicjuje kolektor z domyślnymi opcjami konfiguracyjnymi. Można również przekazać obiekt konfiguracyjny podczas inicjowania kolektora Instana Node.js . Lista poprawnych opcji konfiguracji znajduje się na stronie konfiguracji , a w szczególności w sekcji Komunikacja agenta , aby uzyskać szczegółowe informacje na temat konfigurowania połączenia między monitorowaną aplikacją i agentem Instana.

Moduły ECMAScript produktu

Jeśli program @instana/collector jest instalowany jako zależność, należy aktywować kolektor dla aplikacji, ładując kolektor Instana Node.js za pomocą programu Argument --experimental-loaders. Więcej informacji na ten temat zawiera sekcja Moduły ECMAScript.

Śledzenie z wieloma śledzeniem

Nie jest obsługiwane śledzenie pojedynczej aplikacji Node.js za pomocą Instana i programu śledzącego innej firmy, na przykład z New Relic, Dynatrace lub Datadog w tym samym czasie.

Opentelemetry

Używanie zarówno pakietu SDK OpenTelemetry , jak i kolektora Instana w tej samej aplikacji Node.js nie jest obsługiwane. Może to spowodować następujące problemy:

• Brak połączenia na Instana
• Zduplikowane dane na Instanie
• Uszkodzone instrumentacje

Nie zaleca się używania zarówno pakietu OpenTelemetry SDK, jak i kolektora Instana w tej samej aplikacji Node.js . Aby użyć pakietu Opentelemetry SDK, należy zapoznać się z sekcją Integracja z produktemNode.js OpenTelemetry.

Kubernetes & OpenShift

Cloud Foundry

Uwaga: W tej sekcji przyjęto założenie, że agent Instana działa obecnie w komórkach Diego platformy Cloud Foundry . Bez agenta działającego w komórce Diego, monitorowanie aplikacji Cloud Foundry nie jest obsługiwane.

Informacje na temat konfigurowania agentów Instana i powiązanych z nimi funkcji Cloud Foundry lub Pivotal Platform można znaleźć w dokumentacji produktów Cloud Foundry i Pivotal Platform .

W produkcie Cloud Foundrykonfiguracja nie jest wymagana na poziomie produktu cf push i w manifeście aplikacji. Jedynym niezbędnym krokiem jest dodanie pakietu @instana/collector do aplikacji Cloud Foundry Node.js zgodnie z powyższym opisem.

Mikrobrama Apigee

Informacje na temat używania pakietu kolektora Instana Node.js z produktem Apigee Microgateway (zwanym również edgemicro) można znaleźć na stronie Apigee Microgateway .

Next.js

W przypadku aplikacji Next.js zaleca się użycie metody opisanej w sekcji Instalacja bez modyfikowania kodu źródłowego.

Instalacja bez modyfikowania kodu źródłowego

Istnieją sytuacje, w których nie można (lub nie chcesz) modyfikować kodu źródłowego monitorowanej aplikacji. W przypadku tych scenariuszy można zastosować następujące podejście. Jest to również preferowane podejście dla aplikacji zbudowanych z Webpack, Babel lub innego rodzaju bundler lub transpiler. Co więcej, jest to zalecane podejście dla aplikacji Next.js .

Istnieją dwa rodzaje tej metody:

1. Instalowanie produktu @instana/collector jako lokalnej zależności projektu lub
2. instalowanie @instana/collector globalnie w systemie docelowym.

Oba rodzaje są szczegółowo opisane w następujący sposób.

--experimental-loader /path/to/instana/node_modules/@instana/collector/esm-loader.mjs

--experimental-loader /path/to/instana/node_modules/@instana/collector/esm-loader.mjs

Pakunki (Webpack i podobne)

Preferowana metoda instalacji podczas wstępnego przetwarzania aplikacji serwera Node.js z pakunkiem, takim jak pakiet WWW lub kumulowanie, jest opisana w sekcji Instalacja bez modyfikowania kodu źródłowego.

Alternatywnie, jeśli można również zainstalować produkt @instana/collector jako normalną zależność.

W obu przypadkach należy upewnić się, że został utworzony pakunek tylko własnego kodu, a nie kodu zależności z folderu node_modules . Istnieją dwa powody takiej sytuacji:

• Moduł @instana/collector nie obsługuje wstępnego przetwarzania z użyciem pakietu Webpack. Między innymi dynamiczne instrukcje require używane w naszym kodzie nie zostaną poprawnie rozwiązane.
• Aby instrumentować biblioteki innych firm, pakiet npm @instana/collector przechwytuje proces require środowiska Node.js. Jeśli jednak te biblioteki nie są ładowane w czasie wykonywania, a zamiast tego są spakowane z własnym kodem w czasie budowania, nie jest wykonywany żaden proces require , a instrumentacja nie jest stosowana. Śledzenie Instana nie działa lub działa częściowo w takiej konfiguracji. (Dokładne śledzenie działa tylko dla podstawowych modułów Node.js , takich jak http , ponieważ te moduły są domyślnie wykluczone z tworzenia pakunków).

Dlatego zaleca się skonfigurowanie pakunku w taki sposób, aby wszystkie elementy w produkcie node_modules były wykluczone ze wszystkich transformacji kodu.

Moduł webpack-node-externals umożliwia:

// your webpack.config.js:

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

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

W przypadku korzystania z interfejsu CLI Angular, w szczególności z Angular Universal/SSR, należy dodać do pliku angular.json bibliotekę "externalDependencies": ["@instana/collector"] (i ewentualnie inne biblioteki, które są używane przez instrumenty @instana/collector ), aby wykluczyć ją z tworzenia pakunków (patrz tutaj).

Transpilery (Babel itp.)

Preferowana metoda instalacji w przypadku korzystania z transponera (takiego jak Babel, Traceur lub kompilator TypeScript tsc) jest opisana w sekcji Instalacja bez modyfikowania kodu źródłowego.

Alternatywnie można zainstalować produkt @instana/collector jako normalną zależność, ale nie jest to zalecane. Wymaga to zwrócenia szczególnej uwagi na sposób, w jaki instrukcje import i require są traktowane przez transponler. Jest to szczególnie istotne, jeśli transponler przetwarza instrukcje ES6 import . Po prostu umieszczenie czegoś takiego na początku pliku głównego nie będzie działać w takiej konfiguracji:

import instana from '@instana/collector';

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

import express from 'express';

Dlaczego jest to niemożliwe? Zgodnie ze specyfikacją ES6 wszystkie importy są wartościowane przed wykonaniem treści modułu. Program Babel i inne transponlery są zgodne z tą regułą i podczas transponowania plików źródłowych wszystkie importy są przenoszone na początek. Wszystkie faktyczne stany zostaną umieszczone po imporcie. W związku z tym import dla express w tym przykładzie zostanie umieszczony przed wywołaniem instana(); . Skończysz z czymś takim w transponowanym pliku:

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.

...

Jak widać, rzeczywiste wywołanie funkcji init kolektora @instana/collector jest wykonywane po tym, jak wszystkie instrukcje będą wymagane w transponowanym pliku.

Zamiast tego można zrobić coś takiego:

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

Plik instanaInit.js (lub instanaInit.ts , jeśli używany jest skrypt TypeScript) powinien zawierać tylko jedną instrukcję:

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

W ten sposób funkcja init jest wywoływana natychmiast po uruchomieniu procesu.

Ogólnie rzecz biorąc, w przypadku korzystania z dowolnego transponera dobrym pomysłem jest sprawdzenie plików wyjściowych transponera podczas integrowania produktu @instana/collector.

Niektóre informacje nie są dostępne dla programów Node.js bez pomocy rodzimych dodatków. W szczególności kolektor Instana Node.js używa następujących dodatków:

• Pobieranie informacji o czyszczeniu pamięci
• Pobieranie informacji o działaniu pętli zdarzeń
• Dla profilowania

Wszystkie dodatki rodzime są zależnościami opcjonalnymi. Kolektor będzie działał poprawnie bez tych rodzimych dodatków, ale funkcje wymienione powyżej zostaną wyłączone. Jeśli brakuje którejkolwiek z tych zależności, podczas uruchamiania w dzienniku aplikacji zostanie zapisany komunikat dziennika, który ma następującą postać:

Could not load @instana/autoprofile. You will not get profiling information for this Node.js app in Instana, although
autoprofiling has been enabled. This typically occurs when native add-ons could not be built during module installation
(npm install/yarn) or when npm install --no-optional or yarn --ignore-optional have been used to install dependencies.
See the instructions to learn more about the requirements of the collector:
https://www.ibm.com/docs/de/obi/current?topic=nodejs-collector-installation#native-add-ons

Uwaga: Ten komunikat można zignorować, jeśli dodatkowe wielkości mierzone czyszczenia pamięci i pętli zdarzeń nie są odpowiednie dla użytkownika i jeśli nie jest planowane użycie funkcji Instana AutoProfile w środowisku Node.js.

Istnieją dwie możliwe przyczyny braku rodzimych dodatków:

• Instalowanie zależności z systemem npm install --no-optional lub yarn --ignore-optional. Jeśli ta opcja jest obecna, npm/yarn nie podejmie nawet próby zainstalowania tych zależności. Aby to naprawić, należy usunąć opcję --no-optional/--ignore-optional z kroku instalacji lub dodać jawne kroki instalacji dla omawianych zależności po kroku npm install --no-optional/yarn --ignore-optional :
  • npm install @instana/autoprofile / yarn add @instana/autoprofile
  • npm install event-loop-stats / yarn add event-loop-stats
  • npm install gcstats.js / yarn add gcstats.js
• Kompilacja programu dodatkowego nie powiodła się w kroku npm install/yarn . W pozostałej części tej sekcji wyjaśniono, dlaczego taka sytuacja może wystąpić i w jaki sposób można ją naprawić.

Rodzime dodatki są kompilowane automatycznie dla systemu i wersji Node.js po zainstalowaniu zależności kolektora Node.js na Instana (w ramach kroku npm install lub yarn ). Aby kompilacja działała, w systemie muszą być zainstalowane narzędzia, takie jak make, g++ i python . Narzędzia te mogą być często instalowane przy użyciu pakunku o nazwie build-essential lub podobnego (w zależności od menedżera pakietów i rejestru systemu operacyjnego). W poniższych przykładach przedstawiono sposób wykonania tej czynności dla popularnych dystrybucji systemu Linux :

# for Debian-based distributions (including Ubuntu)
apt-get install build-essential
# or, for Fedora-based distributions (CentOS, Red Hat, etc.)
yum groupinstall "Development Tools"
# or, for Alpine Linux
apk add build-base python

Ważne: Zależności muszą zostać zainstalowane na komputerze, na którym będzie uruchamiana aplikacja. W przeciwnym razie dodatki rodzime mogą być niezgodne z architekturą systemu komputera docelowego lub używaną wersją Node.js . Dlatego złą praktyką jest instalowanie zależności przez uruchomienie komendy npm install/yarn na serwerze budowania, a następnie skopiowanie aplikacji (wraz z zależnościami) na komputer docelowy.

Jeśli aplikacja Node.js jest uruchamiana w kontenerze, ten aspekt zasługuje na szczególną uwagę. Można sprawdzić dane wyjściowe budowania Docker dla błędów systemu node-gyp (patrz gyp ERR! i node-pre-gyp ERR!). Jeśli są one obecne, należy je sprawdzić i ocenić. Niektóre z nich można bezpiecznie zignorować. Na przykład niektóre pakiety mogą próbować pobrać prekompilowane pliki binarne. Jeśli to się nie powiedzie, zostaną one ponownie skompilowane za pośrednictwem komendy node-gyp , co oznacza, że błąd pobierania można zignorować, jeśli krok kompilacji zadziałał. Inne pakiety emitują wiele notatek i ostrzeżeń podczas kompilacji, które również mogą być ignorowane.

Jeśli instalacja opcjonalnej zależności kończy się łańcuchem gyp ERR! not ok, warto ją sprawdzić. Chociaż Instana nie może niestety zapewnić wsparcia dla naprawy konkretnego systemu Dockerfile, udostępniamy kilka przykładowych plików Dockerfile.

Jeśli rodzime zależności programów dodatkowych, takie jak gcstats.js i event-loop-stats , nie zostały pomyślnie zainstalowane podczas działania programu npm install, pakiet @instana/collector automatycznie podejmie próbę użycia wstępnie zbudowanych plików binarnych, które są zgodne z systemem operacyjnym, wersją Node.js i wariantem libc . Ta funkcja jest dostępna tylko w systemie x64 Linux. Można ją wyłączyć, ustawiając właściwość INSTANA_COPY_PRECOMPILED_NATIVE_ADDONS=false.

if (process.env.NODE_ENV !== 'development') {
  require('@instana/collector')();
}

export NODE_ENV=development
# -or-
NODE_ENV=development node myApp.js