トレース検索API - Refinire
Author: kitfactory
Description: 複数のLLMプロバイダーに対応した統一インターフェースライブラリ

コンテンツにスキップ

# トレース検索API

## 概要

Agents SDK Modelsのトレース検索機能は、フロー名やエージェント名でトレースを検索し、実行履歴を追跡・分析するための包括的なAPIを提供します。

## 主要クラス

### TraceRegistry

トレースの保存・検索を管理するメインクラスです。

メソッド | 説明 | 戻り値
--- | --- | ---
`register_trace()` | 新しいトレースを登録 | None
`search_by_flow_name()` | フロー名でトレースを検索 | List[TraceMetadata]
`search_by_agent_name()` | エージェント名でトレースを検索 | List[TraceMetadata]
`search_by_tags()` | タグでトレースを検索 | List[TraceMetadata]
`search_by_status()` | ステータスでトレースを検索 | List[TraceMetadata]
`search_by_time_range()` | 時間範囲でトレースを検索 | List[TraceMetadata]
`complex_search()` | 複数条件による複合検索 | List[TraceMetadata]
`get_statistics()` | トレース統計を取得 | Dict[str, Any]
`export_traces()` | トレースをファイルにエクスポート | None
`import_traces()` | ファイルからトレースをインポート | int

### TraceMetadata

トレースのメタデータを表現するデータクラスです。

フィールド | 型 | 説明
--- | --- | ---
`trace_id` | str | ユニークなトレース識別子
`flow_name` | Optional[str] | フロー名
`flow_id` | Optional[str] | フローインスタンスID
`agent_names` | List[str] | 使用されたエージェント名のリスト
`start_time` | datetime | トレース開始時刻
`end_time` | Optional[datetime] | トレース終了時刻
`status` | str | トレースステータス (running, completed, error)
`total_spans` | int | トレース内のスパン数
`error_count` | int | エラースパン数
`duration_seconds` | Optional[float] | 総実行時間
`tags` | Dict[str, Any] | カスタムタグ
`artifacts` | Dict[str, Any] | トレース成果物

## 検索メソッド詳細

### フロー名による検索

    # 完全一致検索
    exact_matches = registry.search_by_flow_name("customer_support_workflow", exact_match=True)

    # 部分一致検索
    partial_matches = registry.search_by_flow_name("support", exact_match=False)

パラメータ: - `flow_name` (str): 検索するフロー名 - `exact_match` (bool): 完全一致を使用するか（デフォルト: False）

### エージェント名による検索

    # 特定のエージェントを検索
    agent_traces = registry.search_by_agent_name("SupportAgent", exact_match=True)

    # エージェントパターンを検索
    pattern_traces = registry.search_by_agent_name("Agent", exact_match=False)

パラメータ: - `agent_name` (str): 検索するエージェント名 - `exact_match` (bool): 完全一致を使用するか（デフォルト: False）

### タグによる検索

    # すべてのタグがマッチする必要がある
    all_match = registry.search_by_tags({"env": "prod", "version": "1.0"}, match_all=True)

    # いずれかのタグがマッチすればよい
    any_match = registry.search_by_tags({"priority": "high"}, match_all=False)

パラメータ: - `tags` (Dict[str, Any]): 検索するタグ - `match_all` (bool): すべてのタグがマッチする必要があるか（デフォルト: True）

### 時間範囲による検索

    from datetime import datetime, timedelta

    # 過去1時間のトレース
    recent = registry.search_by_time_range(
        start_time=datetime.now() - timedelta(hours=1)
    )

    # 特定の期間のトレース
    period = registry.search_by_time_range(
        start_time=datetime(2024, 1, 1),
        end_time=datetime(2024, 1, 31)
    )

パラメータ: - `start_time` (Optional[datetime]): 検索開始時刻 - `end_time` (Optional[datetime]): 検索終了時刻

### 複合検索

    # 複数条件による検索
    results = registry.complex_search(
        flow_name="support",           # フロー名に"support"を含む
        agent_name="Agent",            # エージェント名に"Agent"を含む
        status="completed",            # ステータスが"completed"
        tags={"priority": "high"},     # タグに"priority": "high"を含む
        start_time=datetime.now() - timedelta(days=7),  # 過去7日間
        max_results=10                 # 最大10件
    )

