Set up docs MCPClickStack は、テレメトリーデータ (ログ、メトリクス、 トレース、例外) の収集に OpenTelemetry 標準を採用しています。トレースは自動インストルメンテーションによって生成されるため、 トレーシングを活用するうえで手動の インストルメンテーションは必要ありません。
このガイドでは、以下を統合します:
- ログ
- メトリクス
- トレース
- 例外
はじめに
HyperDX OpenTelemetry インストルメンテーション パッケージをインストールする
以下のコマンドを使用して、ClickStack OpenTelemetry パッケージをインストールします。
npm install @hyperdx/node-opentelemetry yarn add @hyperdx/node-opentelemetry SDK の初期化
SDK を初期化するには、アプリケーションのエントリポイントの先頭で init 関数を呼び出します。
const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
url: 'http://your-otel-collector:4318',
apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack の場合は省略
service: 'my-service'
});import * as HyperDX from '@hyperdx/node-opentelemetry';
HyperDX.init({
url: 'http://your-otel-collector:4318',
apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack の場合は省略
service: 'my-service'
});これにより、Node.js アプリケーションのトレース、メトリクス、ログが自動的に収集されます。
ログ収集の設定
デフォルトでは、console.* のログが収集されます。winston や pino などのロガーを使用している場合は、ClickStack にログを送信するためのトランスポートをロガーに追加する必要があります。別の種類のロガーを使用している場合は、お問い合わせいただくか、該当する場合はプラットフォームのインテグレーション (たとえば Kubernetes) を確認してください。
winston をロガーとして使用している場合は、以下のトランスポートをロガーに追加する必要があります。
import winston from 'winston';
import * as HyperDX from '@hyperdx/node-opentelemetry';
const logger = winston.createLogger({
level: 'info',
format: winston.format.json(),
transports: [
new winston.transports.Console(),
HyperDX.getWinstonTransport('info', { // info 以上のログを送信
detectResources: true,
}),
],
});
export default logger;pino をロガーとして使用している場合は、以下のトランスポートをロガーに追加し、ログとトレースを相関付けるために mixin を指定する必要があります。
import pino from 'pino';
import * as HyperDX from '@hyperdx/node-opentelemetry';
const logger = pino(
pino.transport({
mixin: HyperDX.getPinoMixinFunction,
targets: [
HyperDX.getPinoTransport('info', { // info 以上のログを送信
detectResources: true,
}),
],
}),
);
export default logger;デフォルトでは、console.* メソッドはそのままでサポートされています。追加の設定は不要です。
これは、HDX_NODE_CONSOLE_CAPTURE 環境変数を 0 に設定するか、init 関数に consoleCapture: false を渡すことで無効にできます。
エラー収集の設定
ClickStack SDK は、アプリケーション内の未捕捉の例外やエラーを、完全なスタックトレースとコードコンテキスト付きで自動的に収集できます。
これを有効にするには、アプリケーションのエラーハンドリングミドルウェアの最後に次のコードを追加するか、recordException 関数を使って例外を手動で記録します。
const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
url: 'http://your-otel-collector:4318',
apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack の場合は省略
service: 'my-service'
});
const app = express();
// ルートなどを追加します
// これをすべてのルートの後に追加し、
// ほかのエラーハンドリングミドルウェアを定義する前に配置します
HyperDX.setupExpressErrorHandler(app);
app.listen(3000);const Koa = require("koa");
const Router = require("@koa/router");
const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
url: 'http://your-otel-collector:4318',
apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack の場合は省略
service: 'my-service'
});
const router = new Router();
const app = new Koa();
HyperDX.setupKoaErrorHandler(app);
// ルートなどを追加します
app.listen(3030);const HyperDX = require('@hyperdx/node-opentelemetry');
function myErrorHandler(error, req, res, next) {
// これはアプリケーション内のどこからでも使用できます
HyperDX.recordException(error);
}トラブルシューティング
SDK で問題が発生している場合は、OTEL_LOG_LEVEL 環境変数を debug に
設定すると、詳細なログ出力を有効にできます。
export OTEL_LOG_LEVEL=debug高度なインストルメンテーションの設定
コンソールログの取得
デフォルトでは、ClickStack SDK はコンソールログを取得します。これを無効にするには、
環境変数 HDX_NODE_CONSOLE_CAPTURE を 0 に設定します。
export HDX_NODE_CONSOLE_CAPTURE=0ユーザー情報またはメタデータを付加する
特定の属性や識別子 (例: user id
または email) に関連するすべてのイベントへ簡単にタグ付けするには、setTraceAttributes 関数を呼び出します。これにより、呼び出し以降、現在の trace に関連付けられたすべての
ログ/スパンに、指定した
属性が付与されます。この関数は、対象の
request/trace 内のできるだけ早い段階 (例: Express のミドルウェアスタックのできるだけ早い段階) で呼び出すことを推奨します。
これは、後で検索できるように、すべての ログ/スパンに 適切な識別子を自動的にタグ付けするための便利な方法です。識別子を自分で手動で タグ付けして伝播させる必要はありません。
userId、userEmail、userName、および teamName を指定すると、対応する値が
セッション UI に表示されますが、これらは省略可能です。そのほかの追加の値も
指定して、イベントの検索に使用できます。
import * as HyperDX from '@hyperdx/node-opentelemetry';
app.use((req, res, next) => {
// リクエストからユーザー情報を取得する...
// 現在のトレースにユーザー情報をアタッチする
HyperDX.setTraceAttributes({
userId,
userEmail,
});
next();
});HDX_NODE_BETA_MODE 環境
変数を 1 に設定するか、init 関数に betaMode: true を渡してベータモードを有効にし、
トレース属性を有効にしてください。
export HDX_NODE_BETA_MODE=1Google Cloud Run
Google Cloud Run でアプリケーションを実行している場合、Cloud Trace は 受信リクエストにサンプリング用ヘッダーを自動的に挿入します。現在は、 各インスタンスでトレースのサンプリングが毎秒 0.1 リクエストに制限されています。
@hyperdx/node-opentelemetry パッケージは、デフォルトで
サンプルレートを 1.0 に上書きします。
この動作を変更したい場合や、他の OpenTelemetry インストールで同様に設定したい場合は、
環境変数
OTEL_TRACES_SAMPLER=parentbased_always_on と OTEL_TRACES_SAMPLER_ARG=1 を
手動で設定することで、同じ結果を得られます。
詳細、および特定のリクエストでトレースを強制的に有効にする方法については、 Google Cloud Run documentation を参照してください。
自動インストルメントされるライブラリ
以下のライブラリは、SDK によって自動的にインストルメントされ、トレースが収集されます。
dnsexpressgraphqlhapihttpioredisknexkoamongodbmongoosemysqlmysql2netpgpinorediswinston
代替のインストール方法
ClickStack OpenTelemetry CLI でアプリケーションを実行する
また、opentelemetry-instrument CLI や Node.js の --require フラグを使えば、コードを変更することなくアプリケーションを自動インストルメントできます。CLI をインストールすると、自動インストルメンテーションに対応するライブラリやフレームワークの対象がより広がります。
HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' npx opentelemetry-instrument index.jsHYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' ts-node -r '@hyperdx/node-opentelemetry/build/src/tracing' index.js// アプリケーションで最初に読み込まれるファイルの先頭でこれをインポートします
// API key は引き続き `HYPERDX_API_KEY` 環境変数で指定します
import { initSDK } from '@hyperdx/node-opentelemetry';
initSDK({
consoleCapture: true, // 任意、デフォルト: true
additionalInstrumentations: [], // 任意、デフォルト: []
});OTEL_SERVICE_NAME 環境変数は、HyperDX アプリでサービスを識別するために使用されます。値には任意の名前を指定できます。
例外のキャプチャを有効にする
未処理の例外のキャプチャを有効にするには、HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE 環境変数を 1 に設定する必要があります。
HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE=1その後、Express や Koa の例外を自動的に収集する場合、または例外を手動でキャッチする場合は、上記のエラー収集の設定セクションの手順に従ってください。
自動インストルメントされるライブラリ
以下のライブラリは、上記のインストール方法を使用すると自動的にインストルメントされ (トレースされ) ます。