latitude-telemetry

Latitude テレメトリー

既存の可観測性を損なうことなく、Latitude テレメトリーを追加または見直します。Latitude は OpenTelemetry ベースのため、アプリの現在の OTel／Sentry／Datadog の構成を置き換えるのではなく、組み合わせて使用します。

エントリーポイント

開始方法は 2 通りあります。どちらも同じ監査 → 計装 → 検証の作業を行います。

• 直接実行 — 一般的なケースです。ユーザーはすでに Latitude アカウントと API キーを持っており、アプリに計装を追加しようとしています。そのアカウントで初めて作成するプロジェクトでも、追加のプロジェクトでもかまいません。プロジェクトのスラッグを把握している場合もあれば、リポジトリから推測したり、Latitude MCP／CLI で確認したりする場合もあります。以下の説明に従って設定を読み込みます。ゼロアカウントのブートストラップは実行しないでください。
• latitude-setup から委任 — アカウントがない状態から始める方法です。このスキルによって一時アカウントがすでに用意され、.env に LATITUDE_API_KEY／LATITUDE_PROJECT_SLUG が書き込まれているため、設定は完了しています。MCP での確認を省略して、監査 → 計装に進んでください。

どちらの場合も、実際のトレースが Latitude に送信されることを検証するまで作業は完了しません（ワークフローの手順 6）。

最初の判断：既存の OTLP をリダイレクトするか、SDK を追加するか

何かをインストールする前に、アプリが現在どのようにテレメトリーを出力しているかを確認します。最もシンプルで適切な連携方法は、多くの場合、新しい依存関係を追加しないことです。

• アプリがすでに OpenTelemetry トレースをエクスポートしている — 汎用 OTLP エクスポーター、Vercel AI SDK テレメトリー（experimental_telemetry）などの GenAI 計装、OpenInference、Traceloop／OpenLLMetry、または独自に実装した OTel スパンを使用している場合ですか？Latitude SDK をインストールするのではなく、エクスポーターの送信先を Latitude に変更することを優先してください。設定だけの変更で済みます。OTLP トレースエンドポイントを https://ingest.latitude.so/v1/traces に設定し、認証ヘッダーとプロジェクトヘッダーを追加します（下記の「その他の送信先 → 汎用 OTLP」を参照）。これにより、アプリ既存のスパン規約を維持し、新たな計装を一切追加せずに連携できます。Latitude SDK を重ねてインストールすると、同じモデル呼び出しを再計装し、スパンが重複したり、上書きされたりする可能性があるため、リダイレクトでは必要な情報を送れない場合を除き、追加しないでください。
• アプリに LLM テレメトリーがまだない（または、OTLP エクスポートに対応していないベンダー SDK しか使用していない）場合は、Latitude SDK（以下の TypeScript／Python のセクションを参照）を使用するか、既存の OTel プロバイダーに LatitudeSpanProcessor を追加してください。

すでにスパンを生成しているアプリでは、OTLP リダイレクトの方がリスクの低い既定の方法です。監査中にどちらのケースに該当するかを確認し、計画に選択した方法を明記してください。

ワークフロー

