Node.js プローブの手動インストール - Cloud Monitor - Alibaba Cloud ドキュメントセンター

Node.js プローブをインストールすると、ARMS がアプリケーションの監視を開始します。アプリケーショントポロジー、トレース、SQL 分析などの主要なデータを確認できます。このトピックでは、Node.js アプリケーション向けに Node.js プローブを手動でインストールする方法について説明します。

前提条件

ビルド環境がパブリックインターネットまたは Alibaba Cloud 内部ネットワークに接続できる必要があります。セキュリティグループでは、ポート 80 および 443 でのアウトバウンド TCP トラフィックが許可されている必要があります。
Node.js のバージョンを確認してください。Node.js 14.x 以降の使用を推奨します。
プロジェクトで npm、yarn、pnpm などのパッケージ管理ツールを使用していることを確認してください。

注意事項

アプリケーションが Express、Koa、Fastify などのサポート対象フレームワークを使用している場合、プローブは自動的に検出し、非侵入型インスツルメンテーションを実行します。
カスタム起動スクリプトを使用するアプリケーションの場合、アプリケーションの起動前にプローブが正しく読み込まれることを確認してください。
アプリケーションがクラスターモードを使用している場合、各ワーカープロセスでプローブが正しく読み込まれることを確認してください。

ステップ 1：プローブ SDK のインストール

次のいずれかのインストール方法を選択してください。

npm リポジトリからインストール： npm install @loongsuite/cms_node_sdk
yarn を使用してインストール： yarn add @loongsuite/cms_node_sdk
pnpm を使用してインストール： pnpm add @loongsuite/cms_node_sdk

ステップ 2：環境変数の設定

Node.js アプリケーションに次の環境変数を手動で追加してください。

# 方法 1：現在のシェルのすべてのプロセスに環境変数を追加
export ARMS_APP_NAME=your-app-name   # アプリケーション名
export ARMS_REGION_ID=your-region-id   # Alibaba Cloud アカウントのリージョン ID
export ARMS_LICENSE_KEY=your-license-key   # Alibaba Cloud ライセンスキー

# 方法 2：特定のプロセスに環境変数を追加
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

ライセンスキーは、OpenAPI または CMS 2.0 コンソールのインテグレーションセンターから取得できます。

Docker 環境へのインストール (オプション)

Docker 環境の場合、次の例に基づいて Dockerfile を変更してください。

# 環境変数を追加
ENV ARMS_APP_NAME={AppName}
ENV ARMS_REGION_ID={regionId}
ENV ARMS_LICENSE_KEY={licenseKey}

## 既存の環境設定

ステップ 3：プローブの初期化

Node.js SDK は 2 つのモードをサポートしています。要件に応じていずれかを選択してください。

プログラマティックアプローチ

コード内で直接 SDK を初期化します。アプリケーションのエントリポイントファイルに次の情報を指定する必要があります。

serviceName：アプリケーション名 (必須)
licenseKey：Alibaba Cloud ライセンスキー (必須)
regionId：Alibaba Cloud リージョン ID (必須)、例： cn-hangzhou または cn-shanghai

CommonJS アプローチ：

// app.js または index.js の最初の行に記述する必要があります
const { NodeSDK } = require('@loongsuite/cms_node_sdk');

// SDK を初期化 (licenseKey、serviceName、regionId は必須)
const sdk = new NodeSDK({
  serviceName: 'your-app-name',        // アプリケーション名
  licenseKey: 'your-license-key',      // ARMS コンソールから取得
  regionId: 'cn-hangzhou',             // Alibaba Cloud リージョン
  // workspace: 'your-workspace',      // オプション：ワークスペース
});

// SDK を起動
sdk.start();

// アプリケーションコードはここから開始
const express = require('express');
const app = express();
// ... その他のコード

ES Module アプローチ：

// app.mjs または index.mjs の最初の行に記述する必要があります
import { NodeSDK } from '@loongsuite/cms_node_sdk';

// SDK を初期化 (licenseKey、serviceName、regionId は必須)
const sdk = new NodeSDK({
  serviceName: 'your-app-name',        // アプリケーション名
  licenseKey: 'your-license-key',      // ARMS コンソールから取得
  regionId: 'cn-hangzhou',             // Alibaba Cloud リージョン
  // workspace: 'your-workspace',      // オプション：ワークスペース
});

