langsmith-trace

主なトピックは2つです。アプリケーションへの**トレースの追加**と、デバッグおよび分析のための**トレースのクエリ**です。Python と Javascript の両方の実装に対応しています。 環境変数

LANGSMITH_API_KEY=lsv2_pt_your_api_key_here          # REQUIRED
LANGSMITH_PROJECT=your-project-name                   # Optional: default project
LANGSMITH_WORKSPACE_ID=your-workspace-id              # Optional: for org-scoped keys

認証は必須です。LANGSMITH_API_KEY 環境変数を設定するか、CLI コマンドに --api-key フラグを渡してください（こちらを推奨します）。

langsmith trace list --project my-project --api-key $LANGSMITH_API_KEY

重要： LangSmith にクエリを実行したり、操作したりする前に、必ず環境変数または .env ファイルで LANGSMITH_PROJECT を確認してください。これにより、関連するトレースとデータがどのプロジェクトに含まれているかがわかります。LangSmith のプロジェクトを特定できない場合は、適切なものを判断してください。

CLI ツール

curl -sSL https://raw.githubusercontent.com/langchain-ai/langsmith-cli/main/scripts/install.sh | sh

<trace_langchain_oss> LangChain／LangGraph アプリでは、トレースは自動で行われます。環境変数を設定するだけです。

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>
export OPENAI_API_KEY=<your-openai-api-key>  # or your LLM provider's key

任意の変数：

• LANGSMITH_PROJECT - プロジェクト名を指定します（デフォルトは "default"）
• LANGCHAIN_CALLBACKS_BACKGROUND=false - 関数の終了前にトレースを完了させるため、サーバーレス環境で使用します（Python） </trace_langchain_oss>

<trace_other_frameworks> LangChain／LangGraph 以外の場合は、トレースコードを書く前に、references/ 内の該当するリファレンスファイルを読んでください。各リファレンスでは、そのフレームワーク固有のインストール方法、環境変数、セットアップ用スニペット、注意点を説明しています。フレームワークによってセットアップ方法は異なることが多く、誤ったパターンを選ぶと（たとえば、フレームワークがネイティブの OTel に対応しているのに @traceable を使うと）、スパンが重複したり欠落したりします。

判断の優先順位：

1. 以下に専用のリファレンスがあるフレームワーク → それを使用します
2. ネイティブの OpenTelemetry に対応しているが、専用のリファレンスがないフレームワーク → references/otel.md
3. フレームワークを使用しない場合、または未対応のフレームワーク → references/traceable.md
4. LangSmith SDK をまったく実行できない場合 → references/api.md（最終手段）

振り分け表：

トレース対象…	参照先
OpenAI／Azure OpenAI／Anthropic／その他の一般的な LLM クライアント	references/traceable.md
AutoGen	references/autogen.md
CrewAI	references/crewai.md
Google ADK	references/google-adk.md
Google Gemini（google-genai SDK を直接使用）	references/google-gemini.md
Instructor（構造化出力）	references/instructor.md
LiveKit Agents（音声 AI）	references/livekit.md
Mastra（TypeScript）	references/mastra.md
Microsoft Agent Framework	references/microsoft-agent-framework.md
Mistral	references/mistral.md
n8n（セルフホスト）	references/n8n.md
OpenAI Agents SDK	references/openai-agents-sdk.md
OpenCode	references/opencode.md
OpenAI Codex CLI	references/codex.md
Pipecat（音声 AI）	references/pipecat.md
PydanticAI	references/pydantic-ai.md
Semantic Kernel	references/semantic-kernel.md
Strands Agents	references/strands-agents.md
Temporal ワークフロー（Go／Python／TS）	references/temporal.md
Vercel AI SDK	references/vercel-ai-sdk.md
ネイティブの OTel に対応するその他のフレームワーク	references/otel.md
複数バックエンドへの OTel ファンアウト	references/otel.md（Collector のセクション）
生の REST（利用可能な SDK がない場合）	references/api.md

必要なフレームワークがここに記載されていない場合は、references/ を確認してください。新しい統合はインラインではなく、そこに追加されます。 </trace_other_frameworks>

<traces_vs_runs> トレースデータのクエリには langsmith CLI を使用します。

違いを理解することが重要です：

• トレース = 完全な実行ツリー（ルート Run とすべての子 Run）。トレースは、すべての LLM 呼び出し、ツール呼び出し、ネストされた操作を含む、エージェントの1回の完全な実行を表します。
• Run = ツリー内の単一ノード（LLM 呼び出し1回、ツール呼び出し1回など）。

通常は、まずトレースをクエリしてください。 軌跡の分析やデータセットの生成に必要な完全なコンテキストが得られ、階層構造も保持されます。 </traces_vs_runs>

<command_structure> 一貫した動作をする2つのコマンドグループがあります。

