Instanaは、完全に自動化されたすぐに使用可能なトレースインスツルメンテーションを提供することを目指していますが、場合によってはこれが常に可能または優先されるとは限りません。 このような場合、ユーザーは OpenTracing、OpenCensus、Web Trace SDK または多くの言語ベースのトレースSDKで独自のカスタムインスツルメンテーションを作成することができます。

Instanaは、一貫性があり、整形式で完全なスパンとタグに依存できる場合に、最高の価値を提供します。 インスツルメンテーションはすぐに使用できますが、手動インスツルメンテーションで同じレベルを達成するにはある程度の知識が必要であり、このページで提供するよう努めています。

このページで使用される用語の定義については、トレースの概念のページを参照してください。

サポートされているトレーステクノロジーとSDK

Instanaダッシュボードにカスタムトレースを送信する方法は多数あります。 以下のセクションでは、現在サポートされているテクノロジーとSDKの概要を説明します。

Instana 言語 Tracing SDK

Instanaは、サポートされている多くの言語と任意の言語で利用できる外部SDKとともに、トレースSDKを提供します。

OpenCensus

OpenCensusはいくつかの言語で利用可能なトレースおよびメトリックAPIと実装です。ベンダー固有の 「エクスポーター」により、 デフォルトとは異なる形式でOpenCensusを使用できます。 現在Instanaは、次の言語のデータをトレースするための「エクスポーター」（OpenCensusモデルで定義されたスパンをInstanaに変換するロジック）を提供しています。

OpenTracing

OpenTracingは、ベンダー固有のカスタム「トレーサー」に依存するトレースAPIで、API呼び出しをスパンに変換して、分析のためにバックエンドに送信します。 現在Instanaは、次の言語のOpenTracingトレーサーを提供しています。

ヒントとベストプラクティス

適切な注釈付きスパンを使用して処理を改善する

Instanaは、すべての着信データに対して高度な処理と分析を実行し、アプリケーションとインフラストラクチャを最適に監視、学習、警告します。 これには、すべてのソースからのすべての着信スパンが含まれます。

Instanaの自動分析と処理を最大限に活用するために、スパンに適切なタグを追加することで、Instanaは受信スパンに最適な分析とアクションを実行できます。

たとえば、次のPython OpenTracingコードはほとんど情報を提供しません。

注：この例ではOpenTracingを使用して説明していますが、その意図はすべてのカスタムトレースコードに適用されます

import opentracing

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

このコードから、それが vanilla という名前のスパンで50msの時間がかかっていることだけが分かります。 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 への着信ウェブサーバーリクエストで結果のHTTPステータスコードは 204 あることが分かります。

上記のような十分に注釈が付けられたスパンにより、Instanaはサービスを抽出し、接続（およびそれらのヘルス）を監視し、ダッシュボードで全体的に豊かなエクスペリエンスを提供できます。

この例の詳細については、サポートされているすべてのOpenTracingタグの信頼できるリストを定義したOpenTracing仕様をご覧ください。 Instanaがサポートするタグの包括的なリスト（OpenTracingタグのスーパーセット）は、このページの最後にあります。

Entryスパンで常に新しいトレースを開始する

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

  • Entry：リクエストの受信、新しいタスクの開始、またはメッセージの消費を注釈します
  • Intermediate：呼び出しを行ったり受けたりしない内部作業に注釈を付けます（ビューのレンダリングなど）
  • Exit：リモートサービスを呼び出したり、キューにメッセージを発行したりする作業に注釈を付けます

タグ span.kind は報告されているスパンのタイプをマークします。このページの最後の表の span.kind、またはOpenTracing仕様で詳細をご覧ください。

新しいトレースを開始するときは、必ず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ヘッダーのドキュメントを参照してください。

オプション：サービス名を設定する

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

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

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

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

すべてのInstana OpenTracing Tracersは、環境変数を介してこの構成もサポートしています。 環境変数INSTANA_SERVICE_NAME をプロセスに設定した場合、値はプロセスのサービス名として使用されます。 これは、コードレベルのサービス名構成をオーバーライドします。

Instanaの全体的なサービス抽出のテクニックとルールドキュメントも参照してください。

オプション：エンドポイントとコール名を設定します

多くの言語では、エンドポイントとコール名はサービスタイプに基づいて自動的に検出されます。

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

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

Instanaの全体的なエンドポイント抽出技術とルールドキュメントも参照してください。

パステンプレート：HTTPエンドポイントの視覚的なグループ化

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スパンに / api / query / {birthdate} / {name} の値で http.path_tpl のキーをレポートすることでグループ化できます。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セマンティックコンベンションドキュメントからのものです。

種類

分散トレースの世界では、スパンにはXNUMXつの主要なカテゴリがあります。

  1. Entryスパン：リクエスト（HTTPまたはRPCサーバーなど）を受信する、キューからメッセージを消費する、またはジョブを実行するスパン
  2. Exitスパン：クライアント要求（HTTP、RPC、データベースなど）を作成する、キューにメッセージをプッシュする、またはクライアントデータベース呼び出しを行うスパン
  3. Intermediateスパン：ビューのレンダリングやアクション/コントローラー処理などのアプリケーションで実行される作業を表すスパン。