// SDK を起動
sdk.start();

// アプリケーションコードはここから開始
import express from 'express';
const app = express();
// ... その他のコード

重要：

serviceName、licenseKey、regionId パラメータは必須です。
自動インスツルメンテーションが正しく機能するように、他のアプリケーションモジュール (express や mysql など) をインポートする前に、sdk.start() を呼び出す必要があります。

自動インジェクション

コードレスインスツルメンテーションの場合、環境変数で SDK を設定し、-r フラグを使用して起動時にプリロードします。

このモードではステップ 2 で設定した環境変数を使用するため、コードの変更は不要です。

ステップ 4：アプリケーションの起動

プログラマティックモードでのアプリケーションの起動

プログラマティックモード (モード 1) を使用している場合、標準コマンドでアプリケーションを起動してください。

node app.js

自動インジェクションを使用したアプリケーションの起動 (レジスタモード)

レジスタモード (ステップ 3 のモード 2) を使用している場合、Node.js の -r フラグを使用してプローブをプリロードしてください。

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

-r フラグは、ARMS Node.js プローブを初期化し、非侵入型インスツルメンテーションを有効にします。

ESM ローダーを使用したアプリケーションの起動 (ESM プロジェクト)

プロジェクトで ES モジュールを使用している場合、Node.js ローダーを使用して、モジュール読み込みフェーズ中に SDK を自動的にインジェクションできます。

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

この方法は、純粋な ESM プロジェクトに適しており、起動コマンドに --experimental-loader フラグを追加する必要があります。

インストールの検証

約 1 分後、ARMS コンソールの [アプリケーション監視] > [アプリケーションリスト] にアプリケーションが表示されることを確認してください。アプリケーションがリストに表示され、データがレポートされていれば、インストールは成功です。

高度な設定

カスタム設定

プログラマティックにプローブの動作をカスタマイズすることもできます。

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',
  // その他のカスタム設定 (サンプリングポリシーやカスタムエクスポーターなど)
});

sdk.start();

環境変数による設定 (レジスタモード)

レジスタモードを使用する場合、次の環境変数がサポートされています。

パラメータ	説明	必須
`ARMS_APP_NAME`	アプリケーション名	はい
`ARMS_LICENSE_KEY`	ARMS ライセンスキー	はい
`ARMS_REGION_ID`	ARMS リージョン ID (例： cn-hangzhou)	はい
`ARMS_WORKSPACE`	ARMS ワークスペース	いいえ
`CMS_ENABLE_CONSOLE_EXPORTER`	コンソールエクスポーターを有効にします。有効な値： `true`、`false`	いいえ
`CMS_OTLP_ENDPOINT`	OTLP エクスポートエンドポイントの URL	いいえ
`OTEL_LOG_LEVEL`	プローブのログレベルを設定します。有効な値： `debug`、`info`、`warn`、`error`	いいえ。デフォルト： `info`

よくある質問

プローブはアプリケーションのパフォーマンスに影響しますか？

プローブは最小限のオーバーヘッドとなるように設計されており、パフォーマンスへの影響は通常 5% 未満です。

どの Node.js フレームワークがサポートされていますか？

プローブは、Express、Koa、Fastify、Hapi、Restify などの主要な Node.js Web フレームワーク、および MySQL、PostgreSQL、Redis、MongoDB 用のデータベースクライアントをサポートしています。

SDK を最初にインポートする必要がありますか？

はい。他のアプリケーションモジュール (express や mysql など) をインポートする前に、sdk.start() を呼び出すか、-r プリロードフラグを使用する必要があります。そうしないと、これらのモジュールの自動インスツルメンテーションが失敗します。

プローブを無効にするにはどうすればよいですか？

プローブを正常にシャットダウンするには、sdk.shutdown() メソッドを呼び出してください。レジスタモードを使用している場合、プロセスの終了時にプローブは自動的にシャットダウンされます。

TypeScript はサポートされていますか？

はい。SDK は TypeScript で記述されており、完全な型定義が含まれています。

プローブのバージョンを固定できますか？

はい。次のコマンドを実行して、特定のバージョンのプローブをインストールできます。

npm install @loongsuite/cms_node_sdk@<version>

<version> を実際のバージョン番号に置き換えてください。