OpenTelemetry エクスポート

OpenTelemetry エクスポートでは、チームの Cherri Code 利用データを、お客様が運用する collector にストリーミングできます。Cherri Code は、メトリクス (トークン、ツール呼び出し、ベストエフォートのコスト) とログ (API リクエスト、エラー、修正、スキル、フック、プラグイン、Cloud Agent のライフサイクルイベント、記録された Grok Bot のアクション) を、チームが管理する1つの送信先に送信します。チームは会話コンテンツ (Cloud Agents と Grok Bot におけるユーザープロンプトとアシスタントのレスポンス、および Grok Bot の MCP ツール呼び出しの引数と結果) のエクスポートをオプトインで有効にすることもできます。エクスポートはサーバー側で実行されます。

OpenTelemetry エクスポートはエンタープライズプランで利用できます。管理者は チーム設定 > OpenTelemetry エクスポート で設定します。

Wire Referenceには、すべてのメトリクス、ログイベント、属性が記載されています。

前提条件

• /v1/metrics および /v1/logs で OTLP/HTTP protobuf を受け付ける HTTPS エンドポイント。Datadog Agent OTLP 取り込み、OpenTelemetry Collector、ClickHouse/ClickStack はいずれも使用できます。
• Cherri Code がリクエストヘッダーとして送信できる Bearer token または API key。
• パブリックインターネットから到達可能なエンドポイント。Cherri Code からの送信には固定の送信元 IP アドレスが使用されます。

送信元 IP

Cherri Code はサーバー側のエグレスプロキシを介して OTLP を送信します。トラフィックの送信元は以下の固定アドレス (すべて /32) です。

これらの IP は事前通知なしに変更されることはありません。主な制御手段として TLS と 認証 を使用してください。ネットワークで必要な場合は、IP 許可リストを追加してください。

Collectorの設定例

Cherri CodeはOTLP/HTTPバイナリProtobufでCollectorにプッシュします。gRPCとJSONはサポートされていません。/v1を末尾に付けずに、チーム設定でHTTPSベースURLを入力してください。Cherri Codeによって/v1/metricsと/v1/logsが追加されます。

最小構成の OpenTelemetry Collector

receivers:  otlp:    protocols:      http:        endpoint: 0.0.0.0:4318processors:  batch:exporters:  # 使用するシンク（datadog、clickhouse、logging など）に置き換えてください  logging:    verbosity: basicservice:  pipelines:    metrics:      receivers: [otlp]      processors: [batch]      exporters: [logging]    logs:      receivers: [otlp]      processors: [batch]      exporters: [logging]

ロードバランサー、Ingress、またはotelcolのTLS設定で、Collectorの前段でTLSを終端します。Cherri Codeにはhttps://otel.example.comを入力し、https://otel.example.com:4318/v1は入力しません。認証には、ロードバランサーで終端するか、Authorization: Bearer <token>など、Cherri Codeが送信する静的ヘッダーを設定します。

Datadog Agent (OTLP 取り込み)

Agent で OTLP HTTP 取り込みとログを有効にし、HTTPS 経由で Agent (またはその前段のゲートウェイ) を公開します。

logs_enabled: trueotlp_config:  receiver:    protocols:      http:        endpoint: 0.0.0.0:4318  logs:    enabled: true

環境変数での設定は DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT=0.0.0.0:4318、DD_LOGS_ENABLED=true、DD_OTLP_CONFIG_LOGS_ENABLED=true です。ポート 4318 を公開するか、443 で TLS を終端して 4318 にプロキシします。

Cherri Code では、ベース URL はそのリスナーの前段にある公開 https:// エンドポイントです。ゲートウェイで必要な場合にのみ DD-API-KEY または site ヘッダーを追加してください。Agent にはすでにローカルで api_key が設定されています。

Agent の設定の詳細については、Datadog Agent での OTLP 取り込みを参照してください。

Databricks とデータウェアハウス型の送信先

Databricks や ClickHouse などのデータウェアハウス送信先では、OTLP HTTP レシーバーとベンダーエクスポーターを備えた collector を実行するか、HTTP 経由で取り込みパイプラインに転送します。Cherri Code 側の設定は同じです。/v1/metrics と /v1/logs で protobuf を提供する HTTPS ベース URL を使用します。メトリクスは デルタ の合計として処理し、ログは cursor.event.id で重複排除します。

