Node.js Toplayıcısı Kuruluşu

CommonJS

Toplayıcı artık kurulduğundan, uygulamanın içinden etkinleştirilmesi gerekir. Bunu, komutunu zorunlu tutarak ve uygulamanızdaki ilk deyim olarak kullanıma hazırlayarak yapın. Toplayıcı belirli bilgilere erişemeyecek olduğundan, bunun ilk deyim olduğunu lütfen dikkat edin.

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

Yukarıda gösterilen kod, toplayıcıyı varsayılan yapılandırma seçenekleriyle başlatır. You can also pass in a configuration object when initializing the Instana Node.js collector. Geçerli yapılandırma seçeneklerinin bir listesi için yapılandırma sayfasına ve özellikle izlenen uygulamanız ile Yönortamın aracısı arasında bağlanırlığı yapılandırmaya ilişkin ayrıntılar için aracı iletişimi bölümüne bakın.

ECMAScript modülleri

When @instana/collector is installed as a dependency, you need to activate the collector for the application by loading the Instana Node.js collector through the --experimental-loaders bağımsız değişkeni. Daha fazla bilgi için bkz. ECMAScript Modülleri.

Birden çok izleyiciyle izleme

Instana ve üçüncü taraf izleyici (örneğin, New Relic, Dynatrace ya da Datadog) içeren tek bir Node.js uygulamasının izlenmesi desteklenmez.

Opentelemetry

Aynı Node.js uygulamasında hem OpenTelemetry SDK hem de YönOrtamı-toplayıcı kullanılması desteklenmez. Aşağıdaki sorunlara neden olabilir:

• Instana 'da arama eksik
• Instana 'da yinelenen veriler
• Bozuk özel işlemden geçirmeler

Aynı Node.js uygulamasında hem OpenTelemetry SDK ' yı, hem de YönOrtamıcı toplayıcısını kullanmanız önerilmez. Opentelemetry SDK ' yı kullanmak istiyorsanız, bkz. Node.js OpenTelemetry bütünleştirmesi.

Kubernetes & OpenShift

Cloud Foundry

Not: Bu bölümde, YönOrtamıAna aracısının Cloud Foundry temelinin Diego hücrelerinde çalışmakta olduğu varsayılır. Diego hücresinde çalışan bir aracı olmadan, Cloud Foundry uygulamalarının izlenmesi desteklenmez.

Instana aracılarının ve ilgili Cloud Foundry ya da Pivotal Platform işlevselliğinin nasıl ayarlanacağına ilişkin bilgi için Cloud Foundry ve Pivotal Platform belgelerimize bakın.

Cloud Foundry' de cf push düzeyinde ve uygulama bildirgesi düzeyinde bir yapılandırma gerekli değildir. Gerekli tek adım, @instana/collector paketini yukarıda açıklandığı gibi Cloud Foundry Node.js uygulamasına eklemektir.

Apigee Microgateway (Apigee Microgateway)

Please refer to the Apigee Microgateway sayfası for information on how to use the Instana Node.js collector package with Apigee Mikroağ Geçidi (also known as edgemicro).

Next.js

Next.js uygulamaları için, Kaynak Kodu Değiştirmeden Kuruluşbaşlıklı konuda açıklanan yaklaşımı kullanmanızı öneririz.

Kaynak Kodunu Değiştirmeden Kuruluş

İzlenen uygulamanın kaynak kodunu değiştiremeyeceğiniz (ya da değiştirmek istemediğiniz) durumlar vardır. Bu senaryolar için aşağıdaki yaklaşım kullanılabilir. Bu, Webpack, Babel veya başka bir paketleyici veya nakil makinesi ile oluşturulan uygulamalar için de tercih edilen bir yaklaşımdır. Son olarak, Next.js uygulamaları için önerilen yaklaşım budur.

Bu yöntemin iki çeşnisi vardır:

1. @instana/collector ' i projenizin yerel bağımlılığı olarak kurma ya da
2. Hedef sisteme @instana/collector genel olarak kurma.

Her iki lezzet de aşağıdaki gibi ayrıntılı olarak açıklanır.

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

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

Bundlers (Web Paketi ve Benzer)

Node.js sunucu uygulamanızı Webpack ya da Rollup gibi bir paketleyici ile önceden işlediğinizde tercih edilen kuruluş yöntemi, Kaynak Kodu Değiştirmeden Kuruluşbaşlıklı konuda açıklanmaktadır.

