Zipkin Configuration

このページは、まだ日本語ではご利用いただけません。翻訳中です。

古いプラグインバージョンのドキュメントを閲覧しています。

構成

このプラグインはDBレスモードに対応しています。

互換性のあるプロトコル

Zipkinプラグインは以下のプロトコルに対応しています：

grpc, grpcs, http, https, tcp, tls, tls_passthrough, udp, ws, wss

パラメータ

このプラグインの設定で使用できるすべてのパラメータのリストは次のとおりです。

• name or plugin

  string required

  プラグイン名。この場合は zipkin 。

  • Kong Admin API、Kong Konnect API、宣言型構成、または decK ファイルを使用する場合、フィールドはnameです。
  • Kubernetes で KongPlugin オブジェクトを使用する場合、フィールドはpluginです。

• instance_name

  string

  プラグインのインスタンスを識別するための任意のカスタム名 (例: zipkin_my-service 。

  インスタンス名はKong ManagerとKonnectに表示されるので、 例えば複数のサービスで同じプラグインを複数のコンテキストで実行する場合に便利です。また、Kong Admin API経由で特定のプラグインインスタンスに アクセスするためにも使用できます。

  インスタンス名は、次のコンテキスト内で一意である必要があります。

  • Kong Gateway Enterpriseのワークスペース内
  • Konnectのコントロールプレーン（CP）またはコントロールプレーン（CP）グループ内
  • Kong Gateway (OSS)の全世界

• service.name or service.id

  string

  プラグインが対象とするサービス名または ID。最上位の /plugins エンドポイント. からプラグインをサービスに追加する場合は、これらのパラメータのいずれかを設定してください /services/{serviceName|Id}/plugins を使用する場合は必要ありません。

• route.name or route.id

  string

  プラグインがターゲットとするルート名または ID。最上位の /plugins エンドポイント. を通るルートにプラグインを追加する場合は、これらのパラメータのいずれかを設定してください /routes/{routeName|Id}/plugins を使用する場合は必要ありません。

• consumer.name or consumer.id

  string

  プラグインがターゲットとするコンシューマーの名前または ID。 最上位の /plugins エンドポイント. からコンシューマーにプラグインを追加する場合は、これらのパラメーターのいずれかを設定してください /consumers/{consumerName|Id}/pluginsを使用する場合は必要ありません。

• enabled

  boolean default: true

  このプラグインが適用されるかどうか。

• config

  record required
  • local_service_name

    string required default: kong

    The name of the service as displayed in Zipkin. Customize this name to tell your Kong Gateway services apart in Zipkin request traces.

  • http_endpoint

    string

    The full HTTP(S) endpoint to which Zipkin spans should be sent by Kong. If not specified, the Zipkin plugin will only act as a tracing header generator/transmitter.

  • sample_ratio

    number default: 0.001 between: 0 1

    How often to sample requests that do not contain trace IDs. Set to 0 to turn sampling off, or to 1 to sample all requests. The value must be between zero (0) and one (1), inclusive.

  • default_service_name

    string

    Set a default service name to override unknown-service-name in the Zipkin spans.

  • include_credential

    boolean required default: true

    Specify whether the credential of the currently authenticated consumer should be included in metadata sent to the Zipkin server.

  • traceid_byte_count

    integer required default: 16 Must be one of: 8, 16

    The length in bytes of each request’s Trace ID. The value can be either 8 or 16.

  • header_type

    string required default: preserve Must be one of: preserve, ignore, b3, b3-single, w3c, jaeger, ot, datadog

    All HTTP requests going through the plugin are tagged with a tracing HTTP request. This property codifies what kind of tracing header the plugin expects on incoming requests.

    Possible values: b3, b3-single, w3c, preserve, jaeger, ot, or ignore.

    • b3: Expects Zipkin’s B3 multiple headers on incoming requests, and will add them to the transmitted requests if the headers are missing from those requests.
    • b3-single: Expects or adds Zipkin’s B3 single-header tracing headers.
    • w3c: Expects or adds W3C’s traceparent tracing header.
    • preserve: Does not expect any format, and will transmit whatever header is recognized or present, with a default of b3 if none is found. In case of a mismatch between the expected and incoming tracing headers (for example, when header_type is set to b3 but a w3c-style tracing header is found in the incoming request), then the plugin will add both kinds of tracing headers to the request and generate a mismatch warning in the logs.
    • jaeger: Expects or adds Jaeger-style tracing headers (uber-trace-id).
    • ot: Expects or adds OpenTelemetry tracing headers of the form ot-tracer-*.
    • ignore: Does not read any tracing headers from the incoming request. Starts a new request using the default_header_type value, or falls back to b3 if there is no default_header_type value set.

  • default_header_type

    string required default: b3 Must be one of: b3, b3-single, w3c, jaeger, ot, datadog

    Allows specifying the type of header to be added to requests with no pre-existing tracing headers and when config.header_type is set to "preserve". When header_type is set to any other value, default_header_type is ignored.

    Possible values are b3, b3-single, w3c, jaeger, or ot. See the entry for header_type for value definitions.

  • tags_header

    string required default: Zipkin-Tags

    The Zipkin plugin will add extra headers to the tags associated with any HTTP requests that come with a header named as configured by this property. The format is name_of_tag=value_of_tag, separated by semicolons (;).

    For example: with the default value, a request with the header Zipkin-Tags: fg=blue; bg=red will generate a trace with the tag fg with value blue, and another tag called bg with value red.

  • static_tags

    array of type record

    The tags specified on this property will be added to the generated request traces. For example: [ { "name": "color", "value": "red" } ].

    • name

      string required

    • value

      string required

  • http_span_name

    string required default: method Must be one of: method, method_path

    Specify whether to include the HTTP path in the span name.

    Options:

    • method: Do not include the HTTP path. This is the default.
    • method_path: Include the HTTP path.

  • connect_timeout

    integer default: 2000 between: 0 2147483646

    The timeout, in milliseconds, for establishing a connection to the Zipkin server.

  • send_timeout

    integer default: 5000 between: 0 2147483646

    The timeout, in milliseconds, between two successive write operations when sending a request to the Zipkin server.

  • read_timeout

    integer default: 5000 between: 0 2147483646

    The timeout, in milliseconds, between two successive read operations when receiving a response from the Zipkin server.

  • http_response_header_for_traceid

    string

  • phase_duration_flavor

    string required default: annotations Must be one of: annotations, tags

    Specify whether to include the duration of each phase as an annotation or a tag.

    Options:

    • annotations: Include the duration of each phase as an annotation. This is the default.
    • tags: Include the duration of each phase as a tag.

  • queue

    record required
    • max_batch_size

      number default: 1 between: 1 1000000

      Maximum number of entries to be processed together as a batch.

    • max_coalescing_delay

      number default: 1 between: 0 3600

      Maximum number of seconds (as a fraction) that can elapse after the first entry was queued before the queue starts processing entries. This parameter has no effect when batch_max_size is one because queued entries will be sent immediately in that case.

    • max_entries

      number default: 10000 between: 1 1000000

      Maximum number of entries that can be waiting on the queue. Once this number of requests is reached, the oldest entry is deleted from the queue before a new one is added.

    • max_bytes

      number

      Maximum number of bytes that can be waiting on a queue. Once this many bytes are present on a queue, old entries up to the size of a new entry to be enqueued are deleted from the queue.

    • max_retry_time

      number default: 60

      Time (in seconds) before the queue gives up trying to send a batch of entries. Once this time is exceeded for a batch, it is deleted from the queue without being sent. If this parameter is set to -1, no retries will be made for a failed batch.

    • initial_retry_delay

      number default: 0.01

    • max_retry_delay

      number default: 60

      Maximum time (in seconds) between retries sending a batch of entries. The interval between retries follows an exponential back-off algorithm capped at this number of seconds.