チュートリアル： Instana トレースSDKを使用したカスタムスケジューラのトレース設定

この custom-scheduler-example チュートリアルのサンプルコードは、 github.com でご覧いただけます。 これは、 http://localhost:8080/ 上の Hello World サービスを 4 秒ごとに呼び出し、応答をコンソールに出力する単純なスケジューラーを実装します。

この例を実行すると、HTTP呼び出しが モニター対象外のソースからのものであることが分かります。

このサンプルコードでは、発信コールに Apache の HTTP クライアントを使用しています。 Apache HTTP クライアントは、Instana エージェントでサポートされています。 では、要求のソースが Instana で表示されないのはなぜでしょうか。

これは、Instana が発信呼び出しをインスツルメントするのは、それが既存のトレース・コンテキストで発生した場合のみであるためです。 この例では、発信呼び出しはインスツルメントされていないカスタム・スケジューラーによってトリガーされています。 したがって、既存のトレース・コンテキストが見つからないため、呼び出しはインスツルメントされません。

カスタムスケジューラのトレースを有効にするには、まず Java Trace SDK を依存関係として追加する必要があります。 Maven の場合は以下のようになります。

<dependency>
  <groupId>com.instana</groupId>
  <artifactId>instana-java-sdk</artifactId>
  <version>1.2.0</version>
</dependency>

HttpClientJob が呼び出されるたびに新しいトレース・コンテキストを作成するには、@Span 注釈をジョブの run() メソッドに追加します。

@Span(type = Span.Type.ENTRY, value = "my-custom-scheduler")
public void run() {
  // ...
}

この注釈は、run() メソッドが呼び出されるたびに ENTRY スパンを生成するように Java エージェントに指示します。

その次に、Instana エージェントの configuration.yaml ファイルに以下を追加して、パッケージ com.instana.sample.* 内の Java クラスをスキャンして @Span 注釈を探すように指示します。

com.instana.plugin.javatrace:
  instrumentation:
    sdk:
      packages:
        - 'com.instana.sample'

ここで、` HTTP ` の呼び出しごとにトレース HelloWorldJob.run() コンテキストが作成され、送信される `` リクエストはこのトレースコンテキスト内で実行されます。 Instana では、以下のように表示されます。

これで、Apache HTTP クライアントの自動インスツルメンテーションから収集されたすべてのメタデータを含め、HTTP GET 要求のソースがトレースされるようになりました。

スケジューラー・ジョブ自体は、モニター対象外のソースを持つ空の呼び出しとして視覚化されます。

前のセクションで示したように、スケジューラジョブは、注釈のない空の呼び出しとして視覚化されます。 SDK の SpanSupport.annotate() メソッドを呼び出して、カスタム・メタデータを追加できます。 HttpClientJob.run() メソッドの先頭で SpanSupport.annotate() を呼び出すだけです。

Override
@Span(type = Span.Type.ENTRY, value = SPAN_NAME)
public void run() {
  SpanSupport.annotate(Span.Type.ENTRY, SPAN_NAME, "tags.batch.job", "hello world job");
  // ...

OpenTracing's のセマンティック規約で規定されているように、ジョブの ENTRY スパンを設定 tags.batch.job する際、 Instana は、そのスパンを型 であるかのように扱い、欠落している BATCH ソースがないことを認識するようになりました。

「無制限分析」ビューでカスタム・タグを検索することもできます。

SpanSupport.annotate(Span.Type.ENTRY, SPAN_NAME, "tags.error", "true");

このチュートリアルでは、カスタム・スケジューラーの新しいトレース・コンテキストを作成したので、バッチ・ジョブを Instana の発信 HTTP 呼び出しのソースとして認識できるようになりました。

SDK の詳細については、SDK の JavaDocを参照してください。 例えば、@SpanParam 注釈および @SpanReturn 注釈を使用すると、パラメーターをキャプチャーしたりスパンの追加情報として値を戻したりすることが非常に簡単になります。これは、シナリオによっては SpanSupport.annotate() を明示的に呼び出すよりはるかに便利な場合があります。