Observability（可観測性）

mixseek-coreは4つの出力・観測方式を提供します。

4つの出力方式

出力方式	用途	データ保存	デフォルト
コンソール	リアルタイム確認	なし	有効
ファイル	事後分析・デバッグ	`$WORKSPACE/logs/`	有効
`--save-db`	永続化・SQL分析	DuckDB（ローカル）	無効
`--logfire`	リアルタイム観測	Logfireクラウド/OTel	無効

これらは併用可能です：

mixseek team "..." --config team.toml --save-db --logfire

アーキテクチャ

mixseek-coreのロギングは2つのパスで統合されています。

┌─────────────────────────────────────────────────────────────────┐
│                    TWO INTEGRATION PATHS                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Path 1: Standard Logging → Logfire + console* + file          │
│  ─────────────────────────────────────────────────────         │
│  logging.info("...") → LogfireLoggingHandler → Logfire Cloud   │
│                     → StreamHandler → console*                  │
│                     → FileHandler → file                        │
│                                                                 │
│  Path 2: Logfire Spans → console + file                        │
│  ─────────────────────────────────────────────────────         │
│  logfire.info("...")           ─┐                              │
│  Pydantic AI instrumentation   ─┼→ logfire.configure()         │
│  OpenTelemetry spans           ─┘     └→ ConsoleOptions        │
│                                            └→ TeeWriter        │
│                                                 ├→ console     │
│                                                 └→ file        │
│                                                                 │
│  * Logfire有効時、Path 1のコンソール出力は自動的に無効化       │
│    （Path 2のConsoleOptionsが代替するため重複を防止）          │
└─────────────────────────────────────────────────────────────────┘

Path 1: 標準ロギング

Pythonの標準loggingモジュールを使用したログ出力です。既存のコードで使用しているlogging.info()、logging.warning()等がそのまま動作します。

コンソール出力: StreamHandler経由で即時表示（Logfire無効時のみ）
ファイル出力: FileHandler経由で$WORKSPACE/logs/mixseek.logに保存
Logfire送信: LogfireLoggingHandler経由でLogfireクラウドに送信（--logfire有効時）

Note

Logfire有効時のコンソール出力: --logfireフラグを使用すると、標準ロギングのコンソール出力（StreamHandler）は自動的に無効化されます。代わりに、Path 2のLogfire ConsoleOptionsがコンソール出力を担当します。これにより、同じログメッセージが重複して表示されることを防ぎます。ファイル出力は引き続き両方のパスで有効です。

Path 2: Logfireスパン出力

Pydantic AI instrumentationやOpenTelemetryスパンのローカル出力です。Agent実行トレース等の詳細な観測データをコンソールやファイルで確認できます。

ConsoleOptions: Logfireスパンをコンソール/ファイルに出力
TeeWriter: 複数出力先への同時書き込み

標準ロギング設定

CLIフラグ

# デフォルト: コンソール + ファイル出力（両方有効）
mixseek team "..." --config team.toml

# Logfireクラウドも追加
mixseek team "..." --config team.toml --logfire

# コンソール出力を無効化（ファイルのみ）
mixseek team "..." --config team.toml --no-log-console

# ファイル出力を無効化（コンソールのみ）
mixseek team "..." --config team.toml --no-log-file

# ログレベルを指定（debug/info/warning/error）
mixseek team "..." --config team.toml --log-level debug

フラグ	説明	デフォルト
`--log-level LEVEL`	グローバルログレベル	`info`
`--no-log-console`	コンソール出力を無効化	有効
`--no-log-file`	ファイル出力を無効化	有効
`--logfire`	Logfireクラウド送信を有効化	無効

環境変数

環境変数	説明	デフォルト
`MIXSEEK_LOG_LEVEL`	グローバルログレベル（debug/info/warning/error）	`info`
`MIXSEEK_LOG_CONSOLE`	コンソール出力有効化（true/false）	`true`
`MIXSEEK_LOG_FILE`	ファイル出力有効化（true/false）	`true`

# 環境変数での設定例
export MIXSEEK_LOG_LEVEL=debug
export MIXSEEK_LOG_CONSOLE=true
export MIXSEEK_LOG_FILE=false  # ファイル出力無効

mixseek team "..." --config team.toml

TOML設定

[logging]
log_level = "info"        # グローバルログレベル
console_output = true     # コンソール出力
file_output = true        # ファイル出力
log_file_path = "logs/mixseek.log"  # ログファイルパス（オプション）

