旧バージョンのドキュメントを参照しています。最新のドキュメントはこちらをご参照ください。

トレース API リファレンス

はじめに

Gateway バージョン 3.0.0 では、トレース取得 API は Kong コアアプリケーションの一部になりました。API は kong.tracing 名前空間にあります。

トレース取得 API は OpenTelemetry API の仕様に準拠しています。この仕様では、API をモジュールのツールとして使用する方法を定義します。OpenTelemetry API に精通している場合は、トレース取得 API も理解しやすいでしょう。

トレーシングAPIを使用すると、次の操作でモジュールの計測を設定できます。

トレーサーを作成

Kongは、コアモジュールとプラグインを計測するために、内部的にグローバルトレーサーを使用します。

デフォルトでは、トレーサーはNoopTracerです。トレーサーは、 tracing_instrumentations構成が有効になっている場合に最初に初期化されます。新しいトレーサーは手動、またはグローバルトレーサーインスタンスを使用して作成できます。

local tracer

-- Create a new tracer
tracer = kong.tracing.new("custom-tracer")

-- Use the global tracer
tracer = kong.tracing

トレースをサンプリング

トレーサーのサンプリングレートは、次のように構成できます。

local tracer = kong.tracing.new("custom-tracer", {
  -- Set the sampling rate to 0.1
  sampling_rate = 0.1,
})

sampling_rateが0.1の場合、10のリクエストのうち1つがトレースされることを意味します。レートが1の場合は、すべてのリクエストがトレースされることを意味します。

スパンを作成

スパンは、トレース内の 1 つの操作を表します。スパンをネストしてトレースツリーを形成できます。各トレースにはルートスパンが含まれます。ルートスパンは通常、操作全体を記述し、オプションでサブ操作に対して 1 つ以上のサブスパンを記述します。

local tracer = kong.tracing

local span = tracer:start_span("my-span")

spanプロパティは、start_spanメソッドにテーブルを渡すことによって設定できます。

local span = tracer:start_span("my-span", {
  start_time_ns = ngx.now() * 1e9, -- override the start time
  span_kind = 2, -- SPAN_KIND
                  -- UNSPECIFIED: 0
                  -- INTERNAL: 1
                  -- SERVER: 2
                  -- CLIENT: 3
                  -- PRODUCER: 4
                  -- CONSUMER: 5
  should_sample = true, -- by setting it to `true` to ignore the sampling decision
})

完了したら、必ずスパンを終了してください。

span:finish() -- ends the span

注：スパンテーブルは、スパンが終了すると、クリアされてテーブルプールに入れられるため、スパン終了後は使用しないでください。

アクティブなスパンを取得または設定

アクティブなスパンとは現在実行されているスパンです。

オーバーヘッドを回避するために、set_active_spanメソッドを呼び出してアクティブなスパンは手動で設定されます。スパンの終了時に、アクティブなスパンは終了したスパンの親になります。

アクティブスパンを設定または取得するには、次のサンプルコードを使用できます。

local tracer = kong.tracing
local span = tracer:start_span("my-span")
tracer.set_active_span(span)

local active_span = tracer.active_span() -- returns the active span

スコープ

トレーサーは、名前空間キーによって特定のコンテキストにスコープされます。

特定の名前空間のアクティブなスパンを取得するには、以下を使用します。

-- get global tracer's active span, and set it as the parent of new created span
local global_tracer = kong.tracing
local tracer = kong.tracing.new("custom-tracer")

local root_span = global_tracer.active_span()
local span = tracer.start_span("my-span", {
  parent = root_span
})

スパン属性を設定

スパンの属性は、キーと値のペアのマップであり、テーブルを set_attributesメソッドに渡すことで設定できます。

local span = tracer:start_span("my-span")

OpenTelemetryの仕様では一般的なセマンティック属性が定義されており、これを使用して範囲を記述できます。また、UIでスパンを視覚化することも意味があります。

span:set_attribute("key", "value")

以下のスパンのセマンティック規則が定義されています。

一般: さまざまな種類の操作を説明する際に使用できる一般的なセマンティック属性。
HTTP：HTTPクライアントおよびサーバーの範囲用。
データベース: SQL および NoSQL クライアント呼び出し範囲用。
RPC/RMI : リモートプロシージャコール (gRPC など) スパン用。
メッセージング：メッセージングシステム（キュー、パブリッシュ/サブスクライブなど）スパン用。
FaaS: Function as a Service (AWS Lambda など) のスパン用。
例外: スパンに関連付けられた例外を記録します。
互換性：互換性コンポーネントによって生成されたスパンの場合、例えばOpenTracingシムレイヤーなど。

スパンイベントの設定

スパンのイベントは、add_eventメソッドにテーブルを渡すことによって設定できる時系列イベントです。

local span = kong.tracing:start_span("my-span")
span:add_event("my-event", {
  -- attributes
  ["key"] = "value",
})

エラーメッセージを記録する

このイベントはエラーメッセージを記録するためにも使用できます。

local span = kong.tracing:start_span("my-span")
span:record_error("my-error-message")

-- or (same as above)
span:add_event("exception", {
  ["exception.message"] = "my-error-message",
})

スパンステータスを設定

スパンのステータスはステータスコードであり、set_statusメソッドにテーブルを渡すことによって設定できます。

local span = kong.tracing:start_span("my-span")

-- Status codes:
-- - `0` unset
-- - `1` ok
-- - `2` error
span:set_status(2)

スパンのリリース（オプション）

スパンはプールに保存され、releaseメソッドを呼び出すことでリリースできます。

local span = kong.tracing:start_span("my-span")
span:release()

デフォルトでは、Nginx リクエストが終了した後にスパンは解放されます。

トレースの視覚化

OpenTelemetry との互換性があるため、トレースは任意の OpenTelemetry UI を通してそのまま視覚化できます。

トレースを視覚化する方法については、OpenTelemetryプラグインを参照してください。