> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickStack 用 Node.js SDK - The ClickHouse Observability Stack

# Node.js

ClickStack は、テレメトリーデータ (ログ、メトリクス、
トレース、例外) の収集に OpenTelemetry 標準を採用しています。トレースは自動インストルメンテーションによって生成されるため、
トレーシングを活用するうえで手動の
インストルメンテーションは必要ありません。

このガイドでは、以下を統合します:

* **ログ**
* **メトリクス**
* **トレース**
* **例外**

<div id="getting-started">
  ## はじめに
</div>

<div id="install-hyperdx-opentelemetry-instrumentation-package">
  ### HyperDX OpenTelemetry インストルメンテーション パッケージをインストールする
</div>

以下のコマンドを使用して、[ClickStack OpenTelemetry パッケージ](https://www.npmjs.com/package/@hyperdx/node-opentelemetry)をインストールします。

<Tabs>
  <Tab title="NPM">
    ```shell theme={null}
    npm install @hyperdx/node-opentelemetry 
    ```
  </Tab>

  <Tab title="Yarn">
    ```shell theme={null}
    yarn add @hyperdx/node-opentelemetry 
    ```
  </Tab>
</Tabs>

<div id="initializin-the-sdk">
  ### SDK の初期化
</div>

SDK を初期化するには、アプリケーションのエントリポイントの先頭で `init` 関数を呼び出します。

<Tabs>
  <Tab title="require">
    ```javascript theme={null}
    const HyperDX = require('@hyperdx/node-opentelemetry');

    HyperDX.init({
        url: 'http://your-otel-collector:4318',
        apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack の場合は省略
        service: 'my-service'
    });
    ```
  </Tab>

  <Tab title="import">
    ```javascript theme={null}
    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'
    });
    ```
  </Tab>
</Tabs>

これにより、Node.js アプリケーションのトレース、メトリクス、ログが自動的に収集されます。

<div id="setup-log-collection">
  ### ログ収集の設定
</div>

デフォルトでは、`console.*` のログが収集されます。`winston` や `pino` などのロガーを使用している場合は、ClickStack にログを送信するためのトランスポートをロガーに追加する必要があります。別の種類のロガーを使用している場合は、[お問い合わせ](mailto:support@clickhouse.com)いただくか、該当する場合はプラットフォームのインテグレーション (たとえば [Kubernetes](/ja/clickstack/integration-examples/kubernetes)) を確認してください。

<Tabs>
  <Tab title="Winston">
    `winston` をロガーとして使用している場合は、以下のトランスポートをロガーに追加する必要があります。

    ```typescript theme={null}
        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;
    ```
  </Tab>

  <Tab title="Pino">
    `pino` をロガーとして使用している場合は、以下のトランスポートをロガーに追加し、ログとトレースを相関付けるために `mixin` を指定する必要があります。

    ```typescript theme={null}
    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;
    ```
  </Tab>

  <Tab title="console.log">
    デフォルトでは、`console.*` メソッドはそのままでサポートされています。追加の設定は不要です。

    これは、`HDX_NODE_CONSOLE_CAPTURE` 環境変数を 0 に設定するか、`init` 関数に `consoleCapture: false` を渡すことで無効にできます。
  </Tab>
</Tabs>

<div id="setup-error-collection">
  ### エラー収集の設定
</div>

ClickStack SDK は、アプリケーション内の未捕捉の例外やエラーを、完全なスタックトレースとコードコンテキスト付きで自動的に収集できます。

これを有効にするには、アプリケーションのエラーハンドリングミドルウェアの最後に次のコードを追加するか、`recordException` 関数を使って例外を手動で記録します。

<Tabs>
  <Tab title="Express">
    ```javascript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Koa">
    ```javascript theme={null}
    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);
    ```
  </Tab>

  <Tab title="手動">
    ```javascript theme={null}
    const HyperDX = require('@hyperdx/node-opentelemetry');

    function myErrorHandler(error, req, res, next) {
        // これはアプリケーション内のどこからでも使用できます
        HyperDX.recordException(error);
    }
    ```
  </Tab>
</Tabs>

<div id="troubleshooting">
  ## トラブルシューティング
</div>

SDK で問題が発生している場合は、`OTEL_LOG_LEVEL` 環境変数を `debug` に
設定すると、詳細なログ出力を有効にできます。

```shell theme={null}
export OTEL_LOG_LEVEL=debug
```

<div id="advanced-instrumentation-configuration">
  ## 高度なインストルメンテーションの設定
</div>

<div id="capture-console-logs">
  ### コンソールログの取得
</div>

デフォルトでは、ClickStack SDK はコンソールログを取得します。これを無効にするには、
環境変数 `HDX_NODE_CONSOLE_CAPTURE` を 0 に設定します。

```sh copy theme={null}
export HDX_NODE_CONSOLE_CAPTURE=0
```

<div id="attach-user-information-or-metadata">
  ### ユーザー情報またはメタデータを付加する
</div>

特定の属性や識別子 (例: user id
または email) に関連するすべてのイベントへ簡単にタグ付けするには、`setTraceAttributes` 関数を呼び出します。これにより、呼び出し以降、現在の trace に関連付けられたすべての
ログ/スパンに、指定した
属性が付与されます。この関数は、対象の
request/trace 内のできるだけ早い段階 (例: Express のミドルウェアスタックのできるだけ早い段階) で呼び出すことを推奨します。

これは、後で検索できるように、すべての ログ/スパンに
適切な識別子を自動的にタグ付けするための便利な方法です。識別子を自分で手動で
タグ付けして伝播させる必要はありません。

`userId`、`userEmail`、`userName`、および `teamName` を指定すると、対応する値が
セッション UI に表示されますが、これらは省略可能です。そのほかの追加の値も
指定して、イベントの検索に使用できます。

```typescript theme={null}
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` を渡してベータモードを有効にし、
トレース属性を有効にしてください。

```shell theme={null}
export HDX_NODE_BETA_MODE=1
```

<div id="google-cloud-run">
  ### Google Cloud Run
</div>

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](https://cloud.google.com/run/docs/trace) を参照してください。

<div id="auto-instrumented-libraries">
  ### 自動インストルメントされるライブラリ
</div>

以下のライブラリは、SDK によって自動的にインストルメントされ、トレースが収集されます。

* [`dns`](https://nodejs.org/dist/latest/docs/api/dns.html)
* [`express`](https://www.npmjs.com/package/express)
* [`graphql`](https://www.npmjs.com/package/graphql)
* [`hapi`](https://www.npmjs.com/package/@hapi/hapi)
* [`http`](https://nodejs.org/dist/latest/docs/api/http.html)
* [`ioredis`](https://www.npmjs.com/package/ioredis)
* [`knex`](https://www.npmjs.com/package/knex)
* [`koa`](https://www.npmjs.com/package/koa)
* [`mongodb`](https://www.npmjs.com/package/mongodb)
* [`mongoose`](https://www.npmjs.com/package/mongoose)
* [`mysql`](https://www.npmjs.com/package/mysql)
* [`mysql2`](https://www.npmjs.com/package/mysql2)
* [`net`](https://nodejs.org/dist/latest/docs/api/net.html)
* [`pg`](https://www.npmjs.com/package/pg)
* [`pino`](https://www.npmjs.com/package/pino)
* [`redis`](https://www.npmjs.com/package/redis)
* [`winston`](https://www.npmjs.com/package/winston)

<div id="alternative-installation">
  ## 代替のインストール方法
</div>

<div id="run-the-application-with-cli">
  ### ClickStack OpenTelemetry CLI でアプリケーションを実行する
</div>

また、`opentelemetry-instrument` CLI や Node.js の `--require` フラグを使えば、コードを変更することなくアプリケーションを自動インストルメントできます。CLI をインストールすると、自動インストルメンテーションに対応するライブラリやフレームワークの対象がより広がります。

<Tabs>
  <Tab title="NPX を使用">
    <Info>
      **Managed ClickStack**

      Managed ClickStack では `HYPERDX_API_KEY` は省略できます。
    </Info>

    ```shell theme={null}
    HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' npx opentelemetry-instrument index.js
    ```
  </Tab>

  <Tab title="カスタムエントリポイント（例: Nodemon、ts-node など）">
    <Info>
      **Managed ClickStack**

      Managed ClickStack では `HYPERDX_API_KEY` は省略できます。
    </Info>

    ```shell theme={null}
    HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' ts-node -r '@hyperdx/node-opentelemetry/build/src/tracing' index.js
    ```
  </Tab>

  <Tab title="コードのインポート">
    ```javascript theme={null}
    // アプリケーションで最初に読み込まれるファイルの先頭でこれをインポートします
    // API key は引き続き `HYPERDX_API_KEY` 環境変数で指定します
    import { initSDK } from '@hyperdx/node-opentelemetry';

    initSDK({
        consoleCapture: true, // 任意、デフォルト: true
        additionalInstrumentations: [], // 任意、デフォルト: []
    });
    ```
  </Tab>
</Tabs>

*`OTEL_SERVICE_NAME` 環境変数は、HyperDX アプリでサービスを識別するために使用されます。値には任意の名前を指定できます。*

<div id="enabling-exception-capturing">
  ### 例外のキャプチャを有効にする
</div>

未処理の例外のキャプチャを有効にするには、`HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE` 環境変数を 1 に設定する必要があります。

```shell theme={null}
HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE=1
```

その後、Express や Koa の例外を自動的に収集する場合、または例外を手動でキャッチする場合は、上記の[エラー収集の設定](#setup-error-collection)セクションの手順に従ってください。

<div id="auto-instrumented-libraries">
  ### 自動インストルメントされるライブラリ
</div>

以下のライブラリは、上記のインストール方法を使用すると自動的にインストルメントされ (トレースされ) ます。

* [`amqplib`](https://www.npmjs.com/package/amqplib)
* [`AWS Lambda Functions`](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html)
* [`aws-sdk`](https://www.npmjs.com/package/aws-sdk)
* [`bunyan`](https://www.npmjs.com/package/bunyan)
* [`cassandra-driver`](https://www.npmjs.com/package/cassandra-driver)
* [`connect`](https://www.npmjs.com/package/connect)
* [`cucumber`](https://www.npmjs.com/package/@cucumber/cucumber)
* [`dataloader`](https://www.npmjs.com/package/dataloader)
* [`dns`](https://nodejs.org/dist/latest/docs/api/dns.html)
* [`express`](https://www.npmjs.com/package/express)
* [`fastify`](https://www.npmjs.com/package/fastify)
* [`generic-pool`](https://www.npmjs.com/package/generic-pool)
* [`graphql`](https://www.npmjs.com/package/graphql)
* [`grpc`](https://www.npmjs.com/package/@grpc/grpc-js)
* [`hapi`](https://www.npmjs.com/package/@hapi/hapi)
* [`http`](https://nodejs.org/dist/latest/docs/api/http.html)
* [`ioredis`](https://www.npmjs.com/package/ioredis)
* [`knex`](https://www.npmjs.com/package/knex)
* [`koa`](https://www.npmjs.com/package/koa)
* [`lru-memoizer`](https://www.npmjs.com/package/lru-memoizer)
* [`memcached`](https://www.npmjs.com/package/memcached)
* [`mongodb`](https://www.npmjs.com/package/mongodb)
* [`mongoose`](https://www.npmjs.com/package/mongoose)
* [`mysql`](https://www.npmjs.com/package/mysql)
* [`mysql2`](https://www.npmjs.com/package/mysql2)
* [`nestjs-core`](https://www.npmjs.com/package/@nestjs/core)
* [`net`](https://nodejs.org/dist/latest/docs/api/net.html)
* [`pg`](https://www.npmjs.com/package/pg)
* [`pino`](https://www.npmjs.com/package/pino)
* [`redis`](https://www.npmjs.com/package/redis)
* [`restify`](https://www.npmjs.com/package/restify)
* [`socket.io`](https://www.npmjs.com/package/socket.io)
* [`winston`](https://www.npmjs.com/package/winston)