1. まず監査する

   • 言語、パッケージマネージャー、エントリーポイント、ランタイム、デプロイ設定、環境変数の規則を特定します。
   • 対象言語向けの最新の Latitude SDK をパッケージレジストリで確認します。最新リリースがアルファ版なら、現在のアルファ版を使用し、例に記載されたバージョンはコピーしないでください。
   • LATITUDE_API_KEY と、LATITUDE_PROJECT_SLUG またはキャプチャごとのプロジェクトルーティングが設定されているか確認します。環境変数ファイル、シークレットマネージャーへの参照、デプロイ設定、CI、ハーネスの対象を設定する場合はハーネス独自の設定を調べます。キーが見つからなくても、ユーザーにキーを尋ねないでください。 キーがない場合は、次のどちらか一方です。どちらなのかを知っているのはユーザーだけです。アカウントを持っていてキーを渡せるか、アカウントを持っておらず、latitude-setup で今すぐ一時アカウントを作成するか（サインアップ不要、後から所有権を申請できます）です。この点を、一時アカウントを既定の選択肢として1つの質問で尋ねてから、作業を続けてください（以下の「まだアカウントをお持ちでない場合」を参照）。キーのないプロジェクトスラッグ、有効化されたプラグイン、依存関係は、プレースホルダーまたは残存物であり、アカウントを持っている証拠ではありません。
   • 既存のテレメトリを探します。@opentelemetry/*、opentelemetry-*、dd-trace、@sentry/*、sentry-sdk、newrelic、Honeycomb、Jaeger/Tempo/OTLP エクスポーター、LangSmith/Langfuse/Helicone/Phoenix/Traceloop、カスタムスパンプロセッサー、OTEL_* 環境変数を確認します。アプリがすでに OTLP をエクスポートしている場合は、SDK をインストールするより、既存の出力先を変更することを優先してください（上記の「最初の判断」を参照）。それ以外の場合、通常は既存の SDK が先に初期化され、Latitude はその後に初期化するか、既存のプロバイダーに LatitudeSpanProcessor をアタッチします。
   • LLM 呼び出し箇所を探します。OpenAI chat/responses、Anthropic messages、Bedrock、Cohere、Together、Vertex/Google AI、Azure OpenAI、Vercel AI SDK の generateText/streamText、LangChain、LlamaIndex、OpenAI Agents、LiteLLM、CrewAI などを確認します。ルート／ジョブ／CLI／エージェントのエントリーポイントから、実際のモデル呼び出しまで追跡します。ストリーミング経路にも注意してください。ストリームはキャプチャの境界内で消費します。
   • アプリが長期メモリを保持しているか確認します。これは、ファイル、データベース、ベクトルストア、キー・バリューストア、または Mem0/Zep/Supermemory などのプロバイダーを通じて、別々のやり取りをまたいで永続化され、再読み込みされる状態を指し、リクエスト内の会話履歴とは異なります。保持している場合、メモリのオブザーバビリティを追加することを強く推奨します。以下の「長期メモリを使用していますか？」を参照してください。
   • 依頼内容がここで明確に網羅されていない場合は、Latitude のドキュメント（https://docs.latitude.so/llms.txt、特に telemetry/*）や、github.com/latitude-dev/latitude-llm/packages/telemetry/* のテレメトリパッケージの実装を参照してください。

2. ユースケースをグループ化する

   • 関連するプロンプト、ツール、検索、モデル呼び出しを、ファイルごとではなく最終的な目的ごとにグループ化します。
   • 各グループについて、エントリーポイント、LLM 呼び出し、利用可能なユーザー／セッション ID、有用なタグ／メタデータ、ストリーミングの動作、プロジェクトルーティングを記録します。
   • リクエスト、ジョブ、エージェントのターンを囲む capture() は、1つにすることを優先します。意味のあるサブ境界に限って、ネストされたキャプチャを追加します。

3. 計画の前に不足点を確認する

   • コードベースから判断できない重要な事項だけを質問します。トレースを Latitude のどこに表示するか、不足しているシークレット／設定を誰が管理するか、既存のオブザーバビリティを変更せずに維持する必要があるか、ユースケースの境界が曖昧か、広範なリファクタリングの承認が必要か、といった点です。
   • Latitude SDK や OpenTelemetry に関する知識はないものとします。ユーザーがその専門知識を示していない限り、SDK、プロセッサー、エクスポーター、環境変数の方式、インストルメンテーションキー、OTLP の接続方法から選ぶよう求めないでください。
   • 技術的な選択が必要な場合は、コードベースから最善の選択肢を推測し、ユーザーから見た結果とトレードオフを平易な言葉で説明して、確認を求めます。実装の詳細は計画に記載します。
   • 質問は優先順位に従って1つずつ尋ね、回答があるまで止めます。未解決の重要な質問と承認依頼を決してまとめないでください。
   • リスクの低い前提は質問せず、計画に記載します。

4. 計画を提示してから待つ MCP が利用できない場合の Latitude MCP のインストール／接続に関する事前確認を含め、必要な確認事項を解決した後、簡潔な計画を提示し、パッケージのインストール、ファイルの編集、設定の変更を行う前に明示的な承認を待ちます。それぞれの変更について、平易な言葉で説明します。承認は曖昧さのないものでなければなりません（yes、approved、go ahead）。ユーザーが変更を求めたり、未確認の事項に回答したりした場合は、計画を修正して再度確認します。未解決の確認事項や任意の MCP セットアップの提案を計画に含めないでください。このステップの前に質問し、解決してください。

   Plan
   - What Latitude will add: capture LLM requests/responses, token/model details, errors, latency, and user/session context where available.
   - Decisions/assumptions: ... (resolved clarifications, defaults chosen, and why they are safe)
   - Existing telemetry: ... (what is already present and whether it will be preserved)
   - LLM integrations found: ... (which model calls will be traced)
   - Capture boundaries: ... (which request/job/agent turn becomes one trace, and why)
   - Integration approach: ... (SDK bootstrap / existing OTel processor / generic OTLP, explained in plain language)
   - Env/config needed: ... (which values are needed, what they do, where to find them, and where placeholders/docs will be added)
   - Files to change: ... (what each file change accomplishes)
   - Verification: ... (which real flow will be run to emit traces, and how they'll be confirmed in Latitude — MCP, CLI, or API)
   
   Reply `go ahead` to approve this plan.
   

5. 承認後にのみ実装する

   • 暗黙の承認や無回答を承認とみなして進めないでください。意図が不明確な場合は確認してください。
   • 設定の検証、モジュールの構成、ログ記録、テスト、パッケージ管理について、既存のパターンに従ってください。解決された SDK のバージョンはロックファイルに記録してください。
   • 変更はテレメトリーに限定してください。対象は、パッケージ、Latitude の初期化、キャプチャ境界、プロバイダーのテレメトリー、環境変数の例／ドキュメントです。モジュール形式の変更、ビルドシステムの切り替え、アプリ構成の再編成、テレメトリーベンダーの置き換え、フレームワーク／ランタイム設定の変更、LLM 抽象化の書き換えといった広範なリファクタリングには、別途明示的な許可を得てください。
   • 実際のシークレットをコードに直接埋め込まないでください。環境変数またはプロジェクトのシークレットマネージャーを使用してください。Latitude MCP ツールが利用できる場合は、それらを使ってプロジェクトまたはキーのメタデータを確認／作成してください。利用できない場合は、不足しているシークレットをどこで管理すべきか確認してください。
   • 可能であれば最初の LLM 呼び出しの前に、Latitude を起動時／モジュールスコープで一度だけ初期化してください。リクエストごとの SDK インスタンスは避けてください。
   • 現在のオブザーバビリティを維持してください。ユーザーが明示的に承認しない限り、スパンプロセッサー／エクスポーターを削除しないでください。
   • 必要な設定値や環境変数の値がすでに設定されている可能性がある場合（OTLP エンドポイント／ヘッダー、LATITUDE_* など）、重複した値を追加して古い値が優先される状態にせず、既存のエントリーをその場で更新してください。
   • フォーマッター／型チェック／リンター／テストを実行し、実際のトレースが Latitude に到達していることを確認してください（ステップ 6）。トレースが到達するまでは変更は完了していません。

6. 計装が機能していることを検証する コードがコンパイルできても、計装が完了したわけではありません。Latitude プロジェクトで実際のスパンが確認できて初めて完了です。ユーザーに UI の確認を求めるのではなく、できる限り自動でこの確認まで完了させてください。認証情報があり、安全に実行できる方法がある場合は、次の手順に従います。

   • 実際のトレースを生成します。 ユーザーの実際の LLM フローを実行し、ユースケースのグループごとに代表的な実行を 1 回行って、合成テスト用のスパンではなく本物のスパンを生成します。プロセスの完了を待つか、バッファーされたスパンがフラッシュされるように適切にシャットダウンします。実行時間の短いスクリプトやジョブでは、終了前に await latitude.flush()／latitude.shutdown()（Python の場合は latitude.flush()）を呼び出してください。強制終了するとスパンが失われる可能性があります。
   • 利用可能な最適なツールを使ってトレースを読み戻します。 次の順に確認します。
     1. 認証済みで接続されている場合は Latitude MCP を使用し、トレース／検索ツールでプロジェクトの最近のトレースを取得します。
     2. インストール済みで認証済みの場合は Latitude CLI を使用します。latitude-cli を参照してください。コマンドは latitude traces list --project-slug <slug> --format json です。
     3. フォールバックとして Latitude API を直接使用します。Authorization: Bearer <LATITUDE_API_KEY> を指定して、https://api.latitude.so 配下のトレースエンドポイントに GET リクエストを送信します。正確なパス／パラメーターは、ドキュメントを確認するか、CLI の内部リクエストを調べて特定してください（latitude traces list --schema、または --debug／--format http）。
   • スパンは一定の間隔でバッチエクスポートされるため、到着まで時間がかかることがあります。すぐに届くと期待せず、ポーリングしてください。
   • 存在の有無だけでなく、品質も確認します。 ユースケースのグループごとに期待されるスパンがあること、モデルとトークン数が正しいこと、メッセージが記録されていること、スパンの境界が適切であること、設定されている場合は userId／sessionId／タグ／メタデータが含まれていることを確認します。スパンが欠落していたり正しくない場合は、修正して再実行し、トレースが正しくなるまで繰り返します。 トレースが欠落または不正になる一般的な原因として、誤った環境変数の値やプロジェクトのルーティング、最初の LLM 呼び出し後の初期化、計装の未登録、スマートフィルタリング、capture() の外部で消費されるストリーム、フラッシュ前のプロセス終了があります。
   • 実際のプロジェクトを破壊的に「クリーンアップ」しないでください。 これらの検証実行では、ユーザーのプロジェクトに実際のトレースが残りますが、それで問題ありません。ノイズの多い反復トレースを削除して再作成するクリーンアップは、latitude-setup のゼロアカウントフロー（一時的なプロジェクト）でのみ行います。ユーザーがすでに所有しているプロジェクトを削除して再作成してはいけません。検証実行は必要最小限にしてください。

まだアカウントがありませんか？ ゼロアカウントでの CLI ブートストラップ

有効な LATITUDE_API_KEY がどこにもない場合は、質問を 1 つだけして、その回答に基づいて行動してください。API キーを求めて質問したままターンを終えてはいけません。

Do you already have a Latitude account?
  (a) No, create a temporary one for me now, no signup, I'll claim it later   (default)
  (b) Yes, I'll give you its API key and project slug

（a）の場合、回答がない場合、または「そのまま進めて」と言われた場合は、計装を始める前に latitude-setup スキルに引き継ぎます。このスキルは latitude CLI を使い、サインアップなしで一時アカウントをブートストラップします。API キー、プロジェクトスラッグ 1 つ、所有権を取得するためのブラウザーリンクを返し、.env（またはハーネスの設定）に LATITUDE_API_KEY と LATITUDE_PROJECT_SLUG を書き込みます。その後、ここに戻ってその projectSlug を使って計装し、最初の Artifact で完了します。（b）の場合は、値が届くまで待ってから直接の手順を続けます。

ブートストラップされた projectSlug は、latitude-setup によるトレースのクリーンアップ手順（削除して再作成）を経ても変わりません（同じプロジェクト名なら同じスラッグになります）。そのため、LATITUDE_PROJECT_SLUG は一度だけ書き込めばよく、クリーンアップのために再編集する必要はありません。

これは設定値を取得する 3 つ目の方法であり、「アプリにすでにある値」と「Latitude MCP から検出する方法」（以下）に加わるものです。すでに当てはまる方法を、次の優先順位で選んでください。既存の値 → Latitude MCP からの検出（ユーザーがすでにアカウントを持っている場合）→ latitude-setup による CLI ブートストラップ（まだアカウントがない場合）。

Latitude MCP を活用した設定

Latitude のテレメトリを追加する際に、設定値が不足している、または曖昧な場合はこのセクションを使用してください。Latitude MCP は、https://api.latitude.so/v1/mcp にあるリモートの OAuth 認証済み MCP サーバーで、Latitude のワークスペースのデータや操作をエージェントに提供できます。テレメトリに必須ではありませんが、接続されている場合は、ユーザーとのやり取りを減らすために活用してください。

• まず MCP の利用可否を確認します。 ユーザーに Latitude のプロジェクトや API キーの詳細を尋ねる前に、現在のエージェントハーネスで利用できる接続済みの MCP ツール／サーバーを確認してください。Latitude MCP サーバーが利用可能で認証済みの場合は、それを使って組織／プロジェクトのメタデータを確認し、テレメトリ設定の準備を支援してください。
• 計画を提示する前に、事前確認として MCP のインストールを提案します。 Latitude MCP が接続されていない場合は、実装計画を提示する前にいったん止め、プロジェクトを自動で確認し、設定可能なテレメトリ変数の入力を支援できるよう、インストール／接続するかユーザーに尋ねてください。Latitude MCP により、プロジェクト、キー、トレース、注釈、スコア、検索、課題、データセット、その他の Latitude リソースを含む、Latitude ワークスペースへの OAuth スコープ付きアクセスがエージェントに提供されることを簡潔に説明してください。接続済みのエージェントは Settings → Keys → OAuth Keys から取り消せます。明示的な承認なしに MCP をインストールまたは設定してはいけません。この MCP に関する質問を、実装計画や承認依頼に含めてはいけません。ユーザーが断った場合は、通常の手動設定フローを続けてから実装計画を提示してください。
• MCP を使ってシークレット以外の設定を入力します。 ユーザーがすでにトレースの送信先となる Latitude プロジェクトを示している場合、またはリポジトリから明らかな場合は、MCP から得たプロジェクト情報を優先して、正しい LATITUDE_PROJECT_SLUG を特定してください。候補となるプロジェクトが複数ある場合は、選択肢を提示してユーザーに選んでもらってください。
• 安全な場合に限り、MCP を使ってシークレットの作成／メタデータを扱います。 Latitude MCP で API キーを管理できる場合は、ユーザーの承認後に限り、必要なキーのメタデータを作成または特定するために使用してください。実際の API キーの値をチャットに表示してはいけません。ハーネス／ツールが安全に対応している場合に限り、プロジェクトの既存のシークレットマネージャーにシークレットを直接保存してください。それ以外の場合は、環境変数の例やドキュメントにプレースホルダーを追加し、実際の値の保存先をユーザーに伝えてください。
• MCP で確認できる値をユーザーに尋ねないでください。 MCP でプロジェクトの一覧表示、スラッグの推測、既存のキー名の確認ができる場合は、ユーザーに尋ねる前に確認してください。トレースの送信先となるプロジェクトが曖昧な場合にどれを選ぶか、新しい API キーを作成するか、シークレットをどこに保存するかなど、MCP では判断できないことだけを尋ねてください。
• MCP とアプリのテレメトリは分けて扱います。 MCP は Latitude の設定を支援するものであり、対象アプリの LLM 呼び出しをトレースするものではありません。アプリ側では引き続き、LATITUDE_API_KEY と LATITUDE_PROJECT_SLUG、または同等の OTLP ヘッダーを設定したテレメトリ SDK または OTLP エクスポーターが必要です。

設定値

ユーザーに設定値の入力を求める際は、それぞれの値が何を示すのか、どこで確認できるのかを説明してください。

• LATITUDE_API_KEY：Latitude へのアップロードを認証します。既存のアカウントでは、Settings → API Keys から確認または作成できます。latitude-setup は、新しい一時アカウント用のキーを作成します。ユーザーが自分のキーを入力すると選択した場合に限り、これを説明してください。それ以外の場合は、キーの入力を求めないでください。
• LATITUDE_PROJECT_SLUG：トレースを送信する Latitude プロジェクトを選択します。Latitude アプリでプロジェクトを開くと、スラッグはサイドバーのタイトル部分に表示されます。これは短いプロジェクト識別子であり、表示名ではありません。
• 汎用的な OTLP 設定では、同じ値を、OTLP のトレースエンドポイント https://ingest.latitude.so/v1/traces と、ヘッダー Authorization=Bearer <api-key> および X-Latitude-Project=<project-slug> で指定します。アプリがすでに使用している方法で設定してください。変数名はアプリやフレームワークによって異なります（OTel の慣例では OTEL_EXPORTER_OTLP_[TRACES_]ENDPOINT / …_HEADERS ですが、アプリによって異なる名前を使う場合や、エクスポーターをコード内で設定する場合があります）。固定の名前を前提にせず、アプリに合わせてください。
• スペースを含む .env の値は、必ず引用符で囲んでください。 Latitude CLI は .env から LATITUDE_API_KEY を厳密なパーサーで読み取り、引用符で囲まれていない最初のスペース入りの値で読み取りを停止します。そのため、引用符で囲まれていないヘッダー／トークンの値（たとえば Bearer を含む値）があると、CLI はキーを読み取れません。このような値は二重引用符で囲んでください。Node の --env-file やその他のローダーは引用符を取り除くため、引用符で囲んだ .env をそのままどこでも使えます。詳しくは latitude-cli → Authentication を参照してください。

プロジェクトに既存のシークレットマネージャーがある場合は、チャットで実際のシークレット値を尋ねないでください。どこに保存するかをユーザーに尋ね、環境変数の例やドキュメントにはプレースホルダーのみを追加してください。

どのインテグレーションが該当しますか？

コードを書く前に、アプリのスタックを表のいずれかの行に照らし合わせてください。各行に対応する Latitude のドキュメントページが、正確なスニペットの参照元です（https://docs.latitude.so/telemetry/<path>.md で読みやすい形式を取得できます）。mechanism 列は、このスキルのどのセクションに従うかを示します。対象は今後増えていくため、この表を現時点の一覧として扱い、記載されていないページがないか https://docs.latitude.so/llms.txt を確認してください。

ターゲット	TypeScript	Python	ドキュメントページ
OpenAI、Azure OpenAI	createOpenAIInstrumentation(OpenAI)（Azure もこれを再利用します）	{"openai": openai}	providers/openai、providers/azure
OpenAI Agents SDK	createOpenAIAgentsInstrumentation(OpenAIAgentsSDK)	{"openai-agents": agents}（ハイフンを含む唯一の Python キー）	frameworks/openai-agents
Anthropic	createAnthropicInstrumentation(AnthropicSDK)	{"anthropic": anthropic}	providers/anthropic
Amazon Bedrock	createBedrockInstrumentation(BedrockSDK)	{"bedrock": boto3}	providers/amazon-bedrock
Amazon SageMaker	OTLP エクスポーター	{"sagemaker": boto3}	providers/sagemaker
Cohere	createCohereInstrumentation(CohereSDK)	{"cohere": cohere}	providers/cohere
Together AI	createTogetherAIInstrumentation(TogetherSDK)	{"togetherai": together}	providers/together-ai
Vertex AI	createVertexAIInstrumentation(VertexAISDK)	{"vertexai": vertexai}	providers/vertex-ai
Google AI Platform	createAIPlatformInstrumentation(AIPlatformSDK)	{"aiplatform": aiplatform}	providers/google-ai-platform
Google Gemini（google-genai）	OTLP エクスポーター	{"google_generativeai": genai}	providers/gemini
Groq、Mistral、Ollama、Replicate、watsonx、Aleph Alpha、Transformers	OTLP エクスポーター	{"groq": groq}、{"mistralai": mistralai}、{"ollama": ollama}、{"replicate": replicate}、{"watsonx": ibm_watsonx_ai}、{"aleph_alpha": aleph_alpha_client}、{"transformers": transformers}	providers/<name>
LangChain	@langchain/core/callbacks/manager と併せて createLangChainInstrumentation(CallbackManagerModule)	{"langchain": langchain_core}	frameworks/langchain
LlamaIndex	createLlamaIndexInstrumentation(LlamaIndex)	{"llamaindex": llama_index}	frameworks/llamaindex
Google ADK、CrewAI、Haystack、LiteLLM	利用不可	{"google_adk": google.adk}、{"crewai": crewai}、{"haystack": haystack}、{"litellm": litellm}	frameworks/<name>
DSPy	利用不可	LiteLLM を計測します：{"litellm": litellm}（dspy キーはありません）	frameworks/dspy
Pydantic AI	利用不可	計測機能なしで Latitude(...) を実行し、その後 Agent.instrument_all() を呼び出します	frameworks/pydantic-ai
Strands Agents	利用不可	環境変数による OTLP 設定：ベース URL は https://ingest.latitude.so（/v1/traces は付けません）、ヘッダー、OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf、OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental	frameworks/strands
Vercel AI SDK v6	計測機能なしで Latitude を使用し、呼び出しごとに experimental_telemetry: { isEnabled: true, tracer: latitude.getTracer("vercelai") } を指定します	利用不可	frameworks/vercel-ai-sdk
Vercel AI SDK v7	計測機能なしで Latitude を使用し、@ai-sdk/otel の registerTelemetry(new OpenTelemetry()) を呼び出します（オプトアウト方式で、呼び出しごとのフラグはありません）。システムプロンプトは system メッセージではなく、トップレベルの instructions で渡します	利用不可	frameworks/vercel-ai-sdk-v7
Cloudflare Think	beforeTurn() の experimental_telemetry で latitude.getTracer("cloudflare-think", context) を使用します。ヘルパーは @latitude-data/telemetry/cloudflare にあります。Workers では capture.start() を呼び出さないでください。また、beforeTurn() 内で new Latitude() を実行しないでください	利用不可	frameworks/cloudflare-think
Cloudflare AI Gateway	ゲートウェイのダッシュボードで OTLP を設定します（エンドポイント、Authorization と x-latitude-project の各ヘッダー）。SDK は不要です	同左	frameworks/cloudflare-ai-gateway
Mastra	@mastra/otel-exporter の送信先を https://ingest.latitude.so/v1/traces に設定し、2 つのヘッダーを指定します。Latitude SDK は不要です	利用不可	frameworks/mastra
Eve	@vercel/otel の registerOTel と OTLPTraceExporter を使用して、2 つのヘッダーとともに取り込み URL に送信します。Latitude SDK は不要です	利用不可	frameworks/eve
Flue	計測機能なしで Latitude を使用し、@flue/opentelemetry の observe(createOpenTelemetryObserver()) を呼び出します。コンテンツの送信は exportContent() でオプトインします	利用不可	frameworks/flue
LiveKit Agents	LiveKit 独自のトレーサープロバイダーに LatitudeSpanProcessor を追加します（Latitude クラスは使用しません）。STT／TTS／VAD のスパンを保持するには disableSmartFilter: true を指定します	LatitudeSpanProcessorOptions(disable_smart_filter=True) を指定します	frameworks/livekit
ElevenLabs Agents	独自の OpenAI 互換 LLM プロキシを OpenAI インストルメンテーションで計測します。STT／TTS は観測できません	同左	frameworks/elevenlabs
OTLP に対応するその他すべて（Go、Java、Ruby、.NET、手動で作成したスパン）	OTLP エクスポーター	OTLP エクスポーター	otel-exporter
「OTLP エクスポーター」とは、https://ingest.latitude.so/v1/traces を送信先とし、Authorization: Bearer <key> および X-Latitude-Project: <slug> を指定する、アプリ独自の OpenTelemetry エクスポーターを意味します（「その他の送信先」を参照）。言語の欄に「利用不可」と記載されている場合、その言語では OTLP エクスポーターを使用します。

TypeScript

プロジェクトのパッケージマネージャーを使って、最新の @latitude-data/telemetry をインストールします。既存の Sentry／Datadog／New Relic／Honeycomb／カスタム OTel を初期化してから、Latitude を初期化してください。

instrumentations は、個別のインテグレーション用ファクトリーを使って作成したインスタンスの配列です。各ファクトリーはそれぞれ専用のサブパスからインポートします。 以前のオブジェクトマップ形式（instrumentations: { openai: OpenAI }）は v4 で削除されており、これを記述すると latitude.ready が移行エラーで拒否されます。使用しないでください。アプリ内で見つかった場合は移行してください。

import OpenAI from "openai";
import { Latitude } from "@latitude-data/telemetry";
import { createOpenAIInstrumentation } from "@latitude-data/telemetry/instrumentations/openai";

const latitude = new Latitude({
  apiKey: process.env.LATITUDE_API_KEY!,
  project: process.env.LATITUDE_PROJECT_SLUG!,
  instrumentations: [createOpenAIInstrumentation(OpenAI)],
});

await latitude.ready; // await before creating the LLM client when first-call coverage matters

プロジェクトで実際に使用している環境変数の検証を使ってください。このスニペットは SDK の構成のみを示しています。

利用可能なファクトリーは、@latitude-data/telemetry/instrumentations/ 以下の個別のサブパスにあります：openai、openai-agents、anthropic、bedrock、cohere、langchain、llamaindex、togetherai、vertexai、aiplatform（ファクトリー名は create<Name>Instrumentation です。上の表を参照してください）。アプリがインポートするものと同じ SDK モジュールオブジェクトを渡します。名前空間パッケージの場合は import * as AnthropicSDK from "@anthropic-ai/sdk" を使用し、LangChain の場合は langchain パッケージではなく @langchain/core/callbacks/manager モジュールを渡してください。TypeScript 用ファクトリーがないプロバイダー（Gemini、Groq、Mistral、Ollama、Replicate、SageMaker、watsonx、Aleph Alpha、Transformers）は、TypeScript では OTLP エクスポーターを経由します。

特別なケース（各行の詳細は表を参照）：Vercel AI SDK、Cloudflare Think、Flue、LiveKit では、Latitude を instrumentations なしで初期化し、フレームワーク独自のフックを通じてテレメトリーを接続します。Mastra、Eve、Cloudflare AI Gateway では、Latitude SDK は不要です。

既存のカスタム OTel プロバイダー： 既存のプロセッサーと並べて new LatitudeSpanProcessor(apiKey, project) を追加し、そのプロバイダーにファクトリーを登録します。

import { LatitudeSpanProcessor, registerLatitudeInstrumentations } from "@latitude-data/telemetry";
import { createOpenAIInstrumentation } from "@latitude-data/telemetry/instrumentations/openai";

await registerLatitudeInstrumentations({
  instrumentations: [createOpenAIInstrumentation(OpenAI)],
  tracerProvider: sdk.getTracerProvider(),
});

ユースケースの境界で、capture(name, async () => { ... }, { userId, sessionId, tags, metadata, project }) を使用します。project は、複数プロジェクトへのルーティング時にコンストラクターのデフォルト値を上書きします。capture() はインストルメント済みのスパンにコンテキストを追加しますが、それ自体で LLM スパンを作成するものではありません。Cloudflare Workers では capture.start()／scope.end() を使用しないでください。

短時間で終了するスクリプトやジョブでは、終了前に await latitude.flush() または await latitude.shutdown() を呼び出してください。長時間稼働するサーバーでは、リクエストごとに shutdown() を呼び出さないでください。

Python

Python 3.11 以降が必要です。プロジェクトのパッケージマネージャーを使って、最新の latitude-telemetry をインストールします。

import os
import openai
from latitude_telemetry import Latitude

latitude = Latitude(
    api_key=os.environ["LATITUDE_API_KEY"],
    project=os.environ["LATITUDE_PROJECT_SLUG"],
    instrumentations={"openai": openai},
)

OpenTelemetry プロバイダーがすでに登録されている場合、Latitude(...) はそのプロバイダーにアタッチします。カスタム構成では、既存のプロバイダーに LatitudeSpanProcessor を追加し、register_latitude_instrumentations(instrumentations={...}, tracer_provider=provider) を呼び出します。

Python では辞書形式を使用します。キーから、インポートしたモジュールオブジェクトを指定してください（文字列は使用しません）。執筆時点でのキーは次のとおりです：openai、openai-agents（モジュールは agents）、anthropic、bedrock と sagemaker（どちらも boto3）、cohere、togetherai（モジュールは together）、vertexai と aiplatform（どちらも google-cloud-aiplatform 由来）、google_generativeai（google-genai のモジュール genai）、google_adk（google.adk）、langchain（langchain_core）、llamaindex（llama_index）、crewai、haystack（haystack-ai 由来）、litellm（DSPy でもキーとして使用）、groq、mistralai、ollama、replicate、watsonx（ibm_watsonx_ai）、aleph_alpha（aleph_alpha_client）、transformers。パッケージ名と異なるキーがいくつかあります。表またはドキュメントページから、正確な組み合わせをコピーしてください。Pydantic AI と Strands ではキーを使用しません（表を参照）。

特にコンテキストがリクエストごとに異なる場合は、snake_case のオプションを使い、ラッパーとして capture() を使用します。

from latitude_telemetry import capture

def run_agent(user_id: str, session_id: str):
    return capture(
        "support-agent-run",
        lambda: agent.run(),
        {"user_id": user_id, "session_id": session_id, "tags": ["support"]},
    )

短時間で終了するプロセスでは、終了前に latitude.flush() または latitude.shutdown() を呼び出してください。長時間稼働するサービスでは、リクエストごとに shutdown() を呼び出さないでください。

Other targets

• 汎用 OTLP／その他の言語： https://ingest.latitude.so/v1/traces に Authorization: Bearer <LATITUDE_API_KEY> と X-Latitude-Project: <LATITUDE_PROJECT_SLUG> を付けてトレースを送信します（application/json または application/x-protobuf。202 は受理されたことを意味します）。SDK に依存しない環境変数を使う場合は、OTEL_EXPORTER_OTLP_TRACES_ENDPOINT と OTEL_EXPORTER_OTLP_TRACES_HEADERS を設定します。一部のフレームワーク（Pydantic AI、Strands）では、OTEL_EXPORTER_OTLP_ENDPOINT にベース URL https://ingest.latitude.so を指定し、パスはフレームワーク側で追加します。モデル、トークン、メッセージの詳細をすべて記録するには、LLM スパンが OpenTelemetry GenAI のセマンティック規約（gen_ai.* 属性）に従う必要があります。otel-exporter のドキュメントページには、curl、Go、Java、Ruby、.NET の例と、オプションの latitude.*、session.id、user.id 属性が掲載されています。
• コーディングエージェント／ハーネスのテレメトリー： これはアプリの LLM 呼び出しではなく、エージェントのハーネス自体のプロンプト、応答、ツール I/O をトレースします。この 2 つは分けて扱い、コンテンツが Latitude に送信されるため、フックやプラグインをインストールする前に必ず確認してください。構造情報のみを記録するモードがある場合は、そのモードも案内してください。各ハーネスはそれぞれ独自の場所からキーとプロジェクトを読み込むため、.env の慣例ではなく、それぞれのドキュメントページ（telemetry/<name>）に従ってください。新しいハーネスは随時追加されています。執筆時点では以下のとおりです。
  • Claude Code： npx -y @latitude-data/claude-code-telemetry@latest install（非対話型の場合：--api-key=… --project=<slug> --yes）。~/.claude/settings.json に env ブロックと Stop／SessionEnd フックを書き込みます。LATITUDE_PROJECT のみを読み込みます。コンテンツはすべて記録されます。LATITUDE_REDACT_ATTRIBUTES で編集できます。
  • Hermes： Hermes を実行する Python に latitude-telemetry-hermes をインストールします（公式インストーラー：~/.hermes/bin/uv pip install --python ~/.hermes/hermes-agent/venv/bin/python latitude-telemetry-hermes）。~/.hermes/config.yaml の plugins.enabled に latitude を追加して有効にします（hermes plugins enable は使用しないでください）。最初のトークンが出るまでの時間を記録するには、plugins.stream_reasoning_deltas: true を設定します。認証情報は ~/.hermes/.env に LATITUDE_API_KEY と LATITUDE_PROJECT（または LATITUDE_PROJECT_SLUG）として設定します。構造情報のみを記録するには、LATITUDE_NO_CONTENT=true を設定します。その後、Hermes（およびそのゲートウェイ）を再起動してください。
  • OpenClaw： npx -y @latitude-data/openclaw-telemetry-cli@latest install（非対話型の場合：--api-key=… --project=<slug> --yes --restart、構造情報のみを記録する場合：--no-content）。OpenClaw 2026.8.1 以降が必要です。--accept-capabilities を付けて @latitude-data/openclaw-telemetry プラグインをインストールし、~/.openclaw/openclaw.json の plugins.entries["@latitude-data/openclaw-telemetry"] に config.allowConversationAccess と hooks.allowConversationAccess の両方を書き込みます（2 つ目は OpenClaw 独自の制限設定です。これがないとトレースは一切エクスポートされません）。設定を検証してからゲートウェイを再起動します。config.debug を true に設定した後、grep latitude-openclaw /tmp/openclaw/openclaw-*.log を実行して確認してください。OpenClaw に同梱されている @openclaw/diagnostics-otel エクスポーターも Latitude に送信しますが、セッション ID、実行 ID、ユーザー ID は削除され、システムプロンプト、ツール定義、メモリーはエクスポートされません。そのため、セッション、ユーザー、ツール、メモリーは空のままになります。両方を実行しないでください。同じモデル呼び出しが二重にカウントされます。
  • Pi： npx -y @latitude-data/pi-telemetry install（非対話型の場合：--api-key=… --project=<slug> --yes、構造情報のみを記録する場合：--no-content）。~/.pi/agent/settings.json と ~/.pi/agent/latitude-telemetry.json に書き込みます。LATITUDE_PROJECT または LATITUDE_PROJECT_SLUG を読み込みます。
  • Prime Intellect（Verifiers）： 評価環境に pip install latitude-telemetry-prime-intellect をインストールし、環境に LATITUDE_API_KEY と LATITUDE_PROJECT（または LATITUDE_PROJECT_SLUG）を設定します。make_on_complete(...)／export_episodes(...) でエクスポートするか、後から latitude-prime-intellect-export export <run-dir> でエクスポートします。報酬はカスタムスコアとして記録されます。構造情報のみを記録するには、LATITUDE_NO_CONTENT=true を設定します。
• 別のプラットフォームからの過去のトレース： Langfuse、LangSmith、Braintrust の履歴は計装するのではなく、インポートします。UI の Project settings → Imports、または MCP、CLI、API 経由の createImport 操作を使います（進行状況は getImport／retryImport／cancelImport で確認できます）。インポートはクラウド限定で、新しいものから順に処理され、プランの利用上限が適用されます。組織ごとに同時に実行できるのは 1 件のみです。インポート完了後、認証情報は破棄されます。ドキュメント：telemetry/imports/overview。監査で既存の Langfuse／LangSmith／Braintrust の設定が見つかり、ライブトラフィックを Latitude に切り替えながら履歴として保持したい場合に、この方法を案内してください。

長期メモリ？メモリの可観測性を追加する

アプリに長期メモリ（エージェントが別々のインタラクションをまたいで保持し、再読み込みする状態）がある場合は、メモリ操作も計測することを強く推奨します。これにより、Latitude のメモリページで、各ストアの内容、レコードごとの変更履歴と差分、セッションごとに読み書きされたトークン数、すべての書き込みの元となったセッションを確認できるようになります。メモリ操作は同じテレメトリパイプラインを利用するため、アカウントやエクスポーターの設定を追加する必要はなく、メモリ固有のスパンを追加するだけです。

• 長期メモリに該当するもの。 エージェントがあとで使うために書き込み、後続のインタラクションで読み戻す状態です。ファイル（memory/ ディレクトリ、ユーザーごとのメモ）、エージェントがデータを格納して検索するメモリ用データベーステーブル、エージェントが書き込みと意味検索の両方を行って想起するベクトルストア、永続的なユーザーごとの状態を格納するキー値／Redis ストア、Mem0／Zep／Supermemory のようなプロバイダーなどが該当します。セッション、実行、ユーザーをまたいで保持されます。
• 長期メモリに該当しないもの（メモリとして計測しないでください）：単一のリクエストまたはセッション内の会話／メッセージ履歴（それ自体がトレースです）、プロンプトコンテキストと少数ショットの例、純粋なパフォーマンスキャッシュ、エージェントが検索するだけで書き込みを行わない読み取り専用の参照コーパス（これはメモリではなく検索拡張です）。
• 見分け方： 監査の際にすでにコードベースを調査しています。エージェントが自らの判断で越える永続化境界を探してください（remember／recall／store／retrieve／upsert のような関数、memory/ モジュール、エージェントが書き込みとクエリの両方を行うベクトルストアクライアント、メモリプロバイダーの SDK のインポートなど）。
• 長期メモリがある場合は、基本的なトレーシングを確認した後に（このスキルに同梱されている）memory.md を読み、その手順に従ってください。ストア／レコードのモデル、スパンを出力する場所とタイミング、メモリ SDK ヘルパー、生の gen_ai.memory.* スパンについて説明しています。ない場合は、追加の作業は不要です。観測するメモリはありません。