優先順位

設定は以下の優先順位で適用されます：

CLIフラグ（--log-level等）
環境変数（MIXSEEK_LOG_*）
TOML設定ファイル
デフォルト値

ログファイルの場所

ログファイルは$MIXSEEK_WORKSPACE/logs/ディレクトリに保存されます：

標準ログ: $MIXSEEK_WORKSPACE/logs/mixseek.log
Logfireスパン: $MIXSEEK_WORKSPACE/logs/logfire.log

Logfire統合

Pydantic Logfireは、Pydantic AIのビルトインサポートを持つObservabilityプラットフォームです。mixseek-coreのLeader AgentとMember Agentの実行をリアルタイムで可視化できます。

特徴

Agent実行フローの可視化（Leader → Member Agent delegationの階層）
メッセージ履歴の自動キャプチャ（system/user/assistant/tool_call/tool_return）
トークン使用量とコストの自動集計
実行時間の詳細分析
HTTPリクエスト/レスポンスのキャプチャ（デバッグモード）
OpenTelemetry準拠（任意のOTelバックエンドで使用可能）

セットアップ

1. Logfireのインストール

uv sync --extra logfire

または開発環境全体をインストール：

uv sync --group dev

2. Logfire認証

uv run logfire auth

ブラウザが開き、Logfireアカウントにサインインします。

3. プロジェクト作成

uv run logfire projects new

プロジェクト名を入力すると、.logfireディレクトリが作成されます。

既存のプロジェクトを使用する場合：

uv run logfire projects use

使用方法

mixseek team での使用

開発・テスト用の単一チーム実行コマンド。

mixseek team "分析してください" --config team.toml --logfire

これで以下が実行されます：

Logfireが自動的に有効化（fullモード）
Pydantic AI instrumentationが設定される
Agent実行のトレースがLogfireに送信される
Logfire UIでリアルタイム確認可能（https://logfire.pydantic.dev/）

mixseek exec での使用

本番環境想定の複数チーム並列実行コマンド。

mixseek exec "分析してください" --config orchestrator.toml --logfire

特徴:

複数チームが並列実行され、それぞれのトレースが階層的に記録される
Orchestrator → RoundController → Leader Agent → Member Agentsの階層構造を可視化
execution_idでDuckDBとの紐付けが可能

トレース階層構造:

📊 orchestrator.execute [10.2s] (execution_id: abc-123)
  ├─ 📊 round_controller.run_round (team_1) [4.1s]
  │   └─ 📊 agent run (leader_agent) [3.8s]
  │       ├─ 💬 request (user prompt)
  │       ├─ 🔧 delegate_to_researcher [2.5s]
  │       │   └─ 📊 agent run (web-search-agent)
  │       └─ 💬 final response
  ├─ 📊 round_controller.run_round (team_2) [5.3s]
  │   └─ 📊 agent run (leader_agent) [5.0s]
  └─ 📊 round_controller.run_round (team_3) [3.9s]
      └─ 📊 agent run (leader_agent) [3.6s]

mixseek ui での使用

Streamlitベースのウェブインターフェース。Logfireと併用することで、UI上での実行をリアルタイムで観測できます。

# Full mode（すべてキャプチャ）- 開発環境推奨
mixseek ui --logfire

# Metadata only mode（本番推奨）- プロンプト/応答を除外
mixseek ui --logfire-metadata

# Full + HTTP capture（デバッグ用）
mixseek ui --logfire-http

特徴:

UI上で実行したオーケストレーションのトレースをLogfireで確認
ブラウザからの実行でもCLIコマンドと同等の観測機能
サイドバーにLogfire状態表示（有効/無効/エラー）
環境変数でも制御可能（LOGFIRE_ENABLED=1）

確認方法:

mixseek ui --logfire でStreamlit起動
UIのサイドバーに「Logfire enabled (full)」表示を確認
UI上でタスクを実行
Logfire UIでトレースを確認（https://logfire.pydantic.dev/）

詳細はui-guide.mdを参照してください。

記録される情報:

Orchestratorレベル: execution_id, team_count, best_team_id, best_score, execution_status
RoundControllerレベル: team_id, team_name, round_number, evaluation_score, execution_time
Agentレベル: メッセージ履歴、トークン使用量、コスト（Pydantic AI自動記録）

DuckDBとの紐付け:

import duckdb

