カスタム・トレースのベスト・プラクティス

アプリケーションとインフラストラクチャーを最大限モニターし、そこから学習し、アラートを活用するために、Instana はすべての着信データに対して高度な処理と分析を実行します。 これには、すべてのソースからのすべての着信スパンが含まれます。

Instana の自動分析と自動処理のメリットを最大限に活用するには、適切なタグをスパンに追加します。それによって、Instana が着信スパンを最適な方法で分析して対処できるようになります。

たとえば、次の Python OpenTracing のコードでは、提供される情報が少なくなっています。

import opentracing

with opentracing.tracer.start_active_span('vanilla') as pscope:
  # ...
  # do something that takes 50ms
  # ...
  pscope.span.log_kv({"foo": "bar"})
 

このコードからわかるのは、 vanilla という名前のスパンが 50 ミリ秒の時間を要したことのみです。 スパンのタイプは不明です。HTTP、RPC、メッセージング・スパンのいずれでもあった可能性があります。 所要時間内に何が起きたのか、インフラストラクチャー内の他のコンポーネントと通信したかどうかなどもわかりません。

適切なコンテキストの OpenTracing タグを指定すると、Instana はこのスパンから処理すべき情報を分析して抽出します。

import opentracing
import opentracing.ext.tags as ext

with opentracing.tracer.start_active_span('webserver') as pscope:
    pscope.span.set_tag(ext.SPAN_KIND, "entry")
    pscope.span.set_tag(ext.PEER_HOSTNAME, "localhost")
    pscope.span.set_tag(ext.HTTP_URL, "/python/simple/two")
    pscope.span.set_tag(ext.HTTP_METHOD, "POST")
    pscope.span.log_kv({"foo": "bar"})

    # ...
    # work that took 50ms
    # ...

    pscope.span.set_tag(ext.HTTP_STATUS_CODE, 204)
 

このように適切な注釈が付けられたスパンは、スパンのコンテキストで何が発生したのかを Instana に詳しく知らせます。 提供されているタグから、これが /python/simple/two への着信 Web サーバー要求であり、結果の HTTP 状況コードが 204 であることがわかります。

前述のスニペットのように適切に注釈が付けられたスパンがあれば、 Instana はサービスを抽出し、接続状況やその健全性を監視することができ、ダッシュボードでの体験をより充実したものにしてくれます。

この例の詳細については、サポートされているすべての OpenTracing タグの正式な一覧を定義している OpenTracing 仕様を参照してください。 Instana でサポートされるタグの総合リスト (OpenTracing タグのスーパーセット) は、このページの最後にあります。

分散トレースには、主に次の 3 つのタイプのスパンがあります。

• Entry: 要求の受信、新規タスクの開始、またはメッセージのコンシュームに注釈を付けます。
• 中間: 通話を発信または受信しない内部作業 (例えば、ビュー・レンダリング) に注釈を付けます。
• 終了: リモート・サービスへの呼び出しを行ったり、キューにメッセージをパブリッシュしたりする作業に注釈を付けます。

span.kind タグは、報告対象のスパンのタイプにマークを付けます。 詳細については、このページ末尾の表、または『 OpenTracingspan.kind 』仕様書をご参照ください。

新規トレースを開始する場合は、Entry スパンを使用して開始します。 span.kind タグを指定しない場合、スパンは Entry タイプのスパンとみなされます。 このタグを適切な値に設定することで、Instana では、処理、バックエンド呼び出しの抽出の可視化、およびマッピングが向上します。

以下の Go の例を参照してください。

// Start a new entry span and set 'kind' to Consumer (entry)
entrySpan := ot.StartSpan("RPCJobRunner")
entrySpan.SetTag(string(ext.SpanKind), string(ext.SpanKindConsumerEnum))

// Now the RPC exit span
spanName := fmt.Sprintf("%s %s", request.Service, request.Method)
clientSpan := ot.StartSpan(spanName, ot.ChildOf(entrySpan.Context()))
clientSpan.SetTag(string(ext.SpanKind), string(ext.SpanKindRPCClientEnum))
clientSpan.SetTag("rpc.call", request.Method)

// Make the RPC call

clientSpan.Finish()
entrySpan.Finish()
 

例外などのエラーを含む作業を表すスパンには、error タグおよび message タグを含める必要があります。 これらのタグの定義については、以下の表の定義を参照してください。

ホスト、キュー、サービスなどの境界を越えてコンテキストを渡すために、分散トレースにはメソッドが含まれています。 これは通常、HTTP ヘッダーやメッセージ・キュー・ヘッダーなどのキャリアで行われます。

詳しくは、 HTTP Headersに関する資料を参照してください。

