tracing

コードに LangWatch トレーシングを追加する

対象範囲を決める

ユーザーの依頼が一般的な場合（「コードを計測する」「トレーシングを追加する」「可観測性を設定する」など）：

• コードベース全体を読み、エージェントのアーキテクチャを把握します
• Git の履歴を調べ、何が、なぜ変更されたのかを把握します。エージェントの動作変更、プロンプトの調整、バグ修正に重点を置き、背景を理解するためにコミットメッセージを読みます
• すべての LLM 呼び出し箇所に包括的なトレーシングを追加します

ユーザーの依頼が具体的な場合（「支払い関数にトレーシングを追加する」「このエンドポイントをトレースする」など）：

• 対象の関数またはモジュールに重点を置きます
• 依頼された箇所にのみトレーシングを追加します
• そのコンテキストで計測が機能することを確認します

このスキルで扱うのはコードのみです。トレーシングのためのプラットフォーム上の手段はありません。ユーザーにコードベースがない場合は、トレーシングにはコードの計測が必要であることを説明してください。

Langy では、ユーザーが手動で適用できるよう変更内容を表示するのではなく、code_access を呼び出し、code-changes スキルに従ってユーザーのマシン上または GitHub 経由で変更してください。

手順 1：インテグレーションのドキュメントを読む

langwatch docs <path> を使って、ドキュメントを Markdown として読みます。役立つエントリーポイントを以下に示します。

langwatch docs                                    # Docs index
langwatch docs integration/python/guide           # Python integration
langwatch docs integration/typescript/guide       # TypeScript integration
langwatch docs prompt-management/cli              # Prompts CLI
langwatch scenario-docs                           # Scenario docs index

langwatch --help と langwatch <subcommand> --help でコマンドを確認します。list コマンドと get コマンドでは、機械可読な出力を得るために --format json を指定できます。すべての list コマンドでは、行数を制限する --limit <n> と、回答の一部を読み取る --jq <expr> を使用できます。ページ分割された list の回答はエンベロープ形式なので、行配列を通じて行数を数え（--jq '.traces | length'）、全体の件数は .pagination.total で確認します。単独の --jq length は行数ではなく、エンベロープのフィールド数を数えます。SDK API や CLI フラグを推測するのではなく、まずドキュメントを読んでください。

シェルを利用できない場合は、同じ Markdown をプレーン HTTP で取得してください。ドキュメントのパスに .md を追加します（例：https://langwatch.ai/docs/integration/python/guide.md）。インデックス：https://langwatch.ai/docs/llms.txt。シナリオのインデックス：https://langwatch.ai/scenario/llms.txt

このスキルの実行中に問題が発生したり、わかりにくい点があったりした場合（コマンドの不具合、実態と異なるドキュメント、回避策が必要だったエラーなど）は、ユーザーの許可を得て、--title と --summary（または --session <transcript.jsonl>）を指定して npx --yes langwatch report --user-approved を実行し、LangWatch チームに報告してください。報告内容は、修正対象の決定に直接反映されます。ログインも API キーも必要ありません。--user-approved を指定しない限り、情報は送信されません。また、--dry-run を指定すると、送信せずに正確なペイロードを表示できます。タイトル、概要、トランスクリプトは、送信前にローカルでパターンに基づいてサニタイズされます。対象となるのはシークレットと API キーのほか、メールアドレス、電話番号、カード番号、パブリック IPv4 アドレスです。パターンに一致しない情報は、--email で指定した連絡先を含め、そのまま送信されます。--session を指定する場合は、必ず先に --dry-run を実行し、ペイロードをユーザーに確認してもらってください。トランスクリプトには、ユーザーが確認していない内容が含まれているためです。オプションについては npx --yes langwatch report --help を参照してください。

プロジェクトと API キー：個人用ではなく、実際のプロジェクトを対象にしてください。

LangWatch のプロジェクトには、次の 2 種類があります。

• チーム／共有プロジェクト：組織内の実際のプロジェクトです。評価、実験、プロンプト、データセット、シミュレーション、計測は、必ずこれらを対象にしてください。
• 個人用プロジェクト：単一ユーザーにひも付いた、プライベートな「My Workspace」の作業スペースです。ユーザーの評価、実験、本番トレースをここに送信しないでください。個人的な試用のみを目的としており、実際のプロジェクトと取り違えるおそれがあります。

