Node.jsにOpenTelemetryを導入する

VaxilaはOpenTelemetryの仕組み (計装)を利用してデータを送信しています。

このページではNode.jsのデータをVaxilaに送信する方法を解説します。

Node.js向けOpenTelemetry

OpenTelemetry には Node.js用のSDKが用意されています。

このSDKに加えて、ExpressやAWS用のSDKを使用すると、色々な範囲を計装することができます。

Collectorを使用するべきか

Vaxilaを使用する場合、SDKからデータを直接Vaxilaに送信するのではなく、Collectorを使うこともできます。

Collectorを使うかどうかを決める際は以下のページを参考にしてください。

導入方法

Node.jsには複数のWebフレームワークが存在しますが、このページでは Express への導入方法を説明します。他のフレームワークを使っている場合もほぼ同じ方法で計装することができます。

以下のステップでVaxilaを導入できます。

パッケージ追加
初期設定
独自の計装の追加 (任意)

1. パッケージ追加

以下のパッケージを使用します。

npm install @opentelemetry/api \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/resources \
  @opentelemetry/sdk-node \
  @opentelemetry/semantic-conventions

上のコマンドで追加した auto-instrumentations-node は多くのパッケージを内包しているため、Expressやhttpのように人気のライブラリは自動で計装されます。

含まれているパッケージはGitHubのページを参照してください。

また、足りない場合はOpenTelemetryのページからパッケージを探すことができます。

2. 初期設定

OpenTelemetryのデータをVaxilaに送信するためには、以下の項目を設定する必要があります。

Exporter
resource

例えば、以下のようにすると、SDKから直接Vaxilaに送信することができます。

const { Resource, processDetector, hostDetector } = require('@opentelemetry/resources');
const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-proto");
const { SemanticResourceAttributes } = require("@opentelemetry/semantic-conventions");
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');

const exporter = new OTLPTraceExporter({
  maxQueueSize: 1000,
  url: "https://telemetry.vaxila-labs.com/v1/traces",
  headers: {
    "Accept": "*/*",
    "X-Vaxila-Token": process.env.VAXILA_TOKEN,
  }
})
// デバッグ時にはConsoleSpanExporterが便利
// const exporter = new ConsoleSpanExporter()

const sdk = new NodeSDK({
  traceExporter: exporter,
  instrumentations: instrumentations: [    
    getNodeAutoInstrumentations({
      // fsの計装はスタートアップ時に大量のトレースを作り出すので、必要がなければ外したほうが便利です。
      '@opentelemetry/instrumentation-fs': {
        enabled: false,
      },
    }),
  ],
  resource: Resource.default().merge(new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: "acme_service",
    [SemanticResourceAttributes.SERVICE_VERSION]: "vX.Y.Z",
    [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: "production"
  })),
  resourceDetectors: [processDetector, hostDetector]
});

sdk.start()

この例では次の項目を設定しています。

Exporter
- url
  - https://telemetry.vaxila-labs.com/v1/traces と設定することで、データを直接Vaxilaに送信するようになります。
  - Collectorを利用する場合は、Collectorのエンドポイント (http://localhost:4318/v1/traces など) を設定してください。
- headers
  - X-Vaxila-Token と Accept のヘッダーを設定することでVaxilaと通信することができます。
  - X-Vaxila-Token には、Vaxilaで発行されたトークンを設定してください。
  - Collectorを利用する場合、ヘッダーは必要ないでしょう。
resource & resourceDetectors
- NodeSDKのresourceを設定することで、データがどこから来たかわかるようになります。

3. 独自の計装の追加 (任意)

独自のSpanを追加することで、任意の範囲を計装することができます。

計装によって、変数の値や処理時間を記録することができるようになります。

具体的には、下のように startActiveSpan で囲むと計装が追加できます。

const tracer = opentelemetry.trace.getTracer(
  'my-service-tracer'
);
tracer.startActiveSpan('awesome_action', (span) => {
  // ... 既存の処理

  span.end();
});

計装の方法は他にも用意されています。詳細はOpenTelemetryのドキュメントを参照してください。

前へGoにOpenTelemetryを導入する次へPHPにOpenTelemetryを導入する

最終更新 1 年前