スパンの span.kind タグは、報告されているスパンのタイプを識別します。 このタグを報告することにより、Instanaはスパン間の通信を抽出、処理、およびマッピングできます。 Instanaでは、このコミュニケーションを「コール」と呼びます。

このような情報を持つことにより、Instanaはスパンを監視するだけでなく、スパン間の呼び出しを監視して、システム間の接続性をより詳細に把握できます。 これを適切に設定すると、Instanaは、スパンが報告されているときに、これらのコールの状態を監視および警告することもできます。

タグ タイプ OpenTracing準拠 説明
span.kind 文字列 ✓ RPCまたはHTTPリクエストの適切な役割として client ないし server 、およびメッセージングシナリオでの適切な役割として producer ないし consumer。 受け入れられるその他の値は、OpenTracingに準拠していないEntry、Exit、Intermediate

HTTP

HTTPスパンは、HTTPクライアント呼び出しまたはHTTPサーバー要求処理を表すものです。

タグ タイプ OpenTracing準拠 説明
http.url 文字列 ✓ このHTTPクライアント要求またはサーバー処理で使用される完全修飾HTTP URL
http.method 文字列 ✓ このHTTPクライアント要求またはサーバー処理で使用されるHTTPメソッド。 例は「GET」、「POST」、「PUT」などです
http.status_code 整数 ✓ このHTTPリクエストのHTTPステータスコード
http.status 整数 x 代替案 http.status_code 。 どちらも送信できますが、両方がサポートされています
http.path 文字列 x リクエストのHTTPパス
http.host 文字列 x クライアント要求または着信HTTP要求を処理するホストの場合、リモートホスト
http.params 文字列 x HTTPリクエストのクエリパラメータ
http.error 文字列 x エラーの場合、このスパンに関連付けられたエラーメッセージ。 例：「内部サーバーエラー」
http.header 文字列 x 「X-My-Custom-Header = afd812cab」などのこのスパンの関係でカスタムヘッダーをレポートするために使用されます
http.path_tpl 文字列 x エンドポイントを視覚的にグループ化できます。 詳細についてはパステンプレートドキュメントをご覧ください

注：

  1. これらのタグとともに常に適切な span.kind を送信する必要があります。
  2. http.host、http.path、http.params は、http.url の代わりにのみ送信する必要があります。これらのタグを組み合わせた http.url の送信はサポートされておらず、結果は未定義です。

RPC

RPCスパンは、RPC呼び出しまたはRPCサーバー呼び出し処理で行われた作業を表すものです。

タグ タイプ OpenTracing準拠 説明
rpc.call 文字列 ✓ 呼び出されるか処理されるRPC呼び出し（span.kind の値に依存）
rpc.host 文字列 ✓ クライアント呼び出しのRPCリモートホスト、またはRPCサーバーの場合、要求を処理するRPCホスト
rpc.params 文字列 x RPC呼び出しのパラメーター
rpc.port 文字列 x RPC呼び出しのポート
rpc.flavor 文字列 x XMLRPC、GRPCIOなど、使用中のRPCライブラリのフレーバー
rpc.error 文字列 x RPC呼び出しに関連するエラーメッセージ

注：これらのタグとともに適切なspan.kind を送信する必要があります。

データベース

タグ タイプ OpenTracing準拠 説明
db.instance 文字列 ✓ データベースインスタンス名。 Javaの例として、 jdbc.url = “jdbc：mysql：//127.0.0.1：3306 customers” なら、インスタンス名は“customers”
db.type 文字列 ✓ SQLデータベースの場合、”sql”。 その他の場合は、小文字のデータベースカテゴリ（”cassandra”、”hbase”、”redis”など）
db.statement 文字列 ✓ 指定されたデータベースタイプのデータベースステートメント。 db.type が”SQL”なら SELECT * FROM user_table ; db.type が”redis”なら SET mykey ‘WuValue’
db.user 文字列 ✓ “readonlyuser”ないし“reportinguser”など、データベースにアクセスするためのユーザー名

メッセージング

タグ タイプ OpenTracing準拠ですか？ 説明
message_bus.destination 文字列 ✓ メッセージを交換できるアドレス。 トピックまたはキューなどにすることができます

ピア

タグ タイプ OpenTracing準拠 説明
peer.hostname 文字列 ✓ 発信呼び出しを行う出口スパンのリモートホスト
peer.address 文字列 ✓ 発信呼び出しを行う出口スパンのリモートアドレス
peer.service 文字列 ✓ 発信呼び出しを行う出口スパンのリモート側のサービス名。 これはオプションであり、リモート側がまだインスツルメントされていないときに使用できることに注意してください

エラー

タグ タイプ OpenTracing準拠 説明
エラー ブーリアン ✓ このスパンが表す時間中にエラーが発生したかどうかを示します
メッセージ 文字列 x エラーに関連するメッセージ