認証方法は次の 2 つです。

• .env にあるプロジェクト API キー（LANGWATCH_API_KEY）：このスキルで使用するすべての認証情報です。実際の 1 つのプロジェクトにスコープが限定されています。これがデフォルトの方法です。ユーザーから明示的に別の方法を求められない限り、これを優先してください。
• langwatch login --device（AI ツール／SSO）：コーディングアシスタント（langwatch claude、langwatch codex など）をラップするための、個人用デバイスセッションです。評価、プロンプト、データセット、シナリオ、SDK 計測には使用しません。また、個人用ワークスペースを参照します。このスキルで行う作業の設定に使用しないでください。 そのため、プロジェクトを読み書きするこれらのスキルでは、実際に共有されているプロジェクトの LANGWATCH_API_KEY を CLI が利用できる状態にしてください。ローカルではプロジェクトの .env にあり、CI ではランナーがプロセス環境に設定します。CLI はどちらからでも読み取れます。新しいキーを求める前に、この変数がすでに設定されているか確認し、値は CLI に読み取らせてください。値を表示、コピー、送信してはいけません。プロジェクトを選ぶために langwatch login を実行してはいけません。また、個人用プロジェクトを既定として使ってはいけません。同じ場所で LANGWATCH_ENDPOINT も確認してください。設定されている場合、そのプロジェクトはセルフホストインスタンス上にあり、CLI は app.langwatch.ai ではなく、そのエンドポイントに対して動作します。

読み取った内容をそのまま伝えてはいけません。 これらのスキルは作業用のメモであり、読者向けの文章ではありません。プロジェクト固有の .env から LANGWATCH_API_KEY と LANGWATCH_ENDPOINT を読み取ってください。これにより、どこで作業すべきかがわかります。そのファイルから他の情報を読み取ってはいけません。データベース、クラウド、プロバイダーの認証情報が含まれており、あなたが知る必要はありません。また、読み取った値はどれも、あなたのコンテキストやコマンド出力に含まれる可能性があります。回答に含めてはいけないのは、あなたが実行されているマシンに関する情報です。ワークスペース内のパス、コンテナーのポート、このワーカーが接続するアドレスなどが該当します。これらは何をしたかではなく、どのように作業したかを示す情報であり、私たちの環境の情報は読者には何の意味もありません。何を行ったか、そして LangWatch のどこで確認できるかを伝えてください。

次に、このプロジェクトのフレームワーク用のインテグレーションガイドを取得してください。

langwatch docs integration/python/guide                      # Python (general)
langwatch docs integration/typescript/guide                  # TypeScript (general)
langwatch docs integration/python/integrations/open-ai       # Framework page
langwatch docs integration/typescript/integrations/mastra    # Framework page

フレームワークのページは integration/<language>/integrations/<framework> にあります。integration/<language>/<framework> ではありません。フレームワークのスラッグはベンダー名を単語間のハイフンでつないだものです。open-ai、open-ai-agents、open-ai-azure、aws-bedrock、google-ai、vertex-ai、lite-llm、crew-ai、pydantic-ai、strand-agents、vercel-ai-sdk に加え、1 語のもの（langchain、langgraph、agno、anthropic、mastra、haystack、llamaindex、instructor、dspy、autogen、smolagents、semantic-kernel、promptflow、azure-ai）があります。

わからない場合は、パスを指定せずに langwatch docs を実行してください。すべてのページのインデックスが表示されます。docs はページを Markdown として出力し、--output、--json、--jq、--format は受け付けません。取得結果が 404 の場合はパスが間違っています。別の綴りを推測せず、インデックスを確認してください。

重大な注意：計測方法を推測してはいけません。フレームワークごとに計測のパターンは異なるため、必ず最初にそのフレームワーク固有のガイドを読んでください。

ステップ 2：LangWatch SDK をインストールする

