Insightを使ったトレース

GraalVM Insightを使用すると、標準のOpenTracing APIを介して、スムーズで宣言的なアドホックトレースを実装できます。トレースは実行中のアプリケーションに追加でき、オンザフライでカスタマイズして、誤動作のインシデントを調査するために必要な適切な情報を抽出できます。

以下の例では、GraalVM Insightを使用したトレース機能を示します。開始するには、Node.js用のJaegerのクライアント側計測ライブラリをインストールします。

./bin/npm install jaeger-client@3.17.1

これで、tracerオブジェクトを介して、インストゥルメントagent.jsでjaeger-clientモジュールによって提供されるOpenTracing APIを使用できます（このガイドの後半で説明します）。

let initialize = function(tracer) {
    var counter = 0;

    insight.on('enter', function(ctx, frame) {
        const args = frame.args;
        if ('request' !== frame.type || args.length !== 2 || typeof args[0] !== 'object' || typeof args[1] !== 'object') {
            return;
        }
        const req = args[0];
        const res = args[1];
        const span = tracer.startSpan("request");
        span.setTag("span.kind", "server");
        span.setTag("http.url", req.url);
        span.setTag("http.method", req.method);
        res.id = ++counter;
        res.span = span;
        console.log(`agent: handling #${res.id} request for ${req.url}`);
    }, {
        roots: true,
        rootNameFilter: 'emit',
        at: {
            sourcePath: '.*events.js'
        }
    });

    insight.on('return', function(ctx, frame) {
        var res = frame['this'];
        if (res.span) {
            res.span.finish();
            console.log(`agent: finished #${res.id} request`);
        } else {
            //Caused, for example, by Tracer itself connecting to the Jaeger server
        }
    }, {
        roots: true,
        rootNameFilter: 'end',
        at: {
            sourcePath: '.*_http_outgoing.js'
        }
    });
    console.log('agent: ready');
};

システムは、HTTPリクエストへのレスポンスの初期化と終了に使用されるemit('request', ...)関数とres.end()関数にフックします。 resオブジェクトは動的なJavaScriptオブジェクトであるため、ソースevents.jsのemit関数のenterハンドラでid属性とspan属性を追加できます。その後、end関数のreturnハンドラでこれらの属性を使用できます。

GraalVM Insightは、frame変数とそのフィールドへのアクセスを提供します。そのため、インストゥルメントはreq.urlまたはreq.methodの値を読み取り、それらをspan.setTag値としてOpenTracingサーバーに提供できます。

このインストゥルメントを使用すると、適切なタイミングで有効にできるかどうかが問題になります。 Node.jsアプリケーションへのInsightの埋め込みセクションで、管理サーバーを作成し、必要に応じてトレーススクリプト（OpenTracingベースのスクリプトを含む）を動的に適用する方法を確認してください。このガイドでは、より簡単なものを使用します。

jaegerオブジェクトが提供されたときにインストゥルメントを有効にします。

let initializeJaeger = function (ctx, frame) {
    insight.off('enter', initializeJaeger);

    let jaeger = frame.jaeger;

    var initTracer = jaeger.initTracer;
    console.log('agent: Jaeger tracer obtained');

    // See schema https://github.com/jaegertracing/jaeger-client-node/blob/master/src/configuration.js#L37
    var config = {
      serviceName: 'insight-demo',
      reporter: {
        // Provide the traces endpoint. This forces the client to connect directly to the Collector and send
        // spans over HTTP
        collectorEndpoint: 'http://localhost:14268/api/traces',
        // Provide username and password if authentication is enabled in the Collector
        // username: '',
        // password: '',
      },
      sampler: {
          type : 'const',
          param : 1
      }
    };
    var options = {
      tags: {
        'insight-demo.version': '1.1.2',
      },
    //  metrics: metrics,
      logger: console,
      sampler: {
          type : 'const',
          param : 1
      }
    };

    var tracer = initTracer(config, options);
    initialize(tracer);
};

insight.on('return', initializeJaeger, {
  roots: true,
  rootNameFilter: 'jaegerAvailable'
});

このインストゥルメントは、メインサーバースクリプトからの支援が必要です。 server.jsにjaeger-clientモジュールを取得させ、jaegerAvailable関数を使用してエージェントに渡します。次に、典型的なHTTPサーバーを作成します。 server.jsの内容は次のとおりです。

function jaegerAvailable(jaeger) {
    console.log("Providing Jaeger object to the agent");
}
jaegerAvailable(require("jaeger-client"));

const http = require("http");
const srv = http.createServer((req, res) => {
    console.log(`server: obtained request ${res.id}`);
    setTimeout(() => {
        res.write(`OK# ${res.id}`);
        console.log(`server: replied to request ${res.id}`);
        res.end();
    }, 5);
});
srv.listen(8080);

これらの2つのファイルを使用すると、ノードアプリケーションとエージェントを起動できます。ただし、まずJaegerサーバーを起動します。

docker run -d --name jaeger \
-e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
-p 5775:5775/udp   -p 6831:6831/udp   -p 6832:6832/udp \
-p 5778:5778   -p 16686:16686   -p 14268:14268   -p 9411:9411 \
jaegertracing/all-in-one:latest

./bin/node --insight=agent.js server.js
Providing Jaeger object to the agent
agent: Jaeger tracer obtained
Initializing Jaeger Tracer with RemoteReporter and ConstSampler(always)
agent: ready

これで、http://localhost:16686/で利用可能なJaeger UIに接続し、サーバーに負荷をかけることができます。

ab -c 10 -n 10000 http://localhost:8080/

サーバーはリクエストを処理している間、コンソールに詳細情報を出力し、Jaeger UIはトレースで埋められます。

Jaeger UI

これで、プレーンなNode.jsアプリケーションにトレースを追加する方法のガイドは完了です。トレースは独自のagent.jsファイルに分離されたままであり、起動時（ここで示したとおり）または必要に応じて動的に適用できます。

次に読むもの #

Insightの詳細と、いくつかの課題について学ぶには、Insightマニュアルにアクセスしてください。

Insightを使ったトレース

次に読むもの #

お問い合わせ