有効化

チーム設定 > OpenTelemetry エクスポート で:

1. ベース URL (/v1/... は不要。Cherri Code がパスを追加します) と認証ヘッダーを指定して送信先を作成
2. URL と認証を確認するために接続をテスト
3. 有効化。約 1 分以内にエクスポートが開始されます。

各シグナルとテレメトリファミリーにはそれぞれトグルがあります。auto_enable_new_families をオフにしない限り、新しいファミリーはデフォルトで有効になります。唯一の例外は 会話コンテンツ で、有効にするまでオフのままです。

会話コンテンツ

conversation_content ファミリーは、ユーザープロンプトとアシスタントのレスポンスのテキストを cursor.conversation.user_message および cursor.conversation.assistant_message ログとしてcollectorにストリーミングします。また、Grok Bot の MCP ツール呼び出しの引数と結果も cursor.conversation.tool_io ログとしてストリーミングします。現時点で対象となるのは Cloud Agents と Grok Bot のみで、IDE、CLI、デスクトップの会話はまだこのファミリーに対応していません。メッセージ本文やツールのペイロードを含むのは、このファミリーだけです。レコードの構造については Wire Reference を参照してください。

チームのオプトインと Conversation content を有効にすると、次のデータが送信されます。

• 2 種類のログイベント。 cursor.conversation.user_message にはユーザープロンプト、cursor.conversation.assistant_message には最終的なアシスタントのレスポンスが含まれます。ロールはイベント名で識別され、本文にはメッセージ本文が入ります。
• スクラブと上限。 Cherri Code はエクスポート前にメッセージ本文をスクラブし、各メッセージの本文を 32 KiB までに制限します。エクスポートされた本文がマスキング済みテキストの先頭部分のみである場合、cursor.conversation.content_truncated が true になります。
• Tool I/O は別扱い。 トグルを有効にすると、cursor.conversation.tool_io により Grok Bot の MCP 呼び出しの引数と結果が追加されます (入力・出力それぞれ 8 KiB まで)。詳しくは MCP tool I/O を参照してください。
• 他のログと同じ識別情報。 レコードには、任意の cursor.user.* リソース属性 を含め、他のすべてのログと同じ ID が含まれます。
• Cloud Agents と Grok Bot のみ。 Cloud Agent の会話は cursor.surface=cloud_agent、Grok Bot の会話は cursor.surface=grok_bot として送信されます。IDE、CLI、デスクトップの会話は、このファミリーではまだエクスポートされません。Grok Bot のメッセージは grok_bot_agent_actions ファミリーとは別物です。こちらはアクション記録が必要で、メッセージではなくアクションを含みます。

MCP tool I/O

cursor.grok_bot.mcp_tool_call ログは、Bot が MCP 呼び出しを行ったことを示します。記録されるのは、どのサーバーのどのツールを呼び出したか、成功したかどうか、所要時間です。Bot が送信した内容や返された内容は含まれないため、レビュアーは Jira の移行が行われたことは確認できても、どの課題がどの状態に移ったかまではわかりません。その内容を含むのが cursor.conversation.tool_io で、送信先の Tool I/O トグルで有効にできます。

有効にする前は、Bot の Jira 呼び出しは collector 上で cursor.grok_bot.mcp_tool_call の 1 行として記録されます。この行の cursor.tool.name には移行ツール名が、cursor.tool.status には success が入ります。有効にすると、同じ呼び出しから cursor.conversation.tool_io の行が 2 行追加で生成されます。direction=arguments の行には、課題キーや移行先のステータスなど、Bot が送信した JSON が含まれます。direction=result の行には Jira が返した内容が含まれます。3 行は cursor.grok_bot.tool_call.id で結合します。

対象範囲と制限:

• 完全なペイロードではなく抜粋。 上限は送信・受信それぞれ 8 KiB です。切り詰められた本文はマスキング済みテキストの先頭部分で、cursor.conversation.content_truncated のフラグが付き、JSON としてはパースできません。書き込み呼び出しの先頭部分(オブジェクトキー、ターゲット、新しい値)は収まりますが、長い読み取り結果は切り詰められます。
• 結果のコンテンツ。 成功時、結果レコードにはツールのテキストと構造化コンテンツが含まれます。失敗時には、エラー、拒否、または却下のメッセージが含まれます。画像のバイトデータは Cherri Code によって MIME タイプに置き換えられます。
• シークレットのマスキング(ベストエフォート)。 Cherri Code は、shell command やメッセージ本文と同じパターンベースのスクラバーを実行します。既知の認証情報の形式、PEM ブロック、メールアドレスは [REDACTED: ...] マーカーに置き換えられるため、assignee のアドレスは [REDACTED: Email] としてエクスポートされます。また、キー名が認証情報を示す JSON メンバー(password、token、api_key など。一覧は Wire Reference を参照)の値は、形式にかかわらずマスキングされます。ただし、パターンマッチングですべてのシークレットや個人データを検出できるわけではありません。一覧にないキーに格納された認証情報、複数のフィールドに分割された認証情報、一般的でないメンバー名を持つヘッダー行({"k":"Authorization","v":"Basic ..."})内の認証情報は、そのままエクスポートされます。チームメイトのメッセージを引用した引数や、コネクタのレスポンス本文を含む結果も同様です。プロンプトやレスポンスと同じく、こうした残存リスクはチームの責任で管理してください。
• ホスト型コネクタの呼び出しのみ。 ツールの I/O が生成されるのは、Cherri Code が実行する Grok Bot の MCP 呼び出し(Jira、Slack、Linear などのホスト型サーバー。これらの mcp_tool_call 行には cursor.grok_bot.mcp.transport=http が表示されます)のみです。Bot のコンピューター上の stdio サーバー、組み込みツール、および Cloud Agent、IDE、CLI のツール呼び出しは、現時点ではペイロードを報告しません。

Cherri Code がエクスポートする内容

スコープ: cursor.telemetry 0.1.0。

conversation_content を除き、以下はすべて新しい送信先でデフォルトで有効になります。個別のファミリーはチーム設定で無効にします。

メトリクス (デルタ累積方式)

• cursor.token.usage: cursor.token.type (input / output / cache_read / cache_creation) 別
• cursor.tool.calls: 組み込みツールおよび MCP (cursor.tool.kind)
• cursor.cost.usage: ベストエフォートの米ドル費用。請求書ではありません

ログ

• cursor.api.request: モデル呼び出しの概要
• cursor.api.error: エラーイベント (raw メッセージは含まれません)
• cursor.api.correction: 請求の確定。cursor.usage_event.id で結合
• cursor.skill.activated
• cursor.hook.execution_complete
• cursor.plugin.installed
• cursor.cloud_agent.setup: started / completed / failed
• cursor.cloud_agent.artifact
• cursor.cloud_agent.pull_request: opened / creation_failed
• cursor.cloud_agent.mcp_auth_error: MCP サーバーが実行の認証情報を拒否しました
• cursor.grok_bot.tool_result: Bot が行ったすべての組み込みツール呼び出しと、その結果および所要時間
• cursor.grok_bot.tool_decision: Bot のツール呼び出しを許可または拒否した主体 (人、Auto-review、フック、またはゲートなし)
• cursor.grok_bot.mcp_tool_call: Bot コネクタ (MCP) のツール呼び出し
• cursor.grok_bot.shell_command: Bot の shell コマンド (シークレットは除去済み)。終了コードと所要時間を含む
• cursor.grok_bot.browser_navigation: Bot のブラウザが遷移したページ
• cursor.grok_bot.computer_use_session: Bot の Computer use セッションの概要
• cursor.grok_bot.file_transfer: Bot のコンピューターとユーザーのマシンまたはクラウドアカウントの間で移動されたファイル
• cursor.grok_bot.message_delivery: Bot が送信したメッセージ、その送信先、および到達したかどうか
• cursor.grok_bot.routine_run: 完了したルーチンの実行
• cursor.grok_bot.guardrail: ループの検出、サイトによる Bot のブロック、または承認リクエストとその待機
• cursor.grok_bot.delegation: Bot がサブエージェントまたは Cloud Agent に委任した作業と、返ってきた結果
• cursor.conversation.user_message: ユーザーのプロンプト (スクラブ済み)。オプトイン
• cursor.conversation.assistant_message: アシスタントのレスポンス (スクラブ済み)。オプトイン
• cursor.conversation.tool_io: Grok Bot の MCP ツール呼び出しの入力または出力のいずれか (引数または結果、スクラブ済み)。オプトイン