Python の場合は、最初に成功した方法で止める順序で試します。ワークスペースの情報から判断できるパッケージマネージャーを最初に試します。情報に uv と記載されている場合、フォルダーに uv.lock がある場合、または .venv/pyvenv.cfg に uv = の行がある場合は、uv add langwatch を実行します（uv が作成した仮想環境には pip がありません）。それ以外の場合は、.venv があれば .venv/bin/python -m pip install langwatch を実行し、その後に限り pip install langwatch、pip3 install langwatch、python3 -m pip install langwatch、python -m pip install langwatch を試します。コマンドが見つからない場合（終了コード 127）は、再試行せず、次の方法に進みます。これはコマンド名が存在しないだけで、機能がないわけではありません。どの方法も使えない場合は、諦める前に確認します。「uv をインストールしてください」または「Python は自分で設定します」。

TypeScript の場合、別のパッケージマネージャーを指定するロックファイルがなければ npm install langwatch を実行します。ロックファイルに応じて、pnpm add langwatch、yarn add langwatch、または bun add langwatch を実行します。指定されたパッケージマネージャーで終了コード 127 が返された場合は、npm に切り替えます。

uv add と JavaScript のパッケージマネージャーは、マニフェストを自動的に更新します。pip でインストールしてもファイルは更新されないため、プロジェクト独自の requirements ファイル（requirements.txt、または requirements/base.txt など、そのフォルダーで使用しているファイル）に自分でパッケージを追加します。python -m pip show langwatch でバージョンを確認し、langwatch==<installed version> の行を追加します。他のパッケージと同じ方法でバージョンを固定し、他のパッケージを固定していない場合は固定しません。

コードを書く前に、インストールしたインタープリターを通じて API が利用できることを確認します。Python の場合は python -c "import langwatch; langwatch.setup; langwatch.connect_agent"、TypeScript の場合は node -e "require('langwatch')" を実行します。Python 1.3.0 より前のリリースには、どちらの API もありません。また、SDK がサポートするバージョンより新しいインタープリターでは、pip は何も通知せずにサポート対象の最後のリリースをインストールします。API を備えたすべてのリリースには Python の上限が指定されており、pip は上限の指定がない最後のリリースまでさかのぼるためです。その場合、pip install langwatch --upgrade では解決できません。確認に失敗した場合は、諦める前にインタープリターについて確認します。「uv を使って Python 3.13 をインストールしてください」または「インタープリターは自分で選びます」。

ピア依存関係の競合が原因でインストールに失敗した場合は、競合する範囲を広げて再試行してください。黙ってスキップしてはいけません。

ステップ 3：計測を追加する

ステップ 1 で確認した統合ガイドに従ってください。基本的な形は次のとおりです。

Python：

import langwatch
langwatch.setup()

@langwatch.trace()
def my_function():
    ...

TypeScript：

import { LangWatch } from "langwatch";
const langwatch = new LangWatch();

正確なパターンはフレームワークによって異なるため、これらの例ではなくドキュメントに従ってください。

グラフでは、コールバックをグラフに渡します。グラフ内のモデル呼び出しに渡すのではありません。 LangChain は、コールバックが設定された場所から下位へ伝播させます。そのため、LangGraph ではグラフの呼び出し時に config にコールバックを設定します。

graph.invoke(state, config={"callbacks": [langwatch.get_current_trace().get_langchain_callback()]})

同じ config 引数は ainvoke と stream でも機能します。実行が通るすべてのノードは、トレース内のスパンになります。ノード名が付いたチェーンスパン、モデル呼び出しの LLM スパン、ツール呼び出しのツールスパンです。1 つのノード内のモデル呼び出しにのみコールバックを設定すると、トレースには LLM スパンしか含まれません。そのため、ツールノードと通常の関数ノードが抜け落ち、グラフが決済ステップに到達したかどうかを確認するためのスパンも得られません。

環境変数は LangWatch の初期化前に読み込まれます。 langwatch.setup() と new LangWatch() は実行された時点で、プロセス環境から LANGWATCH_API_KEY を読み取ります。.env ファイルは、何かが読み込むまでは環境変数ではありません。ある実行では、エントリーファイルの先頭、load_dotenv() を呼び出すインポートより前に langwatch.setup() が置かれていました。その結果、インポート時にプロセスが "LangWatch API key is required but not provided" というエラーで終了しました。

