Installer manuellement la sonde Node.js - Cloud Monitor - Centre de documentation Alibaba Cloud

Prérequis

Votre environnement de build peut se connecter à Internet public ou au réseau interne d'Alibaba Cloud, et son groupe de sécurité autorise le trafic TCP sortant sur les ports 80 et 443.
Votre version de Node.js est la 14.x ou une version ultérieure.
Votre projet utilise npm, yarn ou pnpm comme gestionnaire de paquets.

Notes d'utilisation

Si votre application utilise un framework pris en charge tel qu'Express, Koa ou Fastify, la sonde effectue automatiquement une instrumentation non intrusive.
Pour les applications dotées de scripts de démarrage personnalisés, assurez-vous que la sonde se charge avant le démarrage de l'application.
Si votre application utilise le mode cluster, veillez à ce que la sonde soit chargée dans chaque processus worker.

Étape 1 : Installer le SDK de la sonde

Choisissez une méthode d'installation :

Installez depuis le dépôt npm : npm install @loongsuite/cms_node_sdk.
Installez avec yarn : yarn add @loongsuite/cms_node_sdk.
Installez avec pnpm : pnpm add @loongsuite/cms_node_sdk.

Étape 2 : Configurer les variables d'environnement

Ajoutez les variables d'environnement suivantes à votre application Node.js :

# Method 1: Add environment variables for all processes in the current shell
export ARMS_APP_NAME=your-app-name   # Your application name.
export ARMS_REGION_ID=your-region-id   # The region ID for your Alibaba Cloud account.
export ARMS_LICENSE_KEY=your-license-key   # Your Alibaba Cloud license key.

# Method 2: Add environment variables for a specific process
ARMS_APP_NAME=your-app-name ARMS_REGION_ID=your-region-id ARMS_LICENSE_KEY=your-license-key node -r @loongsuite/cms_node_sdk/register app.js

Vous pouvez obtenir la clé de licence via OpenAPI ou depuis le Integration Center dans la console CMS 2.0.

Installation dans un environnement Docker (facultatif)

Pour les environnements Docker, modifiez votre Dockerfile comme indiqué dans l'exemple suivant.

# Add environment variables
ENV ARMS_APP_NAME={AppName}
ENV ARMS_REGION_ID={regionId}
ENV ARMS_LICENSE_KEY={licenseKey}

## Your existing environment

Étape 3 : Initialiser la sonde

Le SDK Node.js prend en charge deux modes d'initialisation. Choisissez-en un en fonction de vos besoins :

Approche programmatique

Initialisez le SDK dans le fichier point d'entrée de votre application avec les paramètres suivants :

serviceName : nom de votre application (obligatoire).
licenseKey : clé de licence Alibaba Cloud (obligatoire).
regionId : ID de région Alibaba Cloud (obligatoire), par exemple cn-hangzhou ou cn-shanghai.

Approche CommonJS :

// Must be the first line of app.js or index.js
const { NodeSDK } = require('@loongsuite/cms_node_sdk');

// Initialize the SDK (licenseKey, serviceName, and regionId are required)
const sdk = new NodeSDK({
  serviceName: 'your-app-name',        // Application name
  licenseKey: 'your-license-key',      // Get this from the ARMS console
  regionId: 'cn-hangzhou',             // Your Alibaba Cloud region
  // workspace: 'your-workspace',      // Optional: workspace
});

// Start the SDK
sdk.start();

// Your application code starts here
const express = require('express');
const app = express();
// ... other code

Approche ES Module :

// Must be the first line of app.mjs or index.mjs
import { NodeSDK } from '@loongsuite/cms_node_sdk';

// Initialize the SDK (licenseKey, serviceName, and regionId are required)
const sdk = new NodeSDK({
  serviceName: 'your-app-name',        // Application name
  licenseKey: 'your-license-key',      // Get this from the ARMS console
  regionId: 'cn-hangzhou',             // Your Alibaba Cloud region
  // workspace: 'your-workspace',      // Optional: workspace
});

// Start the SDK
sdk.start();

// Your application code starts here
import express from 'express';
const app = express();
// ... other code

Important :