cursor.grok_bot.* イベント、および Bot がスキルを読み込んだ際の cursor.skill.activated は、アクション記録 のデータを含みます。これらはチーム管理者がダッシュボードの Grok Bot ページでアクション記録を有効にした後にのみ送信されます。アクション記録はチーム設定で、デフォルトでは無効です。また、プライバシーモード (Legacy) では強制的に無効になります。

記録されるイベントは Bot が行った操作のメタデータであり、扱ったコンテンツそのものは含まれません。ツールの引数と結果、ファイルパスと名前、メッセージ本文と受信者、認証情報、カード情報がこれらのイベントでエクスポートされることはありません。MCP の引数と結果は、オプトインの cursor.conversation.tool_io レコードとしてのみ送信されます。shell コマンドのテキストはシークレットの除去後、最大 8 KiB までエクスポートされます。ブラウザの URL からはクエリ文字列、フラグメント、認証情報が削除されます。ツールがサイトに対して操作した場合は、ホスト名のみが報告されます。イベントごとのすべての属性は Wire Reference に記載されています。

cursor.conversation.* イベントはメッセージ本文またはツールのペイロードを含むため、チームがオプトインし、かつ送信先で該当する種類のトグルが有効になっている場合にのみ送信されます。会話コンテンツ および MCP tool I/O を参照してください。

ファミリー (管理者用トグル、conversation_content を除きすべてデフォルトで有効)

• model_usage: トークンおよびコストのメトリクス、api.request / api.error / api.correction
• tool_calls: tool.calls メトリクス
• skills_hooks_plugins: skill / hook / plugin ログ (Bot のスキル有効化を含む)
• cloud_agents: cloud_agent.* ログ
• grok_bot_agent_actions: grok_bot.* アクションログ。アクション記録が必要です (エンタープライズ)
• conversation_content: conversation.* メッセージおよびツール I/O ログ。デフォルトでは無効

主な属性

• リソース: service.name=cursor、cursor.team.id、Surface/エントリポイント、および任意の cursor.user.id、cursor.user.account_id、cursor.user.email。レコードを個人に紐付ける方法については セッションの結合 を参照してください。Grok Bot のトラフィックはすべてのファミリーで cursor.surface=grok_bot としてエクスポートされ、desktop には含まれなくなりました。ルーチンによって開始されたターンは cursor.entrypoint=automation としてエクスポートされます。
• ログ: cursor.event.id (重複排除) 、および存在する場合は cursor.request.id / cursor.conversation.id / cursor.usage_event.id
• Grok Bot ログ: cursor.grok_bot.turn.id、cursor.grok_bot.event.sequence、cursor.grok_bot.tool_call.id、cursor.grok_bot.decision.id。セッションの結合 を参照してください

配信

• メトリクスは最大1回配信されます。障害発生後、デルタの合計値に一時的な欠損が生じる場合があります。
• ログは少なくとも1回配信されます。正確に1回のビューを実現するには、cursor.event.idで重複を排除してください。
• 送信先の作成前のデータはバックフィルされません。
• エンドポイントまたは認証情報を編集しても、送信先は維持されます。無効化または削除すると、転送中のデータは破棄されます。

認証

Cherri Code はヘッダーを暗号化して保存します。認証情報をローテーションするには、送信先を編集して保存します。変更は約30秒で反映されます。

制限事項

