Managed Service for OpenTelemetry:Submit trace data from a Node.js application

ステップ 1: 依存関係のインストール

cd auto-instrumentation
npm init -y
npm install express axios

ステップ 2: OpenTelemetry パッケージのインストール

npm install --save @opentelemetry/api @opentelemetry/auto-instrumentations-node

ステップ 3: アプリケーションの作成

次の例では、2 つのルートを持つ基本的な Express サーバーを作成します。

"use strict";

const axios = require("axios").default;
const express = require("express");
const app = express();

app.get("/", async (req, res) => {
  const result = await axios.get("http://localhost:7001/hello");
  return res.status(201).send(result.data);
});

app.get("/hello", async (req, res) => {
  console.log("hello world!")
  res.json({ code: 200, msg: "success" });
});

app.use(express.json());

app.listen(7001, () => {
  console.log("Listening on http://localhost:7001");
});

ステップ 4: 環境変数の設定とアプリケーションの起動

次の環境変数を設定し、アプリケーションを起動します。

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="<your-endpoint>"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
export OTEL_SERVICE_NAME="<your-service-name>"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
node main.js

次のプレースホルダーを実際の値に置き換えます。

次の表は、各環境変数について説明しています。

利用可能なすべての OpenTelemetry 環境変数の詳細については、「自動イベントトラッキング構成」をご参照ください。

ステップ 5: トレースデータの生成

トレースを生成するためにリクエストを送信します。

curl localhost:7001/hello

リクエストが完了すると、SDK はトレースデータを Managed Service for OpenTelemetry にエクスポートします。

ステップ 1: OpenTelemetry 依存関係の追加

次の依存関係を package.json ファイルに追加します。

"dependencies": {
    "@opentelemetry/api": "^1.0.4",
    "@opentelemetry/exporter-trace-otlp-grpc": "^0.27.0",
    "@opentelemetry/instrumentation": "^0.27.0",
    "@opentelemetry/instrumentation-express": "^0.27.0",
    "@opentelemetry/instrumentation-http": "^0.27.0",
    "@opentelemetry/resources": "^1.0.1",
    "@opentelemetry/sdk-trace-base": "^1.0.1",
    "@opentelemetry/sdk-trace-node": "^1.0.1"
}

ステップ 2: トレーサープロバイダーの作成

const { Resource } = require("@opentelemetry/resources");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const {
  SemanticResourceAttributes,
} = require("@opentelemetry/semantic-conventions");

const provider = new NodeTracerProvider({
  resource: new Resource({
    [SemanticResourceAttributes.HOST_NAME]: require("os").hostname(),
    // "opentelemetry-express" をご利用のサービス名に置き換えます
    [SemanticResourceAttributes.SERVICE_NAME]: "opentelemetry-express",
  }),
});

ステップ 3: フレームワークイベントトラッキングの登録

HTTP および Express イベントトラッキングを登録して、受信および送信リクエストを自動的にトレースします。

const { registerInstrumentations } = require("@opentelemetry/instrumentation");
const { HttpInstrumentation } = require("@opentelemetry/instrumentation-http");
const {
  ExpressInstrumentation,
} = require("@opentelemetry/instrumentation-express");

registerInstrumentations({
  tracerProvider: provider,
  instrumentations: [new HttpInstrumentation(), ExpressInstrumentation],
});

他のNode.jsフレームワークをインストゥルメントするには、利用可能なプラグインについては、OpenTelemetry auto-instrumentations-nodeパッケージを参照してください。

ステップ 4: エクスポーターの構成

gRPC 経由で OTLP エクスポーターを構成し、トレースデータを Managed Service for OpenTelemetry に送信します。

const metadata = new grpc.Metadata();
metadata.set("Authentication", "<your-token>");

const exporter = new OTLPTraceExporter({ url: "<your-endpoint>", metadata });
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
provider.register();

次のプレースホルダーを実際の値に置き換えます。

ステップ 5 (オプション): カスタムイベントと属性の追加

アプリケーション固有のコンテキストのために、現在のスパンにイベントと属性をアタッチします。

const api = require("@opentelemetry/api");
const currentSpan = api.trace.getSpan(api.context.active());

// タイムスタンプ付きイベントを追加
currentSpan.addEvent("timestamp", { value: Date.now() });

// カスタム属性を追加
currentSpan.setAttribute("tagKey-01", "tagValue-01");

OpenTelemetry トレース API の詳細については、「OpenTelemetry JS 入門ガイド」をご参照ください。

アプリケーションがコンソールに表示されない

• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (自動) または OTLPTraceExporter (手動) の url パラメーターがコンソールからのエンドポイントと一致することを確認します。

• エンドポイントへのネットワーク接続を確認します。アプリケーションが Alibaba Cloud の外部で実行されている場合は、VPC エンドポイントの代わりにパブリックエンドポイントを使用します。

• ご利用のアプリケーションが少なくとも 1 つのリクエストを受信していることを確認します。OpenTelemetry は、スパンをエクスポートする前にバッファーします。

• 手動イベントトラッキングの場合、トレーサープロバイダーが他のアプリケーションのインポートよりも前に初期化されていることを確認します。初期化順序の誤りは、スパン欠落の原因となります。

デバッグログの有効化

SDK の動作を検査するために、OpenTelemetry ログレベルを debug に設定します。

export OTEL_LOG_LEVEL=debug

アプリケーションを再起動し、スパンエクスポートログとエラーについてコンソール出力を確認します。エクスポートが成功すると、次のようなログエントリが生成されます。

@opentelemetry/api: Registered a global for diag v1.x.x
...
items to be sent [{"traceId":"...","spanId":"...","name":"GET /hello",...}]

スパンエントリが表示されない場合は、ご利用のアプリケーションが少なくとも 1 つのリクエストを処理しており、エンドポイントに到達可能であることを確認します。