これはオプションです。 サービス名は、モニター対象のアプリケーション・プロセスに適用される名前です。 多くの言語では、使用中のフレームワークまたはプロセス・コマンド・ラインから、最適なサービス名を自動的に検出できます。

これをオーバーライドする場合は、トレーサーごとにサービス名を設定できます。 以下の Go 言語の例を参照してください。

serviceName := "default"
if *isServer {
    serviceName = "rpc-client"
} else {
    serviceName = "rpc-server"
}

opts := instana.Options{Service: serviceName})
opentracing.InitGlobalTracer(instana.NewTracerWithOptions(&opts)
 

Instana OpenTracing Tracer もすべて、環境変数を介してこの構成をサポートします。 プロセスに環境変数 INSTANA_SERVICE_NAME を設定すると、その値がプロセスのサービス名として使用されます。 これにより、コード・レベルのサービス名の構成のすべてがオーバーライドされます。

Instana のサービス抽出手法およびルールに関するドキュメントも参照してください。

これはオプションです。 多くの言語では、サービス・タイプに基づいてエンドポイント名と呼び出し名が自動的に検出されます。

これをオーバーライドする場合は、トレーサーごとにエンドポイント名と呼び出し名を設定できます。 以下の Java 言語の例を参照してください。

SpanSupport.annotate(Span.Type.ENTRY, "my-custom-span", "endpoint", "endpoint-name");
SpanSupport.annotate(Span.Type.ENTRY, "my-custom-span", "call.name", "call-name");
 

Instana のエンドポイント抽出技術およびルール全般に関する詳細については、 エンドポイントに関するドキュメントをご覧ください。

トレース SDK は、スパンの開始から終了までのスパン期間を自動的に計算します。

通常は測定対象を表しますが、対象が合致していない場合は duration タグを使用して上書きできます。

予期されている形式はミリ秒です。

// Overwrite the span duration with 15 milliseconds.
SpanSupport.annotate(Span.Type.ENTRY, "my-custom-span", "duration", "15");
 

Instana は、パス・テンプレートを使用したエンドポイントの自動グループ化をサポートします。 これは、多くのフレームワークの Instana トレースですぐに使用できます。 OpenTracing, を使用する場合は、以下に説明する通り、追加の手順が必要となります。

各種のフレームワークに、通常、以下のような REST パス・パターンがあります。

/api/query/1956-01-31/Guido-van-Rossum
/api/query/1976-04-18/Andrew-Ng
/api/query/1912-06-23/Alan-Turing
 

これらの類似したエンドポイントは、HTTP スパンの http.path_tpl キーを値 /api/query/{birthdate}/{name}で報告することによってグループ化できます。Instana はこのテンプレートを使用して、指定されたパターンに一致するエンドポイントを自動的にグループ化します。 Instana ダッシュボードでは、HTTP エンドポイントは単一のエンドポイントとしてグループ化されます。

/api/query/{birthdate}/{name}
 

以下の Go の例を参照してください。

span := ot.GlobalTracer().StartSpan("myTemplatedSpan", ext.RPCServerOption(incomingContext))
span.SetTag("http.path_tpl", "/api/query/{birthdate}/{name}")
span.SetTag(string(ext.SpanKind), string(ext.SpanKindRPCServerEnum))
span.SetTag(string(ext.HTTPUrl), req.URL.Path)
span.SetTag(string(ext.HTTPMethod), req.Method)
span.SetTag(string(ext.HTTPStatusCode), 200)
 

この機能は Instana 固有のものであり、OpenTracing に準拠していないことため、注意が必要です。

このセクションでは、スパンの識別および処理をする際に Instana が検索する特定のタグをリストします。 あるスパンに対して以下のようなタグのサブセットが検出された場合、 Instana は、受信したスパンの処理、分析、可視化、およびアラート通知をより適切に行うことができます。

以下にリストするタグは、標準の OpenTracing タグの スーパーセット であることに注意してください。 各タグには、OpenTracing に準拠しているかどうかを示すマークが付けられます。準拠していない場合は、 ✓ または x のいずれかになります。

以下のタグの説明の一部は、 『 OpenTracing 』のセマンティック規約文書から直接引用したものです。

// NodeJS SDK => JSON
span.annotate('sdk.custom.tags.graphql.fields', {
    Account: [ 'id', 'name' ],
    User: [ 'id', 'name' ]
})
span.annotate('sdk.custom.tags.graphql.arguments', {
    User: [ 'where', 'orderBy' ]
})

// Java SDK => String
SpanSupport.annotate("graphql.fields", "{ \"Account\": [\"id\", \"name\"], \"User\": [\"id\", \"name\"] }");
SpanSupport.annotate("graphql.arguments", "{ \"User\": ["\where\", \"orderBy\"] }");
 

• OpenTracing ドキュメント

• OpenCensus ドキュメント