Diğer bir seçenek olarak, @instana/collector ' yi normal bir bağımlılık olarak da kurabilirsiniz.

Her iki durumda da node_modules klasöründeki bağımlılıklarınızın kodunu değil, yalnızca kendi kodunuzu paketlemeniz gerekir. Bunun iki nedeni vardır:

• @instana/collector modülü, Webpack ile önceden işlenmesini desteklemiyor. Diğer sorunların yanı sıra, kodumuzda kullanılan dinamik zorunlu deyimler doğru şekilde çözümlenmeyecektir.
• Üçüncü kişi kitaplıklarınıizleme kodu eklemek için, npm paketi @instana/collector , Node.js' nin require sürecini durdurur. Ancak, bu kitaplıklar çalıştırma zamanında yüklenmezse ve bunun yerine oluşturma sırasında kendi kodunuzla birlikte paketlenirse, require işlemi yürütülmez ve özel işlemden geçirme uygulanmaz. Instana izleme çalışmıyor ya da kısmen böyle bir düzende çalışıyor. (Kesin olarak, izleme yalnızca http gibi Node.js çekirdek modüllerinde çalışır; çünkü bu modüller varsayılan olarak paketleme dışında bırakılır.)

Bu nedenle, node_modules içindeki her şeyin tüm kod dönüşümlerinin dışında bırakılacağı şekilde paketleyicinizi yapılandırmanızı şiddetle öneririz.

Aşağıdakileri gerçekleştirmek için webpack-node-externals modülünü kullanabilirsiniz:

// your webpack.config.js:

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

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

Açısal CLI kullanıyorsanız, özellikle Angular Universal/SSRile, bunları paketleme dışında bırakmak için angular.json dosyanıza "externalDependencies": ["@instana/collector"] (ve muhtemelen @instana/collector aygıtlarını içeren diğer kitaplıklar) eklemelisiniz (bkz. buraya).

Nakil işlemleri (Babel vb.)

Taşıyıcı kullanırken tercih edilen kuruluş yöntemi (Babel, Traceur ya da TypeScript derleyicisi tscgibi) Kaynak Kodu Değiştirmeden Kuruluşbaşlıklı konuda açıklanmaktadır.

Alternatif olarak, @instana/collector ürününü normal bir bağımlılık olarak kurabilirsiniz, ancak bu yaklaşımı önermiyoruz. Bu, import ve require deyimlerinin nakil yapanınız tarafından nasıl ele alındığına dikkat etmenizi gerektirir. Bu, nakil işlemciniz ES6 import deyimlerini işlerse özellikle içe aktarır. Ana dosyanızın üst kısmına bunun gibi bir şey koymak işe yaramayacaktır :

import instana from '@instana/collector';

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

import express from 'express';

-Neden olmasın? ES6 belirtimine göre, modülün gövdesi yürütülmeden önce tüm içe aktarmalar değerlendirilir. Babel ve diğer nakiller bu kurala uygun hareket eder ve kaynak dosyaları naklederken tüm içe aktarmaları en üste taşır. Tüm gerçek stamerler ithalattan sonra konacak. Sonuç olarak, bu örnekteki express için içe aktarma, instana(); çağrıdan önce yerleştirilir. Nakledilen dosyanda buna benzer bir şey bulacaksın:

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.

...

Gördüğünüz gibi, @instana/collector init işlevine yapılan gerçek çağrı, nakledilen dosyadaki tüm zorunlu deyimlerin ardından gelir.

Bunun yerine, şöyle bir şey yapabilirsiniz:

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

instanaInit.js dosyası (ya da TypeScriptkullanıyorsanız instanaInit.ts ) şu bir deyime sahip olmalıdır:

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

Bu şekilde, init işlevi işlem başladığında hemen çağrılır.

Genel olarak, herhangi bir nakil aracı kullanırken, @instana/collectorbütünleştirirken nakil yapanın çıkış dosyalarını incelemek iyi bir fikirdir.

Bazı bilgiler, yerel eklentilerin yardımı olmadan Node.js programlarının kullanımına sunulmaz. Specifically, the Instana Node.js collector uses these add-ons:

• Atık toplama hakkında bilgi almak için
• Olay döngüsü etkinliğine ilişkin bilgileri almak için
• Profil Oluşturma için