langsmith
├── trace (operations on trace trees - USE THIS FIRST)
│   ├── list    - List traces (filters apply to root run)
│   ├── get     - Get single trace with full hierarchy
│   └── export  - Export traces to JSONL files (one file per trace)
│
├── run (operations on individual runs - for specific analysis)
│   ├── list    - List runs (flat, filters apply to any run)
│   ├── get     - Get single run
│   └── export  - Export runs to single JSONL file (flat)
│
├── dataset (dataset operations)
│   ├── list    - List datasets
│   ├── get     - Get dataset details
│   ├── create  - Create empty dataset
│   ├── delete  - Delete dataset
│   ├── export  - Export dataset to file
│   └── upload  - Upload local JSON as dataset
│
├── example (example operations)
│   ├── list    - List examples in a dataset
│   ├── create  - Add example to a dataset
│   └── delete  - Delete an example
│
├── evaluator (evaluator operations)
│   ├── list    - List evaluators
│   ├── upload  - Upload evaluator
│   └── delete  - Delete evaluator
│
├── experiment (experiment operations)
│   ├── list    - List experiments
│   └── get     - Get experiment results
│
├── thread (thread operations)
│   ├── list    - List conversation threads
│   └── get     - Get thread details
│
└── project (project operations)
    └── list    - List tracing projects

主な違い：

</command_structure>

	traces *	runs *
フィルターの適用対象	ルートランのみ	一致するすべてのラン
--run-type	利用できません	利用できます
戻り値	完全な階層	フラットなリスト
エクスポート出力	ディレクトリ（トレースごとに1ファイル）	単一ファイル
</command_structure>

<querying_traces> langsmith CLI を使用してトレースをクエリします。コマンドは言語に依存しません。

# List recent traces (most common operation)
langsmith trace list --limit 10 --project my-project --api-key $LANGSMITH_API_KEY

# List traces with metadata (timing, tokens, costs)
langsmith trace list --limit 10 --include-metadata --api-key $LANGSMITH_API_KEY

# Filter traces by time
langsmith trace list --last-n-minutes 60 --api-key $LANGSMITH_API_KEY
langsmith trace list --since 2025-01-20T10:00:00Z --api-key $LANGSMITH_API_KEY

# Get specific trace with full hierarchy
langsmith trace get <trace-id> --api-key $LANGSMITH_API_KEY

# List traces and show hierarchy inline
langsmith trace list --limit 5 --show-hierarchy --api-key $LANGSMITH_API_KEY

# Export traces to JSONL (one file per trace, includes all runs)
langsmith trace export ./traces --limit 20 --full --api-key $LANGSMITH_API_KEY

# Filter traces by performance
langsmith trace list --min-latency 5.0 --limit 10 --api-key $LANGSMITH_API_KEY    # Slow traces (>= 5s)
langsmith trace list --error --last-n-minutes 60 --api-key $LANGSMITH_API_KEY     # Failed traces

# List specific run types (flat list)
langsmith run list --run-type llm --limit 20 --api-key $LANGSMITH_API_KEY

</querying_traces>

すべてのコマンドで次のフィルターを使用できます（すべて AND 条件で適用されます）。

基本フィルター：

• --trace-ids abc,def - 特定のトレースに絞り込みます
• --limit N - 結果の最大数
• --project NAME - プロジェクト名
• --last-n-minutes N - 時間フィルター
• --since TIMESTAMP - 時間フィルター（ISO 形式）
• --error / --no-error - エラー状態
• --name PATTERN - 名前に含まれる文字列（大文字と小文字を区別しません）

パフォーマンスフィルター：

• --min-latency SECONDS - 最小レイテンシ（例：5秒以上なら 5）
• --max-latency SECONDS - 最大レイテンシ
• --min-tokens N - 合計トークン数の最小値
• --tags tag1,tag2 - これらのタグのいずれかを持つもの

高度なフィルター：

• --filter QUERY - 複雑なケース（フィードバック、メタデータなど）向けの LangSmith 生フィルタークエリ

# Filter traces by feedback score using raw LangSmith query
langsmith trace list --filter 'and(eq(feedback_key, "correctness"), gte(feedback_score, 0.8))' --api-key $LANGSMITH_API_KEY

<export_format> エクスポートでは、次のフィールドを含む .jsonl ファイル（1行につき1ラン）が作成されます。

{"run_id": "...", "trace_id": "...", "name": "...", "run_type": "...", "parent_run_id": "...", "inputs": {...}, "outputs": {...}}

入力／出力を含めるには、--include-io または --full を使用します（データセットの生成に必要です）。 </export_format>

- **まずはトレースから始めましょう** — トレースには、軌跡やデータセットの生成に必要な完全なコンテキストが含まれています - データセット用の一括データには `traces export --full` を使用します - 異なるプロジェクトのデータが混在しないよう、必ず `--project` を指定します - 一時エクスポートには `/tmp` を使用します - パフォーマンス／コストの分析には `--include-metadata` を含めます - ファイルを結合します：`cat ./traces/*.jsonl > all.jsonl`