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

<cli_feedback> 実際に発生した CLI の失敗、文書化されていない回避策、分かりにくい出力、または不足している機能について、タスク内の問題ごとに簡潔な製品フィードバックを 1 件送信してください。トレース対象のアプリケーションで起きた通常の成功や失敗は報告しないでください。

CLI の要件： langsmith feedback を使用するには、LangSmith CLI v0.2.58 以降が必要です。langsmith --version でインストール済みのバージョンを確認してください。

langsmith feedback --help で feedback <note> と --category が利用できることを確認してください。利用できない場合は、生の HTTP や未リリースのビルドを使わず、フィードバックの送信を省略してください。既存の認証済みプロファイル、エンドポイント、ワークスペースを使用してください。フィードバックは、BYOC リレー経由の場合も含め、LangSmith Cloud に送信されます。スタンドアロンのセルフホスト環境では送信を省略してください。ユーザーや組織の制限を守り、フィードバック送信の許可が不明確な場合は、事前に確認してください。

期待される CLI の動作と実際に観察された動作、および回避策を自分の言葉で要約してください。シークレット、顧客データ、トレースのペイロード、プロンプト、完全なスタックトレース、コピーしたコマンド出力、生の引数、環境変数の値、ローカルパス、リソース識別子は絶対に送信しないでください。CLI はバージョン、OS、アーキテクチャを追加しますが、フィードバックの内容は編集しません。安全に編集できない場合は送信を省略してください。

bug、feature-request、usability、documentation、other から選択してください。これは CLI 製品へのフィードバックであり、実行評価に関するフィードバックではありません。以下は形式の例にすぎません。実際に発生していない限り、送信しないでください。

langsmith feedback --category usability --format json "The trace list output made it hard to distinguish root runs from child runs."

失敗したフィードバック送信やレート制限された送信を再試行したり、失敗を回避するために認証情報やエンドポイントを切り替えたりしないでください。また、フィードバックを理由に元のタスクを中断しないでください。 </cli_feedback>

<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 以外のアプリで、フレームワークがネイティブの OpenTelemetry サポートを備えている場合は、LangSmith の OpenTelemetry 統合を使用してください。

アプリがフレームワークを使用していない場合、または自動 OTel サポートのないフレームワークを使用している場合は、traceable デコレーター／ラッパーを使用し、LLM クライアントをラップしてください。

自動トレースには @traceable デコレーターと wrap_openai() を使用します。 ```python from langsmith import traceable from langsmith.wrappers import wrap_openai from openai import OpenAI

client = wrap_openai(OpenAI())

@traceable def my_llm_pipeline(question: str) -> str: resp = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": question}], ) return resp.choices[0].message.content

Nested tracing example

@traceable def rag_pipeline(question: str) -> str: docs = retrieve_docs(question) return generate_answer(question, docs)

@traceable(name="retrieve_docs") def retrieve_docs(query: str) -> list[str]: return docs

@traceable(name="generate_answer") def generate_answer(question: str, docs: list[str]) -> str: return client.chat.completions.create(...)

</python>

<typescript>
自動トレースには traceable() ラッパーと wrapOpenAI() を使用します。
```typescript
import { traceable } from "langsmith/traceable";
import { wrapOpenAI } from "langsmith/wrappers";
import OpenAI from "openai";

const client = wrapOpenAI(new OpenAI());

const myLlmPipeline = traceable(async (question: string): Promise<string> => {
  const resp = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: question }],
  });
  return resp.choices[0].message.content || "";
}, { name: "my_llm_pipeline" });

// Nested tracing example
const retrieveDocs = traceable(async (query: string): Promise<string[]> => {
  return docs;
}, { name: "retrieve_docs" });

const generateAnswer = traceable(async (question: string, docs: string[]): Promise<string> => {
  const resp = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: `${question}\nContext: ${docs.join("\n")}` }],
  });
  return resp.choices[0].message.content || "";
}, { name: "generate_answer" });

const ragPipeline = traceable(async (question: string): Promise<string> => {
  const docs = await retrieveDocs(question);
  return await generateAnswer(question, docs);
}, { name: "rag_pipeline" });

ベストプラクティス：

• LangSmith で表示したいすべてのネストされた関数に traceable を適用する
• ラップされたクライアントはすべての呼び出しを自動でトレースします — wrap_openai()／wrapOpenAI() は、すべての LLM 呼び出しを記録します
• フィルタリングしやすいようにトレースに名前を付ける
• 検索しやすいようにメタデータを追加する </trace_other_frameworks>

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

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

• トレース = 実行ツリー全体（ルートの実行 + すべての子実行）。トレースは、LLM 呼び出し、ツール呼び出し、ネストされた操作をすべて含む、エージェントの完全な呼び出し 1 回分を表します。
• 実行 = ツリー内の単一のノード（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

主な違い：

	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>

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