パラメータ: - `flow_name` (Optional[str]): フロー名フィルタ - `agent_name` (Optional[str]): エージェント名フィルタ - `tags` (Optional[Dict[str, Any]]): タグフィルタ - `status` (Optional[str]): ステータスフィルタ - `start_time` (Optional[datetime]): 開始時刻フィルタ - `end_time` (Optional[datetime]): 終了時刻フィルタ - `max_results` (Optional[int]): 最大結果数

## 統計情報

    stats = registry.get_statistics()
    print(f"総トレース数: {stats['total_traces']}")
    print(f"ユニークフロー名数: {stats['unique_flow_names']}")
    print(f"ユニークエージェント名数: {stats['unique_agent_names']}")
    print(f"総スパン数: {stats['total_spans']}")
    print(f"総エラー数: {stats['total_errors']}")
    print(f"平均実行時間: {stats['average_duration_seconds']:.2f}秒")

戻り値の構造:

    {
        "total_traces": int,
        "status_distribution": Dict[str, int],
        "unique_flow_names": int,
        "unique_agent_names": int,
        "total_spans": int,
        "total_errors": int,
        "average_duration_seconds": float,
        "flow_names": List[str],
        "agent_names": List[str]
    }

## エクスポート・インポート

### エクスポート

    # JSONファイルにエクスポート
    registry.export_traces("traces_backup.json", format="json")

### インポート

    # JSONファイルからインポート
    imported_count = registry.import_traces("traces_backup.json", format="json")
    print(f"{imported_count}件のトレースをインポートしました")

## グローバルレジストリ

    from agents_sdk_models import get_global_registry, set_global_registry

    # グローバルレジストリを取得
    registry = get_global_registry()

    # カスタムレジストリを設定
    custom_registry = TraceRegistry(storage_path="custom_traces.json")
    set_global_registry(custom_registry)

## Flow統合

Flowクラスは自動的にトレースレジストリと統合されます：

    # フロー作成時に自動的にトレースが登録される
    flow = Flow(
        name="my_workflow",
        steps=my_steps,
        start="first_step"
    )

    # フロー実行後、トレースが更新される
    await flow.run("input_data")

    # 検索で見つけることができる
    traces = registry.search_by_flow_name("my_workflow")

## 使用例

### 1. 特定エージェントを使用したフローの検索

    # SupportAgentを使用したすべてのフローを検索
    support_traces = registry.search_by_agent_name("SupportAgent")
    for trace in support_traces:
        print(f"フロー: {trace.flow_name}, 開始時刻: {trace.start_time}")

### 2. エラーが発生したフローの分析

    # エラーが発生したトレースを検索
    error_traces = registry.search_by_status("error")
    for trace in error_traces:
        error_step = trace.tags.get("error_step", "不明")
        error_type = trace.tags.get("error_type", "不明")
        print(f"エラーフロー: {trace.flow_name}, ステップ: {error_step}, エラー: {error_type}")

### 3. パフォーマンス分析

    # 完了したトレースの実行時間を分析
    completed_traces = registry.search_by_status("completed")
    durations = [t.duration_seconds for t in completed_traces if t.duration_seconds]
    if durations:
        avg_duration = sum(durations) / len(durations)
        print(f"平均実行時間: {avg_duration:.2f}秒")

### 4. 最近のアクティビティ監視

    # 過去1時間のアクティビティを監視
    recent_traces = registry.get_recent_traces(hours=1)
    print(f"過去1時間で{len(recent_traces)}件のフローが実行されました")

    # ステータス別の分布
    status_counts = {}
    for trace in recent_traces:
        status_counts[trace.status] = status_counts.get(trace.status, 0) + 1
    print("ステータス分布:", status_counts)

## ベストプラクティス

1. フロー名の命名規則: 検索しやすいように一貫した命名規則を使用する
2. エージェント名の標準化: エージェント名に一貫したパターンを使用する
3. タグの活用: 環境、バージョン、優先度などの情報をタグで管理する
4. 定期的なクリーンアップ: 古いトレースを定期的に削除する
5. エクスポート: 重要なトレースデータは定期的にエクスポートしてバックアップする

## 注意事項

- トレースレジストリはメモリ内に保存されるため、アプリケーション再起動時にはデータが失われます
- 永続化が必要な場合は、`storage_path`を指定してTraceRegistryを作成してください
- 大量のトレースを扱う場合は、定期的なクリーンアップを実施してください
- 検索結果は開始時刻の降順（新しい順）でソートされます