langsmith-trace

LangSmith トレース

主なトピックは、アプリケーションへのトレースの追加と、デバッグおよび分析のためのトレースのクエリです。

セットアップ

環境変数

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

依存関係

pip install langsmith click rich python-dotenv

アプリケーションへのトレースの追加

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 - サーバーレス環境で使用すると、関数の終了前にトレースが完了します

LangChain／LangGraph 以外のアプリ

まずコードベースを確認してください： OpenTelemetry を使用している場合は、OTel 統合を優先してください（https://docs.langchain.com/langsmith/trace-with-opentelemetry）。Vercel AI SDK、LlamaIndex、Instructor、DSPy、または LiteLLM を使用している場合は、https://docs.langchain.com/langsmith/integrations でネイティブ統合を確認してください。

統合を使用していない場合は、@traceable デコレーターを使用し、LLM クライアントをラップしてください。

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

トレースは LangSmith ワークスペースに自動的に表示されます。

ベストプラクティス

• LangSmith で表示したいすべてのネストされた関数に @traceable を適用します。装飾された関数のみが、トレース階層内に個別のスパンとして表示されます。
• ラップされたクライアントはすべての呼び出しを自動的にトレースします — wrap_openai() は、追加のデコレーターなしですべての LLM 呼び出しを自動的に記録します。
• フィルタリングしやすいように、トレースに名前を付けます：@traceable(name="retrieve_docs") または traceable(myFunc, { name: "retrieve_docs" })
• 検索しやすいように、メタデータを追加します：@traceable(metadata={"user_id": "123", "feature": "chat"})

# Example: nested tracing
@traceable
def rag_pipeline(question: str) -> str:
    docs = retrieve_docs(question)  # traced if @traceable applied
    return generate_answer(question, docs)  # traced if @traceable applied

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

@traceable(name="generate_answer")
def generate_answer(question: str, docs: list[str]) -> str:
    # LLM calls via wrapped client are auto-traced
    return client.chat.completions.create(...)

---

トレースのクエリ

以下のスクリプトを使って、LangSmith からトレースをクエリ、分析、エクスポートできます。

コマンドを実行するには、skills/langsmith-trace/scripts/ に移動してください。

クイックリファレンス

# Show recent traces
python query_traces.py recent --limit 10 --project my-project

# Show with metadata (timing, tokens, costs)
python query_traces.py recent --limit 10 --include-metadata

# Filter by time
python query_traces.py recent --last-n-minutes 60
python query_traces.py recent --since 2025-01-20T10:00:00Z

# Get specific trace details
python query_traces.py trace <trace-id> --show-hierarchy

# Export traces to directory (recommended for bulk collection)
python query_traces.py export ./traces --limit 50 --include-metadata
python query_traces.py export ./traces --limit 20 --include-io    # With inputs/outputs
python query_traces.py export ./traces --limit 20 --full          # Everything

# Filter by run type
python query_traces.py export ./traces --run-type tool            # Only tool calls
python query_traces.py export ./traces --run-type llm             # Only LLM calls

# Search by name pattern
python query_traces.py search "agent" --project my-project

# Output as JSON
python query_traces.py recent --format json --limit 5

コマンド

recent - 最近のトレースを一覧表示します（--limit、--project、--last-n-minutes、--include-metadata、--format）

trace <id> - 特定のトレースを取得します（--show-hierarchy、--include-metadata、--output）

export <dir> - ディレクトリに一括エクスポートします（--limit、--include-metadata、--include-io、--full、--run-type、--max-concurrent）

search <pattern> - 名前で実行を検索します（--limit、--last-n-minutes）

ヒント

• 一括データには export を使用し、必ず --project を指定してください。一時ファイルには /tmp を使用します。
• パフォーマンスやコストの分析には --include-metadata を含めてください。
• 大規模なエクスポートでは、--max-concurrent 10 に増やしてください。
• 分析には jq とともに --format json を使用してください。

関連スキル

• トレースから評価用データセットを生成するには、langsmith-dataset スキルを使用してください。
• 評価器を作成してパフォーマンスを測定するには、langsmith-evaluator スキルを使用してください。