> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Langfuse

> CloudThinker と Langfuse を接続して、LLM トレースの調査、会話のデバッグ、評価レビュー、プロンプト監査を実現する

Langfuse プロジェクトを接続することで、CloudThinker エージェントが LLM トレースの調査、会話のデバッグ、評価スコアとデータセットのレビュー、オブザーバビリティスタック全体のプロンプトバージョンの監査を行えるようになります。Langfuse は Langfuse ホストに対して**プロジェクトスコープの API キーペア**（公開キーとシークレットキー）で認証します。このセットアップは Langfuse Cloud とセルフホストインスタンスの両方で同じです。

## 前提条件

* 調査対象の **Langfuse Cloud またはセルフホストプロジェクト**。
* そのプロジェクトの**プロジェクトスコープ API キーペア**（公開キーとシークレットキー）。
* **Langfuse ホスト URL**（EU は `https://cloud.langfuse.com`、US は `https://us.cloud.langfuse.com`、またはセルフホストのドメイン）。

<Info>
  Langfuse の API キーは単一のプロジェクトにスコープされます。CloudThinker がアクセスすべきプロジェクトでキーペアを作成し、アクセスの監査と失効を簡単に行えるよう CloudThinker 専用のキーペアを使用してください。
</Info>

## セットアップ

<Steps>
  <Step title="Langfuse を開く">
    Langfuse にサインインし、CloudThinker で調査するプロジェクトを選択します。
  </Step>

  <Step title="API キーペアを作成する">
    **Project → Settings → API Keys** に移動し、**Create new API keys** をクリックします。Langfuse が以下を生成します。

    * `pk-lf-` プレフィックスの**公開キー**
    * `sk-lf-` プレフィックスの**シークレットキー**

    シークレットキーを直ちにコピーしてください。一度しか表示されず、後から取得できません。
  </Step>

  <Step title="CloudThinker で接続を追加する">
    **Connections → Langfuse** に移動して以下を入力します。

    * **Host**: Langfuse のベース URL（例: `https://cloud.langfuse.com`）。パスを含まないベース URL のみ
    * **Public Key**: 作成した `pk-lf-` キー
    * **Secret Key**: 作成した `sk-lf-` キー

    **Connect** をクリックします。CloudThinker が認証情報を検証し、**Connected** ステータスを表示します。
  </Step>
</Steps>

<Warning>
  シークレットキーは作成直後にコピーしてください。Langfuse は一度しか表示しません。紛失した場合は新しいキーペアを作成する必要があります。
</Warning>

## 接続の詳細

| フィールド                     | 説明                                                  | 例                            |
| ------------------------- | --------------------------------------------------- | ---------------------------- |
| **LANGFUSE\_HOST**        | Langfuse インスタンスのベース URL — EU クラウド、US クラウド、またはセルフホスト | `https://cloud.langfuse.com` |
| **LANGFUSE\_PUBLIC\_KEY** | プロジェクトスコープの公開キー                                     | `pk-lf-...`                  |
| **LANGFUSE\_SECRET\_KEY** | プロジェクトスコープのシークレットキー                                 | `sk-lf-...`                  |

## 必要な権限

Langfuse API キーは所属するプロジェクトのアクセスを継承します。CloudThinker はキーペアを使用して、トレース、オブザベーション、メトリクス、スコア、データセット、アノテーションキュー、コメント、プロンプトの読み取り・調査ワークフローを実行します。

<Tip>
  最小権限の原則に従ってください。キーペアを CloudThinker が調査すべき単一プロジェクトにスコープし、SDK や他の統合で使用するキーとは別に保管することで、独立してローテーションまたは失効させることができます。
</Tip>

## エージェントの機能

接続後、エージェントは Langfuse プロジェクト全体の LLM オブザーバビリティデータを調査できます。

| 機能             | 説明                                   |
| -------------- | ------------------------------------ |
| **トレース**       | トレースの検索・調査、エラー・レイテンシ・モデル使用量の相関付け     |
| **オブザベーション**   | トレース内のスパン、ジェネレーション、イベントへのドリルダウン      |
| **メトリクス**      | 時間ウィンドウでの使用量、レイテンシ、コストメトリクスのクエリ      |
| **スコア**        | 評価スコアと品質シグナルのレビュー                    |
| **データセット**     | 評価とテストに使用するデータセットの調査                 |
| **アノテーションキュー** | アノテーションキューとそのアイテムのレビュー               |
| **コメント**       | トレースとオブザベーションに残されたコメントの読み取り          |
| **プロンプト**      | プロンプト監査のためのプロンプトバージョン、ラベル、最近の変更の一覧表示 |

