OpenTelemetry

Schiftは、取得および検索操作のためにOpenTelemetryトレースを発行します。これらのトレースは、いくつかの環境変数を設定することで、Datadog、Honeycomb、Grafana Tempo、Jaeger、LangSmithなどのOTLP互換バックエンドにルーティングできます。テレメトリが構成されていない場合、計測はノーオプであり、オーバーヘッドはゼロです。

発行される内容

Schift APIは、OTEL_EXPORTER_OTLP_ENDPOINTが設定されているときにOTLPトレースエクスポータを起動時に初期化します。現在発行されるトレースは以下の通りです：

schift.bucket.search — ローカル取得パイプラインを実行するすべてのPOST /v1/buckets/{bucket_id}/searchリクエストのために作成されたトップレベルのバケット検索スパン。

各schift.bucket.searchスパンは、リクエスト、取得戦略、結果の品質を説明する属性を持っています。

テレメトリの有効化

Schift APIを起動する前に、これらの環境変数を設定してください：

export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.honeycomb.io"
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=<your-api-key>"

サーバーを再起動します。スパンはバッチ処理され、非同期にエクスポートされます。

注意: OTEL_EXPORTER_OTLP_HEADERSには認証情報が含まれています。これをシークレットマネージャーまたはデプロイメントプラットフォームのシークレットストレージから読み込むようにし、チェックインされた.envファイルからは読み込まないでください。

設定リファレンス

変数	必須	デフォルト	説明
`OTEL_EXPORTER_OTLP_ENDPOINT`	Yes	—	OTLPエンドポイントのURL。
`OTEL_EXPORTER_OTLP_HEADERS`	Usually	—	認証用のカンマ区切りのkey=valueヘッダー。
`OTEL_EXPORTER_OTLP_PROTOCOL`	No	auto	`grpc`または`http/protobuf`。
`OTEL_SERVICE_NAME`	No	`schift-api`	各スパンに付与されるサービス名。
`OTEL_TRACES_SAMPLER`	No	`always_on`	サンプラー名、例：`parentbased_traceidratio`。
`OTEL_TRACES_SAMPLER_ARG`	No	—	サンプラー引数、例：`0.1`は10%を意味します。

OTEL_EXPORTER_OTLP_ENDPOINTが設定されていない場合、init_telemetry()は即座に戻り、エクスポータ、トレーサプロバイダ、またはFastAPIの計測はインストールされません。

プロトコルの選択

Schiftはトランスポートプロトコルを自動検出するため、HTTPSエンドポイントは追加の設定なしで機能します：

OTEL_EXPORTER_OTLP_PROTOCOLがgrpcまたはhttp/protobufに設定されている場合、その値が使用されます。
それ以外の場合、HTTPSエンドポイントはhttp/protobufを使用します。
それ以外の場合、プレーンHTTPまたはgrpc://エンドポイントはgrpcを使用します。

ほとんどのマネージドベンダーはhttp/protobufを要求します。自動検出がコレクタと一致しない場合のみ、変数を明示的に設定してください。

スパン属性

schift.bucket.searchスパンには以下の属性が含まれます：

属性	型	説明
`schift.bucket.id`	string	リクエストパスからのバケットID。
`schift.search.top_k`	int	要求された結果の数。
`schift.search.mode`	string	`vector`や`hybrid`などの検索モード。
`schift.search.rerank`	bool	再ランク付けが要求されたかどうか。
`schift.search.model`	string	クエリに使用された埋め込みモデル（オーバーライドされた場合）。
`schift.expand_neighbors.enabled`	bool	隣接拡張が有効になっていたかどうか。
`schift.filter.keys`	string[]	適用されたメタデータフィルターキー。
`schift.filter.ops`	string[]	適用されたフィルター演算子（例：`eq`や`like`）。
`schift.schiftql.plan_digest`	string	実行されたSchiftQLプランのダイジェスト（該当する場合）。
`schift.search.method`	string	実行された実際の取得メソッド。
`schift.search.results.count`	int	返された結果の数。
`schift.search.scores.top`	float	トップ結果のスコア。
`schift.search.scores.avg`	float	結果全体の平均スコア。
`schift.timing.total_ms`	int	ミリ秒単位の総検索レイテンシ。
`schift.search_id`	string	内部検索相関ID。
`schift.search.error`	string	検索が失敗したときのエラータイプ。

これらの属性を使用すると、バケット、検索メソッド、フィルター形状、結果数、またはレイテンシに基づいてダッシュボードやアラートを構築できます。非構造化ログを解析する必要はありません。

FastAPIの計測

テレメトリが有効になっている場合、SchiftはFastAPIInstrumentor.instrument_app(app)も呼び出します。これにより、受信HTTPリクエストのためのスパンが作成され、W3Cトレースコンテキストが伝播されるため、Schift APIによって発行されたスパンは上流の呼び出し元と相関します。

クライアントリクエストをSchiftトレースと相関させるには、traceparentヘッダーを伝播します：

from schift import Client

client = Client(
    api_key="...",
    headers={"traceparent": current_traceparent()},
)

import { WorkspaceClient } from "@schift-io/sdk";

const client = new WorkspaceClient({
  apiKey: "...",
  headers: { traceparent: currentTraceparent() },
});

高トラフィックのためのサンプリング

デフォルトでは、すべてのトレースがサンプリングされます。高ボリュームのデプロイメントでは、サンプルレートを減少させます：

export OTEL_TRACES_SAMPLER="parentbased_traceidratio"
export OTEL_TRACES_SAMPLER_ARG="0.1"

これにより、親子相関を維持しながら、10%のトレースがサンプリングされます。

ベンダーの例

Datadog Agent

export OTEL_EXPORTER_OTLP_ENDPOINT="http://datadog-agent:4318"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

Honeycomb

export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.honeycomb.io"
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=<your-api-key>,x-honeycomb-dataset=schift"

Grafana TempoまたはJaeger

export OTEL_EXPORTER_OTLP_ENDPOINT="http://tempo:4318"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

LangSmithに特有の指示については、LangSmith integrationを参照してください。

トラブルシューティング

スパンが表示されない。 アプリが起動する前にOTEL_EXPORTER_OTLP_ENDPOINTが設定されていること、そしてエンドポイントがサーバーから到達可能であることを確認してください。init_telemetry()はアプリ作成時に一度呼び出され、起動後のランタイム変更は反映されません。
コレクタによってスパンが拒否される。 OTEL_EXPORTER_OTLP_PROTOCOLがコレクタのレシーバーと一致していることを確認してください。ほとんどのHTTPSベンダーはhttp/protobufを要求します。
高いカーディナリティ。 schift.filter.keysに無制限の値を避けてください。一部のベンダーはユニークな属性の組み合わせに対して料金を請求します。