observability

assistant-ui オブザーバビリティ

最新の API については、常に assistant-ui.com/llms.txt を参照してください。

オブザーバビリティには 2 つの別個のレイヤーがあります。Langfuse、LangSmith、Helicone はバックエンドのモデル呼び出しを計測します。@assistant-ui/react-o11y は、アプリケーションがすでに収集したスパンデータを描画します。プロバイダーにトレースを送信したり、アシスタントランタイムからスパンを導出したりはしません。

リファレンス

• ./references/langfuse.md -- Langfuse 用の OpenTelemetry セットアップ、トレース属性、サーバーレスでのフラッシュ。
• ./references/langsmith.md -- LangSmith 用の wrapAISDK、メタデータ、サーバーレスでのフラッシュ。
• ./references/helicone.md -- AI SDK および OpenAI SDK のルート用の Helicone プロキシセットアップ。
• ./references/react-o11y.md -- SpanResource、エクスポートされるすべてのスパンプリミティブパーツ、スパンコントラクト、タイムライン属性、スタイル付きの TraceWaterfall オプション。

バックエンド統合の選択

必要なデータモデルに基づいて、いずれか 1 つのプロバイダーを使用します。

• Langfuse は、experimental_telemetry が有効なときに AI SDK が出力する OpenTelemetry スパンを受信します。エージェントのターン、ツール呼び出し、モデル呼び出しにまたがる階層的なトレースに使用します。
• LangSmith は、wrapAISDK(ai) を通じて AI SDK の関数をラップします。トレース、評価、プロンプト管理を LangChain や LangGraph のツール群と一緒に扱いたい場合に使用します。
• Helicone はプロバイダーのリクエストをプロキシします。AI SDK の呼び出し形式を変えずに、リクエストログ、コスト、レイテンシ、プロンプトの差分を確認したい場合に使用します。

Langfuse と Helicone は併用できます。一方は OpenTelemetry スパンを消費し、もう一方はプロバイダーのトラフィックをプロキシするからです。LangSmith は独自のラッパーパスであるため、元の AI SDK 関数ではなく、ラップされた AI SDK 関数を使用してください。

実装の順序

1. テレメトリーの送信先を担うプロバイダー統合を選択します。
2. そのサーバー環境変数と、起動時の計測またはプロバイダー設定を追加します。
3. 1 つのルートを計測し、実際のリクエストがプロバイダーのダッシュボードに到達することを確認します。
4. 本番環境でトレースを信頼できるものとして扱う前に、サーバーレスでのフラッシュを追加します。
5. 製品がアプリ内でのトレース表示を必要とする場合にのみ、react-o11y で別個の SpanData[] フィードを描画します。

ルートハンドラーの境界

プロバイダーの認証情報と計測はサーバー上に置いてください。すべての例で openai("gpt-5.6-luna") を使用し、convertToModelMessages(messages) を await し、AI SDK の UI メッセージレスポンスを返します。統合の各ページでは assistant-ui のルートヘルパーを使用していません。ルートで必要な場合は、@assistant-ui/ai-sdk からインポートしてください。@assistant-ui/react-ai-sdk は、古いインストール向けに同じ API を再エクスポートしています。

トレース属性は、実際の認証およびスレッドの状態から解決してください。プロバイダーキー、Langfuse のユーザー ID、LangSmith のメタデータ、Helicone のヘッダーをクライアントコンポーネントに置かないでください。

収集したスパンの描画

SpanResource({ spans }) は、生の SpanData[] リスト全体を受け取り、親子関係を正規化し、表示されるスパンを開始時間で並べ替え、折りたたみ状態を管理します。これを分離されたプロバイダールートにマウントします。

const config = AuiConfig({ span: SpanResource({ spans }) });

<AuiProvider extends={null} config={config}>
  <SpanPrimitive.Children components={{ Span: SpanRow }} />
</AuiProvider>;

SpanRow コンポーネントは、自動的に 1 つの表示中のスパンにスコープされます。行がタイム軸を共有する必要がある場合は、SpanPrimitive.Timeline と SpanPrimitive.TimelineBar を使用してください。スタイル付きのフラットなメッセージとツールのウォーターフォールが手持ちのデータにより適している場合は、コピーした TraceWaterfall 要素を使用してください。

よくある落とし穴

Vercel、Lambda、その他のサーバーレスランタイムでトレースが消える

• Langfuse では、関数が終了する前に await langfuseSpanProcessor.forceFlush() を呼び出すか、デプロイ固有の waitUntil パスが必要です。
• LangSmith では、関数が終了する前に await client.awaitPendingTraceBatches() を呼び出す必要があります。

Langfuse にスパンがない

• トレース対象の各 streamText または generateText 呼び出しで experimental_telemetry: { isEnabled: true } を設定してください。
• LangfuseSpanProcessor は Node ランタイムでのみ登録してください。OpenTelemetry はエッジランタイムでは動作しません。

LangSmith がルートをトレースしない

• ai から直接インポートした元の関数ではなく、wrapAISDK(ai) から分割代入した関数を呼び出してください。
• ランタイム環境で LANGSMITH_TRACING=true を設定してください。

Helicone のトラフィックが依然として直接 OpenAI に送信される

• プロバイダーの baseURL は https://oai.helicone.ai/v1 である必要があり、リクエストにはプロバイダーの認証ヘッダーだけでなく Helicone-Auth も含める必要があります。

react-o11y のビューに行が表示されない

• SpanResource を AuiConfig({ span: SpanResource({ spans }) }) でマウントし、<AuiProvider extends={null} config={config}> の下でレンダリングしてください。
• 完全な SpanData[] リストを渡してください。SpanPrimitive.Children は現在のスパンスコープを読み取るだけで、トレースを取得しません。

ドキュメントに記載されているスパンコンポーネントが存在しない

• SpanPrimitive.ChildByIndex は現在のソースから再エクスポートされていません。明示的なインデックススコープが必要な場合は、エクスポートされている SpanByIndexProvider を行コンポーネントとともに使用してください。

関連スキル

• streaming -- AI SDK のストリーム転送とルートレスポンスの処理。
• setup -- プロジェクトの作成、CLI のセットアップ、ランタイムのインストール。
• cloud -- Assistant Cloud の永続化と実行レポートの設定。
• elements -- TraceWaterfall を含む、コピーされたスタイル付き要素。