# Logfireから取得したexecution_id
execution_id = "abc-123"

# DuckDBで同じexecution_idのデータを取得
conn = duckdb.connect("mixseek.db")
result = conn.execute("""
    SELECT * FROM execution_summary
    WHERE execution_id = ?
""", [execution_id]).fetchall()

# Leader boardも取得可能
leaderboard = conn.execute("""
    SELECT * FROM leader_board
    WHERE execution_id = ?
    ORDER BY evaluation_score DESC
""", [execution_id]).fetchall()

プライバシーモード:

# 本番環境推奨: メタデータのみ
mixseek exec "..." --config orchestrator.toml --logfire-metadata

# デバッグモード: HTTP capture有効
mixseek exec "..." --config orchestrator.toml --logfire-http

プライバシーモード

full（デフォルト）

すべてのコンテンツをキャプチャします（開発・デバッグ推奨）。

mixseek team "..." --config team.toml --logfire

含まれる内容:

✅ System instructions
✅ User prompts
✅ Assistant responses
✅ Tool calls（引数含む）
✅ Tool returns
✅ トークン使用量
✅ 実行時間
✅ コスト

metadata（本番推奨）

メトリクスのみをキャプチャし、プロンプト/応答は除外します。

mixseek team "..." --config team.toml --logfire-metadata

含まれる内容:

✅ トークン使用量
✅ 実行時間
✅ コスト
✅ Agent名
❌ System instructions（除外）
❌ User prompts（除外）
❌ Assistant responses（除外）

ユースケース: プライバシー要件が厳しい本番環境、顧客データを含むプロンプト

http（デバッグモード）

fullに加えて、HTTPリクエスト/レスポンスもキャプチャします。

mixseek team "..." --config team.toml --logfire-http

含まれる内容:

✅ fullモードの全内容
✅ HTTPリクエストヘッダー
✅ HTTPリクエストボディ（実際のLLM APIリクエスト）
✅ HTTPレスポンスヘッダー
✅ HTTPレスポンスボディ（実際のLLM APIレスポンス）

ユースケース: プロンプトエンジニアリング、APIエラーのデバッグ、レイテンシ分析

disabled（環境変数のみ）

Logfireを初期化するが、Pydantic AI instrumentationは実行しません。

注意: このモードは環境変数またはTOML設定でのみ使用でき、CLIフラグでは指定できません。 CLIでLogfireを無効化するには、--logfireフラグを省略してください。

# 環境変数での使用
export LOGFIRE_ENABLED=1
export LOGFIRE_PRIVACY_MODE=disabled
mixseek team "..." --config team.toml

含まれる内容:

✅ OpenTelemetryの基本トレース
❌ Pydantic AI instrumentation（実行されない）
❌ Agent実行の詳細

ユースケース: 非常にレアなケース。通常は--logfireを省略してLogfireを完全無効化するのが推奨です。

Logfire UIでの確認

1. Live View（リアルタイム）

Logfire UIの「Live」タブで、実行中のtraceをリアルタイムで確認できます。

実行が完了すると、以下のような階層構造が表示されます：

📊 agent run (leader_agent) [4.5s]
  ├─ 💬 request (user prompt)
  ├─ 💬 response (tool call)
  │
  ├─ 🔧 delegate_to_researcher [3.2s]
  │   └─ 📊 agent run (web-search-agent) [3.2s]
  │       ├─ 💬 request
  │       ├─ 💬 response (tool call)
  │       ├─ 🔧 web_search [2.3s]
  │       │   └─ 🌐 HTTP request to Vertex AI (httpモード)
  │       └─ 💬 final response
  │
  └─ 💬 final response

2. Generation Tab（メッセージ詳細）

Spanをクリックして「Generation」タブを開くと、会話履歴が見やすく表示されます：

💬 system
  あなたは研究チームのリーダーエージェントです...

💬 user
  最新の情報を検索して日本の内閣総理大臣を教えてください

💬 assistant
  このタスクは最新情報を必要とするので、delegate_to_researcherを使用します。

  🔧 tool_call: delegate_to_researcher
     args: {"task": "日本の内閣総理大臣の最新情報を検索"}

📦 tool_return
  2025年10月21日、高市早苗氏が第104代内閣総理大臣に指名されました...

💬 assistant
  2025年10月21日、高市早苗氏が...

3. Details Tab（メトリクス）