• コストは請求額ではありません。 cursor.cost.usage はベストエフォートによる推定値です。1 つの系列で、付属クォータの消費とオンデマンド利用の両方をカバーします。BYOK では、プロバイダーの利用料金ではなく、Cherri Codeトークンレートのみを反映します。請求書については、Admin API と請求 API を使用してください。
• 送信先を無効にするか削除すると、転送中のデータは失われます。 削除して再追加するのではなく、送信先を編集して認証情報をローテーションしてください。
• ログは複数回届くことがあります。 配信は少なくとも 1 回保証されます。cursor.event.id で重複排除してください。
• オプトインしない限り、プロンプトの内容やツールのペイロードは含まれません。 メッセージ本文と MCP ツールの引数および結果は、オプトイン方式の conversation_content ファミリーを通じてのみ送信されます。その他のログイベントには ID、カウント、低カーディナリティの属性が含まれます。会話コンテンツおよび MCP ツールの I/O を参照してください。
• トレースコンテキストや履歴データのバックフィルはありません。 エクスポートされるログには OpenTelemetry の trace_id や span_id フィールドは含まれず、Cherri Code はトレースを送信しません。エクスポートは送信先を有効にすると開始されます。
• メトリクスのデータポイントには相関 ID が含まれません。 会話単位で結合するには、ログ属性を使用してください。セッションの結合を参照してください。
• メトリクスはデルタのみです。 系列ごとにデルタを合計してください。厳密なデルタから累積値への変換プロセッサでは、終了時刻が開始時刻より前のポイントが破棄される場合があります。

セッションの結合

メトリクス (cursor.token.usage、cursor.tool.calls、cursor.cost.usage) は集計値です。データポイントには conversation.id、request.id、usage_event.id は含まれません。これにより、メトリクスのカーディナリティを抑えています。セッション単位またはリクエスト単位で分析するには、ログを使用してください。

各 ID の意味

• cursor.conversation.id はセッションキーです。IDE と CLI では composer チャットの UUID です。Cloud Agent では、顧客に表示される bc-... エージェント ID です。Grok Bot (grok_bot.*、および cursor.surface=grok_bot を含むすべてのログ) では Bot の識別子であり、この値がそのまま Bot の会話 ID になります。存在する場合、同じ値がその実行の api.request、api.error、skill.activated、hook.execution_complete、cloud_agent.*、grok_bot.*、および (チームがオプトインしている場合は) conversation.* ログにも含まれます。
• cursor.usage_event.id は、api.request、api.error、api.correction におけるリクエスト単位のキーです。Cherri Code の利用状況および請求エクスポートとの照合や、修正の適用に使用します。
• cursor.request.id は、ほとんどのログに含まれる任意の呼び出しごとの ID です。api.correction、cloud_agent.*、grok_bot.* には含まれません。
• cursor.event.id は重複排除専用のキーであり、イベントタイプをまたいで結合するためのキーではありません。

レコードを個人に関連付ける

cursor.user.account_id はメンバーの Admin API ID です。これを GET /teams/members のレスポンスに含まれる id と結合すると、レコードに対応する人物を特定できます。cursor.user.email でメンバーを直接特定できます。どちらも任意で、cursor.user.id がある場合にのみ含まれるため、すべてのレコードに存在することを前提にしないでください。存在条件については リソース属性 の表を参照してください。

Grok Bot のアクティビティをグループ化する

Bot のレコードは 4 つの属性で相互に関連付けられます。cursor.grok_bot.turn.id はターンを識別します。この属性はそのターンのすべてのアクション記録ログに含まれ、cursor.surface=grok_bot の場合はそのターンの api.request および api.error ログにも含まれるため、モデル呼び出しとアクションをターン単位で結合できます。ターン内では、cursor.grok_bot.event.sequence を使うと、クライアントの時計に依存せずにアクションを順序付けられます。タイムスタンプではなくこの値で並べ替えてください。なお、値が連番になるとは限りません。cursor.grok_bot.tool_call.id は 1 つのツール呼び出しの行をグループ化し、cursor.grok_bot.decision.id は承認依頼、その待機、およびユーザーの回答を結び付けます。

サブエージェントのアクションには、独自の cursor.grok_bot.turn.id と cursor.grok_bot.subagent.id に加え、サブエージェントが処理するユーザー向けのターンを示す cursor.grok_bot.root_turn.id が含まれます。root_turn.id でグループ化すると、サブエージェントのアクションを生成元のターンにロールアップできます。

たとえば、Bot が実行したコマンドを Auto-review がユーザーにエスカレーションしたターンでは、次のようなレコードが生成されることがあります。