Tüm yerli eklentiler isteğe bağlı bağımlılıklardır. Toplayıcı bu yerli eklentiler olmadan düzgün çalışacaktır, ancak yukarıda belirtilen özellikler devre dışı bırakılacaktır. Bu bağımlılıklardan herhangi biri eksikse, başlatma sırasında uygulama günlüğüne şöyle bir günlük iletisi yazılır:

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

Not: Ek atık toplama ve olay döngüsü metrikleri sizin için uygun değilse ve Node.jsüzerinde AutoProfile özelliğini kullanmayı planlamıyorsanız, bu iletiyi güvenle yoksayabilirsiniz.

Yerli eklentilerin eksik olmasının iki nedeni olabilir:

• npm install --no-optional ya da yarn --ignore-optionalile bağımlılıklar kuruluyor. Bu işaret varsa, npm/yarn bu bağımlılıkları kurma girişiminde bulunmaz. Bunu düzeltmek için, kuruluş adımından --no-optional/--ignore-optional işaretini kaldırın ya da npm install --no-optional/yarn --ignore-optional adımından sonra söz konusu bağımlılıklar için belirtik kuruluş adımları ekleyin:
  • 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
• npm install/yarn adımı sırasında eklenti derlemesi başarısız oldu. Bu bölümün geri kalanında bunun neden olabileceği ve nasıl düzeltileceği açıklanır.

Instana Node.js toplayıcı bağımlılığı ( npm install ya da yarn adımının bir parçası olarak) kurulduğunda, sisteminiz ve Node.js sürümü için yerli eklentiler otomatik olarak derlenir. Derlemenin çalışması için sistemin make, g++ ve python gibi araçlarının kurulu olması gerekir. Bu araçlar genellikle build-essential adlı ya da benzeri bir paket kullanılarak kurulabilir (işletim sisteminizin paket yöneticisine ve kaydına bağlı olarak). Aşağıdaki örneklerde, sık kullanılan Linux dağıtımları için bunun nasıl gerçekleştirileceği gösterilmektedir:

# 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

Önemli: Uygulamayı çalıştıracak makinede bağımlılıkların kurulması gerekir. Tersi durumda, yerli eklentiler hedef makinenin sistem mimarisiyle ya da kullanılmakta olan Node.js sürümüyle uyumsuz olabilir. Bu nedenle, npm install/yarn komutunu bir oluşturma sunucusunda çalıştırarak bağımlılıkları kurmak ve uygulamayı (bağımlılıklar dahil) hedef makineye kopyalamak hatalı bir uygulamadır .

Node.js uygulamanızı bir taşıyıcıda çalıştırırsanız, bu özellik daha fazla dikkat edilmeyi hak eder. Docker oluşturmanızdaki node-gyp hatalarını denetlemek isteyebilirsiniz ( gyp ERR! ve node-pre-gyp ERR!öğelerini arayın). Bunlar varsa, bunları inceleyip değerlendirmelisiniz. Bazıları güvenle yoksayılabilir. Örneğin, bazı paketler ön derlenmiş ikili dosyaları karşıdan yüklemeye çalışabilir; bu başarısız olursa, node-gyp aracılığıyla derlemeye geri dönerler; yani, derleme adımı çalışırsa, karşıdan yükleme hatası yoksayılabilir. Diğer paketler derleme sırasında birçok not ve uyarı yayar; bu da yoksayılabilir.

İsteğe bağlı bir bağımlılığın kuruluşu gyp ERR! not okile biterse, bu bağımlılığa bakmak isteyebilirsiniz. Instana, Dockerfileürününüzü düzeltmek için ne yazık ki destek sağlayamıyor olsa da, bazı örnek Dockerfilessağlıyoruz.

npm installçalıştırılırken gcstats.js ve event-loop-stats gibi yerel eklenti bağımlılıkları başarıyla kurulmadıysa, @instana/collector paketi otomatik olarak işletim sistemiyle ( Node.js sürümü ve libc çeşitlemesi) eşleşen önceden oluşturulmuş ikili dosyaları kullanmayı dener. Bu özellik yalnızca x64 Linuxüzerinde kullanılabilir. INSTANA_COPY_PRECOMPILED_NATIVE_ADDONS=falseayarlanarak devre dışı bırakılabilir.

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

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