<Note>
  CloudThinker チャット URL には `conversationId` が含まれており、これが Langfuse の `sessionId` に対応します。エージェントにチャット URL を分析させると、URL を Web ページとして取得するのではなく Langfuse を通じてセッションを解決します。
</Note>

### 接続の確認

```text theme={null}
@alex investigate recent Langfuse traces and summarize errors, latency, and model usage
```

### プロンプト例

```text theme={null}
@alex investigate recent failed Langfuse traces for production conversations, correlate errors and latency, and #recommend likely fixes
@alex inspect this CloudThinker chat URL by mapping its conversationId to a Langfuse session and summarize tool calls, model usage, and failures
@alex list active Langfuse prompts, versions, and labels, and #report prompts tied to degraded scores
```

トレースとメトリクスのクエリは時間制限があるため、結果を絞り込むためにウィンドウ（例: 「過去 1 時間」）を指定してください。

## トラブルシューティング

<Accordion title="401 Unauthorized で接続が失敗する">
  公開キーとシークレットキーが正しく、ローテーションまたは削除されていないか確認してください。両方のキーが**同じ** Langfuse プロジェクトに属しており、余分な空白なしにコピーされていることを確認してください。
</Accordion>

<Accordion title="ホストまたはリージョンが間違っている">
  データはリージョンごとに分離されており、キーペアは作成されたホストに対してのみ機能します。**LANGFUSE\_HOST** がサインインする URL と一致していることを確認してください（EU は `https://cloud.langfuse.com`、US は `https://us.cloud.langfuse.com`）。
</Accordion>

<Accordion title="すべてのリクエストが 404 を返す">
  **LANGFUSE\_HOST** に余分なパスサフィックスがあります。末尾パスなしのベース URL のみに設定してください。
</Accordion>

<Accordion title="検索結果が返らない">
  トレースとメトリクスの検索には時間範囲が必要です。エージェントに最近のウィンドウ（例: 過去 1 時間）を使用させ、必要な場合にのみ広げてください。プロジェクトがアプリケーションからトレースを積極的に受信していることを確認してください。
</Accordion>

<Accordion title="チャット URL がセッションとして分析されない">
  エージェントに `conversationId` を抽出させ、URL を直接取得するのではなく Langfuse の `sessionId` にマッピングさせてください。
</Accordion>

## セキュリティ

* **最小権限** — エージェントがユースケースに必要な権限のみを付与します。まず読み取り専用から始め、後から拡張してください。
* **デフォルトで読み取り専用** — エージェントにこの接続で変更を行わせる場合を除き、読み取り専用の認証情報を使用してください。
* **認証情報のローテーション** — 通常のスケジュールに従ってキーとトークンをローテーションしてください。接続を更新すると、CloudThinker が新しい値を自動的に取得します。
* **オフボーディング時に失効** — 接続を削除するか、チームメンバーが退職する際には、プロバイダー側で認証情報を無効化してください。

- **プロジェクトスコープのキーペア** — CloudThinker が調査する単一プロジェクトにスコープされたキーペアを使用し、アクセスの監査と独立した失効を容易にするために CloudThinker 専用のペアを作成してください。
- **正しいホスト** — クロスリージョンの失敗を避けるために、プロジェクトが存在するリージョンのホストと一致させてください。

## 関連情報

<CardGroup cols={2}>
  <Card title="SigNoz 接続" icon="https://mintcdn.com/cloudthinker/CGWam0VVP8R5KVLk/images/icons/signoz.svg?fit=max&auto=format&n=CGWam0VVP8R5KVLk&q=85&s=d08abadb07adcc41c8812b59483344e3" href="/ja/guide/connections/signoz" width="24" height="24" data-path="images/icons/signoz.svg">
    ログ、メトリクス、トレース、ダッシュボード
  </Card>

  <Card title="Datadog 接続" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/datadog.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=e8382167f2a1eb1e00971b5f4d703d48" href="/ja/guide/connections/datadog" width="24" height="24" data-path="images/icons/datadog.svg">
    ログ検索、メトリクス、監視
  </Card>
</CardGroup>