すべての行は Bot の cursor.conversation.id を共有します。turn-1 でグループ化すると、モデル呼び出しを含むターン全体を再構成できます。call-7 でグループ化すると、1 つのシェル呼び出しの流れを追跡できます。この例では、Auto-review が呼び出しを拒否し、カードでユーザーに確認が求められ、ユーザーが許可した後、ツールが実行されて success が返されています。card-2 は、確認とその待機を回答に結び付けます。コマンドのテキスト自体はターンの cursor.grok_bot.shell_command 行に記録されており、この行には tool_call.id は含まれません。これらのフィールドはカスタムのログ属性であり、OpenTelemetry のトレース ID やスパン ID ではありません。

会話コンテンツを有効にすると、Bot の cursor.conversation.user_message ログと cursor.conversation.assistant_message ログにも同じ cursor.conversation.id が含まれます。この ID で結合すると、プロンプトとレスポンスを Bot のモデルリクエストや記録されたアクションと並べて確認できます。メッセージログには、独自の任意項目である cursor.conversation.turn.id が含まれます。これらのログの cursor.grok_bot.turn.id や cursor.request.id には依存しないでください。

MCP tool I/O を有効にすると、MCP 呼び出しごとに 2 つの cursor.conversation.tool_io ログ(direction=arguments と direction=result)が追加されます。これらのログには、その呼び出しの cursor.grok_bot.tool_call.id と、存在する場合は turn.id および event.sequence が含まれます。tool_call.id でグループ化すると、引数と結果を、その呼び出しの mcp_tool_call 行、tool_decision 行と並べて確認できます。

レシピ: トークン数でセッションをランク付けし、スキルとツールを紐付ける

1. cursor.api.request のログ行を取得します。cursor.conversation.id でグループ化し、cursor.api.request.input_tokens と output_tokens(必要に応じてキャッシュ関連のフィールドも)を合計します。これにより、メトリクスでは得られないセッションごとのトークン合計を算出できます。
2. その合計値、または推定コストで会話をランク付けします。
3. 同じ cursor.conversation.id をキーに、他のログを左結合します:
   • cursor.skill.activated: 実行されたスキル
   • cursor.hook.execution_complete: フック
   • cursor.cloud_agent.*: セットアップ、プルリクエスト、アーティファクト、MCP 認証エラー(Cloud Agents のみ)
   • cursor.grok_bot.*: Bot の実行内容(Grok Bot のみ、アクション記録が有効な場合)
   • cursor.conversation.user_message と cursor.conversation.assistant_message: プロンプトとレスポンス(Cloud Agents と Grok Bot、conversation_content をオプトインした場合のみ)
   • cursor.conversation.tool_io: Grok Bot の各 MCP 呼び出しで送受信された内容(Grok Bot のみ、tool I/O をオプトインした場合に限る)
4. cursor.tool.calls はメトリクス専用のため、会話 ID を持ちません。組織全体のツール利用率はメトリクスから集計してください。Grok Bot では、cursor.grok_bot.tool_result と cursor.grok_bot.mcp_tool_call により、Bot ごと・ターンごとにツールの利用を紐付けられます。その他のサーフェスでは、この情報はまだ送信されていません。

cursor.cost.usage もメトリクス専用です。コストでセッションをランク付けするには、api.request のトークン合計と自社の料金から概算するか、Admin API と請求 API から支出を取得し、可能な場合は cursor.usage_event.id で結合してください。

レシピ: 請求の訂正を適用する

1. cursor.api.correction ログを探します。
2. cursor.usage_event.id をキーに、同じ ID を持つ api.request ログと api.error ログを結合します。
3. そのグループ全体を請求対象外として扱います。

注意事項

• サブエージェントには独自の会話 ID が割り当てられます。Grok Bot のアクションは cursor.grok_bot.root_turn.id で親に集約できます。その他のサーフェスでは、親への集約に必要な情報はまだエクスポートされていません。
• 正確に1回のビューが必要な場合は、結合前に cursor.event.id でログ行の重複を排除してください。
• 古いバージョンの Grok Bot のレコードには、cursor.grok_bot.event.sequence と cursor.grok_bot.initiated_by が含まれません。どちらも任意項目として扱ってください。

変更ポリシー

カバレッジの拡大に伴い、新しいメトリクスやイベントが追加される場合があります。auto_enable_new_families は、それらを自動的に有効にするかどうかを制御します。名称変更や削除は明示的に通知されます。Wire Referenceには、すべての属性サーフェスが記載されています。