> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.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

export const ClickStackIntegrates = ({signals = []}) => {
  const list = Array.isArray(signals) ? signals : String(signals).split(",");
  const supported = list.map(s => String(s).trim().toLowerCase());
  const pillStyle = {
    display: "inline-flex",
    alignItems: "center",
    padding: "0.125rem 0.625rem",
    borderRadius: "9999px",
    fontSize: "0.8125rem",
    fontWeight: 500,
    lineHeight: 1.6,
    color: "#161517",
    backgroundColor: "#faff69",
    border: "1px solid rgba(0, 0, 0, .1)",
    marginRight: "0.5rem"
  };
  return <div style={{
    margin: "0 0 1.25rem"
  }}>
      <span style={{
    marginRight: "0.5rem"
  }}>このガイドで統合するシグナル:</span>
      {supported.includes("logs") && <span style={pillStyle}>ログ</span>}
      {supported.includes("metrics") && <span style={pillStyle}>メトリクス</span>}
      {supported.includes("traces") && <span style={pillStyle}>トレース</span>}
    </div>;
};

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

<ClickStackIntegrates signals={['logs', 'metrics', 'traces']} />

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

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

以下のコマンドを使用して、[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>

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

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

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

    HyperDX.init({
        url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
        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: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
        apiKey: '<YOUR_INGESTION_API_KEY>', // Managed ClickStack の場合は省略
        service: 'my-service'
    });
    ```
  </Tab>
</Tabs>

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

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

デフォルトでは、`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>

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

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

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

<Tabs>
  <Tab title="Express">
    ```javascript theme={null}
    const HyperDX = require('@hyperdx/node-opentelemetry');
    HyperDX.init({
        url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
        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: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
        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>

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

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

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

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

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

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

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

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

特定の属性や識別子 (例: 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
```

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

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) を参照してください。

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

以下のライブラリは、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)

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

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

また、`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_API_KEY>' OTEL_SERVICE_NAME='<YOUR_SERVICE_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_API_KEY>' OTEL_SERVICE_NAME='<YOUR_SERVICE_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 アプリでサービスを識別するために使用されます。値には任意の名前を指定できます。*

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

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

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

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

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

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

* [`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)