Les paramètres serviceName, licenseKey et regionId sont obligatoires.
Vous devez appeler sdk.start() avant d'importer tout autre module d'application (tel qu'express ou mysql) afin de garantir le bon fonctionnement de l'instrumentation automatique.

Injection automatique

Pour une instrumentation sans code, configurez le SDK avec des variables d'environnement et préchargez-le au démarrage à l'aide de l'indicateur -r.

Ce mode utilise les variables d'environnement configurées à l'étape 2, donc aucune modification du code n'est requise.

Étape 4 : Démarrer l'application

Démarrer l'application en mode programmatique

Si vous utilisez l'approche programmatique (mode 1), démarrez votre application avec la commande standard :

node app.js

Démarrer l'application à l'aide de l'injection automatique (mode register)

Si vous utilisez l'injection automatique (mode 2 à l'étape 3), préchargez la sonde avec l'indicateur Node.js -r :

node -r @loongsuite/cms_node_sdk/register app.js

L'indicateur -r initialise la sonde Node.js ARMS et active l'instrumentation non intrusive.

Démarrer l'application avec un chargeur ESM (projets ESM)

Si votre projet utilise des modules ES, utilisez le chargeur Node.js pour injecter automatiquement le SDK lors du chargement des modules :

node --experimental-loader=@loongsuite/cms_node_sdk/import-hooks app.mjs

Cette méthode convient aux projets purement ESM et nécessite l'indicateur --experimental-loader dans la commande de démarrage.

Vérifier l'installation

Environ une minute après l'installation, vérifiez si votre application apparaît dans la console ARMS sous Application Monitoring > Application List. L'application est correctement connectée lorsqu'elle apparaît dans la liste et rapporte des données.

Configuration avancée

Configuration personnalisée

Vous pouvez personnaliser le comportement de la sonde par programmation :

const { NodeSDK } = require('@loongsuite/cms_node_sdk');

const sdk = new NodeSDK({
  serviceName: 'my-custom-service',
  licenseKey: 'your-license-key',
  regionId: 'cn-hangzhou',
  workspace: 'your-workspace',
  // Other custom configurations, such as sampling policies or custom exporters
});

sdk.start();

Configurer avec des variables d'environnement (mode register)

Lors de l'utilisation du mode register, les variables d'environnement suivantes sont prises en charge :

Paramètre

Description

Obligatoire

ARMS_APP_NAME

Nom de l'application

Oui

ARMS_LICENSE_KEY

Clé de licence ARMS

Oui

ARMS_REGION_ID

ID de région ARMS (par exemple, cn-hangzhou)

Oui

ARMS_WORKSPACE

Espace de travail ARMS

Non

CMS_ENABLE_CONSOLE_EXPORTER

Active l'exportateur de console. Valeurs valides : true, false.

Non

CMS_OTLP_ENDPOINT

URL du point de terminaison d'export OTLP.

Non

OTEL_LOG_LEVEL

Définit le niveau de journalisation de la sonde. Valeurs valides : debug, info, warn, error.

Non. Par défaut : info.

FAQ

La sonde affecte-t-elle les performances de l'application ?

La sonde est conçue pour engendrer une surcharge minimale, généralement inférieure à 5 %.

Quels frameworks Node.js sont pris en charge ?

La sonde prend en charge les principaux frameworks web Node.js, notamment Express, Koa, Fastify, Hapi et Restify, ainsi que les clients de base de données pour MySQL, PostgreSQL, Redis et MongoDB.

Le SDK doit-il être importé en premier ?

Oui. Vous devez appeler sdk.start() ou utiliser l'indicateur de préchargement -r avant d'importer tout autre module d'application (tel qu'express ou mysql). Sinon, l'instrumentation automatique échouera pour ces modules.

Comment désactiver la sonde ?

Appelez la méthode sdk.shutdown() pour arrêter gracieusement la sonde. En mode register, la sonde s'arrête automatiquement lorsque le processus se termine.

TypeScript est-il pris en charge ?

Oui. Le SDK est écrit en TypeScript et inclut des définitions de type complètes.

Puis-je figer la version de la sonde ?

Oui. Installez une version spécifique en exécutant la commande suivante :

npm install @loongsuite/cms_node_sdk@<version>

Remplacez <version> par le numéro de version réel.