• Python：環境変数を読み込む処理（python-dotenv の load_dotenv()、設定モジュール、設定ローダーなど）を見つけ、その処理を実行するすべてのインポートより後に langwatch.setup() を置いてください。エントリーファイルの先頭には置かないでください。プロジェクトが python-dotenv に依存しているものの、エントリーファイルで読み込んでいない場合は、計測するエントリーファイルの先頭、import langwatch より前に from dotenv import load_dotenv と load_dotenv() を追加してください。
• TypeScript：プロジェクトで dotenv を使用している場合は、エントリーファイルの最初のインポートとして、langwatch のインポートより前に import "dotenv/config" を置きます。SDK はインスタンス化された時点でキーを読み取ります。

プロセスを開始する前に、プロジェクトでの読み込み方法に従って、キーがプロセスから参照できることを確認してください。これは最初で唯一の確認です。言語に対応するコマンドをそのままコピーし、プロジェクトのルートから 1 回実行して、結果を確認してください。その前に別の方法を試してはいけません（ローダーなしの import langwatch などを使った確認では、dotenv プロジェクトの場合、プロセス環境を直接読み取るため、必ず見つからないという結果になります）。確認後に繰り返すこともできません。

uv run python -c "from dotenv import load_dotenv; load_dotenv(); import os; print(bool(os.getenv('LANGWATCH_API_KEY')))"

プロジェクトで使用している実行コマンドが uv run の場合はそれを使い、poetry run python -c または .venv/bin/python -c を使用しているプロジェクトでは、それぞれのコマンドを使ってください。必ず -c を使い、heredoc を使った python - は使わないでください。python-dotenv のローダーは呼び出し元のファイルを探すため、標準入力から実行すると失敗します。TypeScript：

node -e "require('dotenv').config(); console.log(Boolean(process.env.LANGWATCH_API_KEY))"

このコマンドは、LANGWATCH_API_KEY が設定されているかどうかだけを出力し、値は出力しません。dotenv 以外を使っている場合は、ローダーをプロジェクト独自のものに置き換えてください。False が出た場合は、ファイルがローダーの検索場所にないか、上記の順序が間違っています。そこを修正し、別のパスを使って確認をやり直してはいけません。

Step 4: 検証

検証せずに作業を完了したと考えてはいけません。以下の順に進めます。

1. 依存関係が問題なくインストールされたことを確認します。
2. 少なくとも 1 つのトレースが生成されるテスト入力でエージェントを実行します（フレームワークの起動方法を調べます。自分では起動できないインフラストラクチャが必要な場合に限り、ここで断念します）。
3. トレースが届いたことを確認します：langwatch trace search --limit 5 --format json。実行終了直後はトレースを検索できません。エクスポートがまずプロセスの外に出て、その後取り込みに数秒かかるため、最初の結果が空でも「まだ届いていない」という意味であり、「動作していない」という意味ではありません。約 20 秒間隔で最大 3 回まで待って再確認し、そこで終了します。検索対象は直近 24 時間分なので、トレースが取り込まれれば検索結果に現れます。試行ごとにコマンドを変更しないでください。
4. 待った結果を伝えます。トレースが見つかった場合は、実行によって何が生成されたかを伝えます。3 回目の確認後も見つからなかった場合は、計装が設定されているものの、トレースがまだ届いていないことと、確認すべきプロジェクト名を伝え、変更が検証済みだと報告しないでください。
5. 検証できない場合（シェルにアクセスできない、コードを実行できない、外部サービスが不足しているなど）は、LangWatch ダッシュボードで何を確認すべきか、また何をどのような理由で検証できなかったかを、ユーザーに具体的に伝えます。

この手順で確認できるのは、トレースが届くことだけです。その後、特定のトレース（特定のユーザー、エラー、低評価など）を探すには、find-traces スキルを使用します。

よくある間違い

• 計装のパターンを推測してはいけません。フレームワーク固有のドキュメントを読んでください。
• Python では langwatch.setup() を省略してはいけません。
• 環境変数を読み込むインポートより前に langwatch.setup() を呼び出してはいけません。キーは setup() の実行時に読み込まれます。
• LangChain コールバックをグラフノード内のモデル呼び出しだけに設定してはいけません。グラフの呼び出しに設定する必要があります。設定しないと、ノードがスパンになりません。
• Step 1 を省略してはいけません。計装のパターンは OpenAI／LangGraph／Vercel／Mastra／Agno ごとに異なり、推測すると気づきにくい不具合が生じます。