Input tokens: 457
Output tokens: 110
Total cost: $0.000172
Duration: 4.519s
Model: gemini-2.5-flash-lite

4. Explore（SQL分析）

Logfire UIの「Explore」タブで、SQLクエリによる集計・分析が可能です：

-- トークン使用量の推移
SELECT
  DATE_TRUNC('hour', start_timestamp) as hour,
  SUM(gen_ai_usage_input_tokens) as total_input,
  SUM(gen_ai_usage_output_tokens) as total_output
FROM records
WHERE span_name = 'agent run'
GROUP BY hour
ORDER BY hour DESC;

-- Agent別の実行時間
SELECT
  attributes->>'agent_name' as agent,
  AVG(duration) as avg_duration,
  COUNT(*) as runs
FROM records
WHERE span_name = 'agent run'
GROUP BY agent;

-- コストの集計
SELECT
  DATE(start_timestamp) as date,
  SUM((attributes->'logfire.metrics'->'operation.cost'->>'total')::float) as daily_cost
FROM records
WHERE span_name = 'agent run'
GROUP BY date
ORDER BY date DESC;

Logfire環境変数

Logfireの設定は環境変数で制御できます。

Note

標準ロギング（コンソール/ファイル出力）の環境変数については、標準ロギング設定セクションを参照してください。

# Logfire有効化
export LOGFIRE_ENABLED=1
export LOGFIRE_PRIVACY_MODE=full

mixseek team "..." --config team.toml
# --logfireフラグなしでもLogfireが有効化される

Logfire環境変数一覧

環境変数	説明	デフォルト
`LOGFIRE_ENABLED`	“1”で有効化	なし（無効）
`LOGFIRE_PRIVACY_MODE`	“full”, “metadata_only”, “disabled”	“metadata_only”
`LOGFIRE_CAPTURE_HTTP`	“1”でHTTPキャプチャ	なし（無効）
`LOGFIRE_PROJECT`	プロジェクト名	.logfireから読み込み
`LOGFIRE_SEND_TO_LOGFIRE`	“1”でLogfireクラウドへ送信	“1”
`LOGFIRE_TOKEN`	Logfire認証トークン（本番環境）	.logfireから読み込み

環境変数の詳細

プロジェクト名の設定（オプション）

環境変数 LOGFIRE_PROJECT でプロジェクト名を明示的に指定できます。

# 環境変数で設定
export LOGFIRE_PROJECT="my-project"

Note

LOGFIRE_PROJECT は通常、.logfire/ ディレクトリの設定またはトークンから自動的に決定されるため、明示的な指定は必須ではありません。複数プロジェクトがある場合や明示的に切り替えたい場合に使用します。

本番環境での認証

開発環境では uv run logfire auth で認証情報が .logfire/ ディレクトリに保存されますが、本番環境（CI/CD、コンテナなど）では環境変数 LOGFIRE_TOKEN を使用します。

# 本番環境での最小構成
export LOGFIRE_TOKEN="your-logfire-token-here"
export LOGFIRE_PRIVACY_MODE="metadata_only"
mixseek team "..." --config team.toml --logfire

# プロジェクトを明示的に指定する場合（推奨）
export LOGFIRE_TOKEN="your-logfire-token-here"
export LOGFIRE_PROJECT="production-project"
export LOGFIRE_PRIVACY_MODE="metadata_only"
mixseek team "..." --config team.toml --logfire

Important

認証に関する重要事項

LOGFIRE_TOKEN はLogfireライブラリが自動的に読み取ります
トークンは通常、特定のプロジェクトに紐付いています
LOGFIRE_PROJECT を省略した場合、トークンのデフォルトプロジェクトが使用されます
複数プロジェクトがある場合は LOGFIRE_PROJECT の明示的な指定を推奨します

トークンの取得方法

Logfire UIから取得できます：

Logfire Dashboard にアクセス
Settings → Write Tokens
“Create token” をクリック
トークンをコピーして LOGFIRE_TOKEN に設定

Logfire TOML設定

$MIXSEEK_WORKSPACE/logfire.tomlでLogfire設定を管理できます：

[logfire]
enabled = true
privacy_mode = "metadata_only"
capture_http = false
project_name = "mixseek-prod"
send_to_logfire = true
# ローカル出力設定（Path 2）
console_output = true
file_output = true

Note

標準ロギングのTOML設定については、標準ロギング設定セクションを参照してください。

Logfire設定の優先順位:

CLIフラグ（--logfire）
環境変数（LOGFIRE_ENABLED等）
TOML設定ファイル
デフォルト値（無効）

既存の出力方式との併用

DuckDBとの併用

mixseek team "..." --config team.toml --save-db --logfire

DuckDB: 永続化、後からSQL分析
Logfire: リアルタイム可視化、デバッグ

JSON出力との併用

mixseek team "..." --config team.toml --output-format json --logfire > result.json

JSON: プログラム的にアクセス、パイプライン統合
Logfire: 同時にリアルタイム観測

3つ全て併用

mixseek team "..." --config team.toml --output-format json --save-db --logfire > result.json

最も包括的な記録方法です。

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

Logfire not installed

ImportError: Logfire not installed. Install with: uv sync --extra logfire

解決方法:

uv sync --extra logfire

Logfire initialization failed

WARNING: Logfire initialization failed: ...

原因:

Logfire認証が未完了
.logfireディレクトリがない
プロジェクトが設定されていない

解決方法:

uv run logfire auth
uv run logfire projects new

データが表示されない

確認事項:

Logfireが有効化されているか確認

mixseek team "..." --config team.toml --logfire
# "✓ Logfire observability enabled"メッセージが表示される

正しいプロジェクトが選択されているか確認
```
cat .logfire/logfire_credentials.json
```
Logfire UIのプロジェクトが正しいか確認
- UIの左上でプロジェクト名を確認

プライバシー要件

センシティブなデータを送信したくない場合：

# メタデータのみ
mixseek team "..." --config team.toml --logfire metadata

または完全にLogfireを無効化：

mixseek team "..." --config team.toml
# --logfireフラグなし

OpenTelemetry互換性

Logfireクラウドの代わりに、任意のOpenTelemetryバックエンドを使用できます。

代替バックエンドの設定

# 環境変数で代替エンドポイントを指定
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export LOGFIRE_SEND_TO_LOGFIRE=0

mixseek team "..." --config team.toml --logfire

サポート済みバックエンド

Langfuse（LLM特化の観測）
W&B Weave（ML実験トラッキング）
Arize（プロダクションモニタリング）
Grafana Tempo（セルフホスト）
その他のOpenTelemetry準拠バックエンド

詳細はPydantic AI Logfireドキュメントを参照してください。

ベストプラクティス

開発環境

# フルモードで詳細確認
mixseek team "..." --config team.toml --logfire full

ステージング環境

# メタデータのみ（プライバシー保護）
mixseek team "..." --config team.toml --logfire metadata

本番環境

# Logfire無効（最速）
mixseek team "..." --config team.toml

# または選択的に有効化
mixseek team "..." --config team.toml --logfire metadata

デバッグ時

# HTTPキャプチャでプロンプト詳細確認
mixseek team "..." --config team.toml --logfire http

コスト管理

Logfire無料ティア

月間100万spans
データ保持: 30日間

小規模チームには十分です。

コスト最適化戦略

開発環境のみ有効化: 本番環境では--logfireなし
メタデータモード: --logfire metadataでデータ量削減
選択的実行: 重要な実行のみLogfire有効化

Observability（可観測性）

4つの出力方式

アーキテクチャ

Path 1: 標準ロギング

Path 2: Logfireスパン出力

標準ロギング設定

CLIフラグ

環境変数

TOML設定

優先順位

ログファイルの場所

Logfire統合

特徴

セットアップ

1. Logfireのインストール

2. Logfire認証

3. プロジェクト作成

使用方法

mixseek team での使用

mixseek exec での使用

mixseek ui での使用

プライバシーモード

full（デフォルト）

metadata（本番推奨）

http（デバッグモード）

disabled（環境変数のみ）

Logfire UIでの確認

1. Live View（リアルタイム）

2. Generation Tab（メッセージ詳細）

3. Details Tab（メトリクス）

4. Explore（SQL分析）

Logfire環境変数

Logfire環境変数一覧

環境変数の詳細

Logfire TOML設定

既存の出力方式との併用

DuckDBとの併用

JSON出力との併用

3つ全て併用

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

Logfire not installed

Logfire initialization failed

データが表示されない

プライバシー要件

OpenTelemetry互換性

代替バックエンドの設定

サポート済みバックエンド

ベストプラクティス

開発環境

ステージング環境

本番環境

デバッグ時

コスト管理

Logfire無料ティア

コスト最適化戦略

参考資料