mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-28 19:35:27 +08:00
docs(telemetry): document route eligibility and execution reporting
This commit is contained in:
Hyu
+21
-5
@@ -496,20 +496,36 @@ space:
|
||||
disable_telemetry: true
|
||||
```
|
||||
|
||||
This switch disables query statistics, heartbeat and execution telemetry, as well as survey fetching. Use an unquoted YAML boolean. To restore the default, set it to `false` and restart.
|
||||
This switch disables product telemetry (including heartbeats and execution records) and survey fetching. Use an unquoted YAML boolean. To restore the default, set it to `false` and restart. Cloud Plugin Runtime operational health reporting is controlled separately by `plugin.runtime_ops.enabled`.
|
||||
|
||||
If `SPACE__DISABLE_TELEMETRY` is set in your deployment, it overrides the file at startup; update or remove it too. Recreate containers when changing their environment. In Cloud, the instance operator controls this setting for every Workspace in the instance. It does not disable the bot or change privacy settings of messaging platforms, model providers or plugins.
|
||||
|
||||
### Per-event execution chains
|
||||
|
||||
Execution telemetry also reports sampled per-event chains (one inbound platform event from its source through routing and processing to the platform API calls it caused). Tune the sampling in the same `space` section:
|
||||
Current 4.11 execution telemetry defaults to full reporting of eligible executions, covering platform events, routing, Pipeline / Agent / plugin event processors, and the platform API and tool calls they cause. Each completed node generates a record, followed by a closure record when the execution ends; Space reconstructs the chain. These are the defaults in the same `space` section; restart after changing them:
|
||||
|
||||
Platform events without a matching business route, or ignored by a `discard` rule with no matching plugin subscription, upload no execution records. Local logs and monitoring keep their existing behavior. Matching subscriptions, valid interaction resumptions and independent WebUI/API/Pipeline calls remain eligible, as do unavailable targets, execution failures or Pipeline filtering after a route matches. Eligibility is checked before sampling; neither Cloud's `all` nor failure fallback bypasses it. A Core upgrade is required.
|
||||
|
||||
```yaml
|
||||
space:
|
||||
execution_trace: sampled # off | failures | sampled | all
|
||||
execution_trace_sample: 20 # with 'sampled': keep every N-th successful chain
|
||||
execution_trace: all # off | failures | sampled | all
|
||||
execution_trace_sample: 20 # sampled: retain about 1/N successful executions by event hash
|
||||
telemetry_flush_seconds: 180 # Execution record buffer flush interval, in seconds
|
||||
```
|
||||
|
||||
`failures` keeps only chains that contain a failed, cancelled or timed-out stage. `off` disables chains while window counters continue. WebUI debug runs are always kept and remain flagged as synthetic. Chains share the 30-day retention of execution records.
|
||||
The community edition supports these modes:
|
||||
|
||||
| Mode | Reporting behavior |
|
||||
|---|---|
|
||||
| `all` | Default; records nodes and closure records for every eligible execution |
|
||||
| `sampled` | Makes one stable hash decision from the event identity for all records of that execution; excluded executions that fail still report a closure, without recovering skipped nodes |
|
||||
| `failures` | Omits nodes for ordinary executions; reports closures only for failure, cancellation, timeout or a recorded chain failure reason |
|
||||
| `off` | Reports neither nodes nor closures; no independent window counters continue, while heartbeats remain controlled by `disable_telemetry` |
|
||||
|
||||
WebUI debug runs are retained with a debug flag in `all`, `sampled` and `failures`; `off` or `disable_telemetry: true` stops their upload. **Cloud always uses `all` while product telemetry is enabled and does not apply the sampling mode configured above**; the instance operator can still disable product telemetry with the main switch.
|
||||
|
||||
`execution_trace_sample` accepts integers from 1 to 100000; `telemetry_flush_seconds` accepts integers from 1 to 86400. Invalid values fall back to 20 and 180 respectively, and an invalid mode falls back to `all`. Sampling does not select exactly every N-th execution in sequence.
|
||||
|
||||
Each flush sends at most 128 records and the buffer holds at most 512. Failed sends remain buffered for retries; a full buffer drops the oldest records, so full reporting does not guarantee complete delivery. Active Workspaces first send a heartbeat about 30 seconds after startup, then daily in ordinary deployments or every 5 minutes in Cloud runtime. Raw execution records are cleaned up in batches using a 30-day window; backlogs can delay deletion.
|
||||
|
||||
See [Data Collection Policy](../insight/data-collection-policy).
|
||||
|
||||
@@ -1,45 +1,62 @@
|
||||
---
|
||||
title: "Data Collection Policy"
|
||||
description: "Optional telemetry, execution observations and opt-out controls"
|
||||
description: "Optional telemetry, execution chains, collected data and opt-out controls"
|
||||
---
|
||||
|
||||
LangBot sends telemetry to the configured LangBot Space service (by default `https://space.langbot.app`) to understand usage and improve reliability. **Telemetry is enabled by default and can be disabled.** Execution observations use existing telemetry rather than a separate Beta diagnostics producer.
|
||||
|
||||
## Existing product telemetry
|
||||
|
||||
When enabled, the existing query path can send:
|
||||
|
||||
| Data | Contents |
|
||||
|---|---|
|
||||
| Identity and environment | `instance_id`, `workspace_uuid`, random `query_id`, version, adapter and runner types |
|
||||
| Query statistics | Model name, duration, timestamp, pipeline plugin names |
|
||||
| Feature usage | Tool counts by source, tool-call rounds, knowledge-base and retrieved-entry counts, knowledge-engine plugin IDs, sandbox execution/error counts, activated skill names and configured MCP server names |
|
||||
| Errors | The legacy `error` field can contain a raw traceback, including exception text |
|
||||
| Managed runtime activity | `runtime_instance_id` on managed SaaS queries refreshes idle-timeout activity; it is not stored in the analytics event record |
|
||||
|
||||
Feature counters do not intentionally include tool arguments/results, retrieved text or sandbox code/output. **However, legacy exception text and user-defined model, skill or MCP names may contain sensitive information. The execution-record content restrictions do not sanitize this legacy stream.** Do not treat existing telemetry as guaranteed content-free.
|
||||
|
||||
A Workspace heartbeat is sent shortly after startup and daily for active Workspaces. It includes deployment platform, database/vector-database kinds, sandbox configuration and availability, enabled adapter types and resource counts, rather than resource contents or connection details.
|
||||
|
||||
Optional in-app surveys send the survey ID, submitted answers, instance ID, version and completion/dismissal status. Survey answers are user-provided content, not Beta diagnostics.
|
||||
LangBot sends product telemetry to the LangBot Space service configured by `space.url` (by default `https://space.langbot.app`) to understand usage and improve reliability. **Telemetry is enabled by default and can be disabled.** This page describes the current 4.11 execution telemetry protocol (`schema: 2`); older-version data is described separately below.
|
||||
|
||||
## Execution telemetry
|
||||
|
||||
Execution observations cover platform events, routing, Pipeline / Agent / plugin event processors and platform APIs. Fields include code-defined operation identifiers, adapter and runner types, processing mode, outcome, counts, first/last observation times, instance and Workspace identifiers, version and a synthetic-execution flag. Core aggregates bounded counters in memory and sends them in background tasks; Space performs coverage analysis.
|
||||
An eligible execution consists of independent records sharing an `event_id`: one `execution_node` is generated when each workflow node completes, and one `execution_chain` when the execution closes. Core buffers records within a fixed limit and uploads them in background batches; Space reconstructs the execution chain. The current sender no longer uses legacy feature window counters or assembles a complete chain locally.
|
||||
|
||||
These execution records exclude messages, prompts, model replies, platform user/group IDs, tool/API arguments or results, credentials and raw exception tracebacks. Instance and Workspace identifiers may be associated with deployments or accounts. These content restrictions apply to execution records, not to the legacy query telemetry described above.
|
||||
**Platform events without a matching business route, or whose selected route is `discard` with no matching plugin subscription, report neither nodes nor a closure.** Disabled routes and event-type/filter mismatches are included; local logs and monitoring keep their existing behavior. A matching plugin event processor still makes an execution eligible when the primary route misses. Unmatched and discarded branches do not contribute telemetry.
|
||||
|
||||
### Per-event execution chains
|
||||
After a business route matches, unavailable targets, execution failures, timeouts and filtering inside a Pipeline remain reportable. Valid interaction callbacks resuming an original processor, WebUI/API debug runs and independent calls explicitly targeting a Pipeline also remain eligible; invalid callbacks do not independently qualify. Eligibility takes precedence over sampling and failure fallback, including in Cloud. This requires a Core upgrade and does not retroactively change older clients or historical records.
|
||||
|
||||
A sampled subset of these records traces one inbound event end to end: an opaque random trace identity, the observed stages in order (platform event → routing decision → Pipeline / Agent / plugin event processor → platform API calls), each stage's outcome, the routing target identity, the Runner run identity when a Runner executed the event, and why the chain closed. Stage fields are the same code-defined identifiers as above; a routing target is reported as `type:uuid`, never as a user-defined rule name. Core keeps a bounded number of stages per chain and a bounded number of chains in memory, then drops overflow.
|
||||
| Data | Contents |
|
||||
|---|---|
|
||||
| Identity and environment | `instance_id`, `workspace_uuid`, `event_id`, version, edition, timestamp, debug flag and sampling information |
|
||||
| Execution nodes | Operation identifiers, processing mode, outcome, start/end times, parent/child relationships and sequence, routing target and Runner run identity for platform events, routing, Pipeline, Runner, platform API and tool calls |
|
||||
| Chain closure | Overall outcome, closure reason, duration, node count, nodes omitted by sampling, origin, model name, adapter, Runner and pipeline plugins |
|
||||
| Bound resources | Identifiers or names of plugins, MCP servers, knowledge bases, tools and their sources, skills, models and platform APIs granted to a Pipeline or Agent, plus selector fields, capabilities and permission flags; fields depend on the execution path |
|
||||
| Errors | Short error text with length limits and whitespace normalization, potentially including an exception class and message prefix |
|
||||
|
||||
Chains are sampled with `space.execution_trace`: `off`, `failures` (chains containing a failed, cancelled or timed-out stage), `sampled` (the default: those chains plus every N-th successful one, N = `space.execution_trace_sample`) or `all`. WebUI debug runs are always kept and remain flagged as synthetic, so they stay out of real-execution statistics.
|
||||
Bound resources describe what an execution was configured or authorized to use. **They do not establish that those resources were actually called, searched or consumed.** Routing targets use `type:uuid`, not user-defined rule names.
|
||||
|
||||
Connection failures, timeouts and server errors do not block normal operations. Failure details are logged only at DEBUG level. Queues are bounded and records may be lost during failures. Observations support analysis; a successful platform API response does not prove that a user read a message.
|
||||
Execution records do not intentionally collect message bodies, prompts, model replies, platform user/group IDs, tool/API arguments or results, credentials or complete exception tracebacks. **Truncating error text is not reliable redaction: exception prefixes and user-defined model, skill or resource names may still contain sensitive information.** Instance and Workspace identifiers may be associated with deployments or accounts; these records are neither anonymous nor guaranteed to contain no user content.
|
||||
|
||||
### Sampling and debug runs
|
||||
|
||||
The community edition controls execution reporting with `space.execution_trace`:
|
||||
|
||||
| Mode | Behavior |
|
||||
|---|---|
|
||||
| `all` (default) | Records nodes and closure records for every eligible execution |
|
||||
| `sampled` | Makes one stable hash decision from the event identity at ingress; retains approximately `1/N` successful executions, where N is `space.execution_trace_sample` (default 20); every record of an execution shares the decision |
|
||||
| `failures` | Omits nodes for ordinary executions and reports a closure only for failure, cancellation, timeout or a recorded chain failure reason |
|
||||
| `off` | Disables node and closure records; no independent window counters continue, while Workspace heartbeats remain controlled by the main telemetry switch |
|
||||
|
||||
If an execution excluded by `sampled` fails, its closure is still reported. Previously skipped nodes are not recovered, so a failure may have a summary without a complete chain. WebUI debug runs are retained in `all`, `sampled` and `failures` with a debug flag; neither `off` nor the main opt-out permits their upload.
|
||||
|
||||
**Cloud always uses `all` while product telemetry is enabled**, so sampling successful executions does not distort activity counts. The instance operator can still disable the product telemetry described here with `space.disable_telemetry`.
|
||||
|
||||
### Delivery and completeness
|
||||
|
||||
Records are sent to `POST /api/v1/telemetry`. The default flush interval is 180 seconds, configurable through `space.telemetry_flush_seconds`. Each flush sends at most 128 records and the memory buffer holds at most 512. Records are removed only after an accepted send; failed sends are retried, and a full buffer drops the oldest records. Shutdown attempts to flush remaining records within a limited time.
|
||||
|
||||
Network failures, timeouts and server errors do not fail business execution because telemetry failed; upload failure details are logged at DEBUG level. Sampling, buffer overflow, process exit or expired cross-task associations can leave incomplete chains. **Full reporting does not guarantee complete delivery.** A successful platform API response does not prove that a user read a message.
|
||||
|
||||
## Heartbeats, surveys and older-version data
|
||||
|
||||
Active Workspaces first send an `instance_heartbeat` about 30 seconds after startup. Ordinary deployments send daily thereafter; Cloud runtime refreshes every 5 minutes. Heartbeats include deployment platform, database/vector-database kinds, sandbox configuration and availability, adapter types and counts of resources such as bots, Pipelines, plugins, Agents, event processors, event bindings, MCP servers, knowledge bases and skills. They do not intentionally include resource contents or connection credentials.
|
||||
|
||||
Optional in-app surveys send the survey ID, submitted answers, instance ID, version and completion/dismissal status. Survey answers are content voluntarily provided by users.
|
||||
|
||||
Space remains compatible with older `query` and `feature_execution` data. Legacy query records may contain model names, feature counters, user-defined skill/MCP names and raw traceback text. The current execution-record restrictions neither sanitize historical data nor change uploads from older clients still running.
|
||||
|
||||
## Storage and retention
|
||||
|
||||
Data is stored by the configured Space service. Raw execution records are periodically removed in bounded batches using a 30-day retention window; backlogs or service interruptions can delay deletion. This does not change retention for legacy query telemetry, surveys, accounts or service logs. Coverage analysis is restricted to authorized telemetry management users or service clients.
|
||||
Data is stored by the configured Space service. Execution lists, chain details and summaries are restricted to authorized telemetry management users or service clients. Raw `execution_node`, `execution_chain` and legacy `feature_execution` records are periodically removed in bounded batches using a 30-day retention window; backlogs or service interruptions can delay deletion. This does not change retention for legacy query telemetry, heartbeats, surveys, accounts or service logs.
|
||||
|
||||
Opting out stops future reporting but does not delete existing server records. For historical data requests, contact [[email protected]](mailto:[email protected]) or your Space administrator.
|
||||
|
||||
@@ -52,8 +69,10 @@ space:
|
||||
disable_telemetry: true
|
||||
```
|
||||
|
||||
This switch disables query statistics, heartbeat and execution telemetry, as well as survey fetching. Use an unquoted YAML boolean. To restore the default, set it to `false` and restart.
|
||||
This switch disables the product telemetry described on this page and survey fetching. Use an unquoted YAML boolean. To restore the default, set it to `false` and restart.
|
||||
|
||||
If `SPACE__DISABLE_TELEMETRY` is set in your deployment, it overrides the file at startup; update or remove it too. Recreate containers when changing their environment. In Cloud, the instance operator controls this setting for every Workspace in the instance. It does not disable the bot or change privacy settings of messaging platforms, model providers or plugins.
|
||||
|
||||
Cloud Plugin Runtime operational health reporting is separate from product telemetry. It is controlled by `plugin.runtime_ops.enabled` and is not disabled by `space.disable_telemetry`.
|
||||
|
||||
See [System Settings](../deploy/settings).
|
||||
|
||||
+21
-5
@@ -408,20 +408,36 @@ space:
|
||||
disable_telemetry: true
|
||||
```
|
||||
|
||||
このスイッチはクエリ統計、ハートビート、実行テレメトリ、およびアンケート取得を無効にします。引用符を付けず YAML の真偽値を使用してください。既定の有効状態に戻すには `false` に変更し、再起動します。
|
||||
このスイッチは製品テレメトリ（ハートビートと実行記録を含む）およびアンケート取得を無効にします。引用符を付けず YAML の真偽値を使用してください。既定の有効状態に戻すには `false` に変更し、再起動します。Cloud の Plugin Runtime 運用状態の送信は、別の設定 `plugin.runtime_ops.enabled` で制御します。
|
||||
|
||||
環境変数 `SPACE__DISABLE_TELEMETRY` が設定されている場合、起動時にファイルの設定を上書きするため、併せて変更または削除してください。コンテナの環境変数を変更する場合はコンテナを再作成します。Cloud ではインスタンスの運用者が設定し、そのインスタンスの全ワークスペースに適用されます。Bot の動作や、メッセージングプラットフォーム、モデル提供者、プラグイン自体のプライバシー設定は変更しません。
|
||||
|
||||
### イベント単位の実行チェーン
|
||||
|
||||
実行テレメトリは、サンプリングしたイベント単位のチェーン（受信した 1 つのプラットフォームイベントが、発生元からルーティング、処理、その結果生じたプラットフォーム API 呼び出しに至るまで）も報告します。サンプリングは同じ `space` セクションで調整します。
|
||||
現在の 4.11 は、送信条件を満たす実行について、プラットフォームイベント、ルーティング、Pipeline / Agent / プラグインのイベントプロセッサー、およびそこから生じるプラットフォーム API とツール呼び出しを、既定で全件記録します。ノード完了ごとに記録を生成し、実行終了時に終了記録を生成します。Space がチェーンを再構成します。同じ `space` セクションでの既定値は以下のとおりです。変更後は再起動してください。
|
||||
|
||||
業務ルートに一致しない、または `discard` ルールで無視され、一致するプラグイン購読もないプラットフォームイベントは、実行記録を送信しません。ローカルのログと監視は従来どおりです。一致する購読、有効な対話の再開、独立した WebUI/API/Pipeline 呼び出しは送信対象です。ルート一致後の対象利用不可、実行失敗、Pipeline 内部のフィルタリングも対象です。この判定はサンプリングより優先し、Cloud の `all` や失敗時の送信でも迂回できません。Core の更新が必要です。
|
||||
|
||||
```yaml
|
||||
space:
|
||||
execution_trace: sampled # off | failures | sampled | all
|
||||
execution_trace_sample: 20 # sampled の場合：成功したチェーンの N 件に 1 件を保持
|
||||
execution_trace: all # off | failures | sampled | all
|
||||
execution_trace_sample: 20 # sampled：イベントのハッシュで成功した実行の約 1/N を保持
|
||||
telemetry_flush_seconds: 180 # 実行記録バッファの送信間隔（秒）
|
||||
```
|
||||
|
||||
`failures` は失敗・キャンセル・タイムアウトした段階を含むチェーンのみを保持します。`off` はチェーンを無効にしますが、集計カウンターは継続します。WebUI のデバッグ実行は常に保持され、模擬実行として記録されます。チェーンの保持期間は実行記録と同じ 30 日です。
|
||||
コミュニティ版のモードは以下のとおりです。
|
||||
|
||||
| モード | 送信動作 |
|
||||
|---|---|
|
||||
| `all` | 既定値。送信条件を満たすすべての実行のノードと終了記録を記録します |
|
||||
| `sampled` | イベント識別子の安定したハッシュで一度だけ判定し、同じ実行の全記録が判定を共有します。対象外の実行が失敗した場合も終了記録は送信しますが、省略したノードは復元しません |
|
||||
| `failures` | 通常の実行ではノードを保持せず、失敗・キャンセル・タイムアウト、またはチェーンの失敗理由がある場合の終了記録のみを送信します |
|
||||
| `off` | ノードと終了記録を送信せず、独立した集計カウンターの送信も継続しません。ハートビートは `disable_telemetry` に従います |
|
||||
|
||||
WebUI のデバッグ実行は `all`、`sampled`、`failures` ではデバッグフラグ付きで保持します。`off` または `disable_telemetry: true` では送信しません。**Cloud は製品テレメトリが有効な場合、常に `all` を使用し、上記のサンプリングモード設定を適用しません。** インスタンス運用者は全体のスイッチで製品テレメトリを無効にできます。
|
||||
|
||||
`execution_trace_sample` は 1–100000、`telemetry_flush_seconds` は 1–86400 の整数を受け付けます。無効な値はそれぞれ 20 と 180 に、無効なモードは `all` に戻ります。サンプリングは実行順に正確に N 件ごとに選ぶ方式ではありません。
|
||||
|
||||
1 回の送信は最大 128 件、バッファは最大 512 件です。送信失敗時は記録を保持して再試行し、満杯になると最も古い記録を破棄するため、全件記録でも完全な到達は保証されません。アクティブなワークスペースは起動約 30 秒後に最初のハートビートを送信し、その後、通常のデプロイでは毎日、Cloud runtime では 5 分ごとに送信します。実行の生データは 30 日の保持期間に基づきバッチで削除しますが、滞留で削除が遅れる場合があります。
|
||||
|
||||
[データ収集ポリシー](../insight/data-collection-policy)も参照してください。
|
||||
|
||||
@@ -1,45 +1,62 @@
|
||||
---
|
||||
title: "データ収集ポリシー"
|
||||
description: "任意のテレメトリ、実行記録と無効化の方法"
|
||||
description: "任意のテレメトリ、実行チェーン、収集範囲と無効化の方法"
|
||||
---
|
||||
|
||||
LangBot は利用状況の把握と信頼性の改善のため、設定された LangBot Space サービス（既定は `https://space.langbot.app`）にテレメトリを送信します。**既定で有効ですが、無効にできます。** 実行記録は既存のテレメトリを利用し、独立した Beta 診断の送信機能は使用しません。
|
||||
|
||||
## 既存の製品テレメトリ
|
||||
|
||||
有効な場合、既存のクエリ処理経路から次のデータが送信されることがあります。
|
||||
|
||||
| データ | 内容 |
|
||||
|---|---|
|
||||
| 識別子と環境 | `instance_id`、`workspace_uuid`、ランダムな `query_id`、バージョン、アダプターとランナーの種類 |
|
||||
| クエリ統計 | モデル名、処理時間、タイムスタンプ、パイプラインプラグイン名 |
|
||||
| 機能利用 | 呼び出し元別のツール呼び出し数、ツール呼び出しラウンド数、ナレッジベースと検索結果の件数、ナレッジエンジンプラグイン ID、サンドボックス実行/エラー数、有効化したスキル名、設定された MCP サーバー名 |
|
||||
| エラー | 旧 `error` フィールドには、例外メッセージを含む生の traceback が入ることがあります |
|
||||
| マネージド実行環境の活動 | マネージド SaaS クエリの `runtime_instance_id` はアイドルタイムアウトの活動更新に使用され、分析イベントレコードには保存されません |
|
||||
|
||||
機能カウンターは、ツールの引数/結果、検索テキスト、サンドボックスのコード/出力を意図的に含めません。**ただし、旧方式の例外テキストやユーザー定義のモデル・スキル・MCP 名には機密情報が含まれる可能性があります。実行記録の内容制限は、この既存ストリームを無害化するものではありません。** 既存のテレメトリについて、ユーザーコンテンツを一切含まないとは保証できません。
|
||||
|
||||
アクティブなワークスペースは、起動直後とその後毎日ハートビートを送信します。デプロイ環境、データベース/ベクトルデータベースの種類、サンドボックス設定と可用性、有効なアダプターの種類、リソース数を含みますが、リソース内容や接続情報は含めません。
|
||||
|
||||
任意参加のアプリ内アンケートでは、アンケート ID、送信した回答、インスタンス ID、バージョン、完了/閉じた状態を送信します。回答はユーザーが提供するコンテンツであり、Beta 診断ではありません。
|
||||
LangBot は利用状況の把握と信頼性の改善のため、`space.url` で設定された LangBot Space サービス（既定は `https://space.langbot.app`）に製品テレメトリを送信します。**既定で有効ですが、無効にできます。** このページは 4.11 の現在の実行テレメトリプロトコル（`schema: 2`）を説明します。旧バージョンのデータについては後述します。
|
||||
|
||||
## 実行テレメトリ
|
||||
|
||||
プラットフォームイベント、ルーティング、Pipeline / Agent / プラグインのイベントプロセッサー、プラットフォーム API の実行を記録します。コードで定義された操作識別子、アダプターとランナーの種類、処理モード、結果、回数、最初と最後の観測時刻、インスタンスとワークスペースの識別子、バージョン、模擬実行フラグを含みます。Core は上限付きのカウンターをメモリ内で集計し、バックグラウンドで送信します。カバレッジ分析は Space が行います。
|
||||
送信条件を満たす 1 回の実行は、同じ `event_id` を持つ独立した記録で構成されます。各ワークフローノードの完了時に `execution_node`、実行の終了時に `execution_chain` を 1 件生成します。Core は上限付きバッファに記録を格納し、バックグラウンドでまとめて送信します。Space がノードから実行チェーンを再構成します。現在の送信側は、旧方式の集計カウンターやローカルでの完全なチェーン組み立てを使用しません。
|
||||
|
||||
この実行記録には、メッセージ、プロンプト、モデルの回答、プラットフォームのユーザー/グループ ID、ツール/API の引数や結果、認証情報、生の例外 traceback は含めません。インスタンスとワークスペースの識別子がデプロイ環境やアカウントに結び付く場合があります。この制限は実行記録に適用され、上記の既存クエリテレメトリの収集範囲は変更しません。
|
||||
**業務ルートに一致しない、または選択されたルートが `discard`（無視・破棄）で、一致するプラグイン購読もないプラットフォームイベントは、ノードも終了記録も送信しません。** 無効なルートやイベント種類・フィルターの不一致も対象です。ローカルのログと監視は従来どおりです。主ルートが一致しなくてもプラグインのイベントプロセッサーが一致すれば、その実行は送信対象になります。不一致・破棄の分岐はテレメトリに含めません。
|
||||
|
||||
### イベント単位の実行チェーン
|
||||
業務ルートに一致した後の対象利用不可、実行失敗、タイムアウト、Pipeline 内部のフィルタリングは引き続き送信対象です。元の処理を再開する有効な対話コールバック、WebUI/API デバッグ、Pipeline を明示的に指定した独立呼び出しも対象です。無効なコールバックだけでは送信対象になりません。この判定はサンプリングや失敗時の送信より優先し、Cloud にも適用します。Core の更新後に有効となり、旧クライアントや過去の記録は遡って変更しません。
|
||||
|
||||
サンプリングされた実行記録は、1 つの受信イベントの処理過程を順序付きで示す場合があります。推測できないランダムなチェーン識別子、観測された段階（プラットフォームイベント → ルーティング判断 → Pipeline / Agent / プラグインのイベントプロセッサー → プラットフォーム API 呼び出し）、各段階の結果、ルーティング先の識別子、実行した Runner の実行識別子、チェーンを閉じた理由です。各項目は上記と同じコード定義の識別子のみを使用し、ルーティング先は `type:uuid` 形式で報告され、ユーザー定義のルール名は使用しません。Core は 1 チェーンあたりの段階数と同時に保持するチェーン数に上限を設け、超過分は破棄します。
|
||||
| データ | 内容 |
|
||||
|---|---|
|
||||
| 識別子と環境 | `instance_id`、`workspace_uuid`、`event_id`、バージョン、エディション、タイムスタンプ、デバッグフラグ、サンプリング情報 |
|
||||
| 実行ノード | プラットフォームイベント、ルーティング、Pipeline、Runner、プラットフォーム API、ツール呼び出しの操作識別子、処理モード、結果、開始/終了時刻、親子関係と順序、ルーティング先、Runner の実行識別子 |
|
||||
| チェーン終了 | 全体の結果、終了理由、所要時間、ノード数、サンプリングで送信しなかったノード数、実行元、モデル名、アダプター、Runner、パイプラインプラグイン |
|
||||
| バインドされたリソース | Pipeline や Agent に許可されたプラグイン、MCP サーバー、ナレッジベース、ツールとその提供元、スキル、モデル、プラットフォーム API の識別子や名前、および選択フィールド、能力、権限フラグ。項目は実行経路により異なります |
|
||||
| エラー | 長さの制限と空白の正規化を行った短いエラーテキスト。例外クラスやメッセージの先頭部分を含む場合があります |
|
||||
|
||||
チェーンのサンプリングは `space.execution_trace` で設定します。`off`、`failures`（失敗・キャンセル・タイムアウトした段階を含むチェーンを保持）、`sampled`（既定。それらに加えて成功したチェーンの N 件に 1 件を保持。N = `space.execution_trace_sample`）、`all` です。WebUI のデバッグ実行は常に保持され、模擬実行として記録されるため、実際の実行統計には含まれません。
|
||||
バインドされたリソースは、その実行で使用するよう設定された、または使用が許可されたリソースです。**実際の呼び出し、検索、消費を示すものではありません。** ルーティング先は `type:uuid` 形式で報告され、ユーザー定義のルール名は使用しません。
|
||||
|
||||
接続障害、タイムアウト、サーバーエラーが通常の操作を妨げることはありません。失敗の詳細は DEBUG ログのみに記録します。キューには上限があり、障害時に記録が失われる場合があります。記録は分析の補助情報であり、プラットフォーム API の成功応答だけではメッセージが読まれたことを確認できません。
|
||||
実行記録は、メッセージ本文、プロンプト、モデルの回答、プラットフォームのユーザー/グループ ID、ツール/API の引数や結果、認証情報、完全な例外 traceback を意図的に収集しません。**ただし、エラーテキストの切り詰めは確実なマスキングではありません。例外メッセージの先頭部分やユーザー定義のモデル・スキル・リソース名には機密情報が含まれる可能性があります。** インスタンスとワークスペースの識別子がデプロイ環境やアカウントに結び付く場合があるため、匿名データではなく、ユーザーコンテンツを一切含まないとも保証できません。
|
||||
|
||||
### サンプリングとデバッグ実行
|
||||
|
||||
コミュニティ版では `space.execution_trace` で実行の送信を設定します。
|
||||
|
||||
| モード | 動作 |
|
||||
|---|---|
|
||||
| `all`（既定） | 送信条件を満たすすべての実行のノードと終了記録を記録します |
|
||||
| `sampled` | 入口でイベント識別子の安定したハッシュに基づき一度だけ判定し、成功した実行の約 `1/N` を保持します。N は `space.execution_trace_sample`（既定 20）で、同じ実行の全記録が判定を共有します |
|
||||
| `failures` | 通常の実行ではノードを保持せず、失敗・キャンセル・タイムアウト、またはチェーンの失敗理由がある場合に終了記録のみを送信します |
|
||||
| `off` | ノードと終了記録を無効にします。独立した集計カウンターの送信は継続しません。ワークスペースのハートビートは全体のテレメトリ設定に従います |
|
||||
|
||||
`sampled` で対象外になった実行が失敗した場合も、終了記録は送信します。ただし省略済みのノードは復元しないため、完全なチェーンがなく概要だけになる場合があります。WebUI のデバッグ実行は `all`、`sampled`、`failures` ではデバッグフラグ付きで保持します。`off` または全体の無効化設定では送信しません。
|
||||
|
||||
**Cloud は製品テレメトリが有効な場合、常に `all` を使用します。** 成功した実行のサンプリングが活動件数に影響することを避けるためです。インスタンス運用者は `space.disable_telemetry` で、このページの製品テレメトリを無効にできます。
|
||||
|
||||
### 送信と完全性
|
||||
|
||||
記録は `POST /api/v1/telemetry` に送信します。既定の送信間隔は 180 秒で、`space.telemetry_flush_seconds` で変更できます。1 回の送信は最大 128 件、メモリ内のバッファは最大 512 件です。送信が受け付けられた記録だけをバッファから削除し、失敗時は再試行します。バッファが満杯になると最も古い記録を破棄します。終了時には、限られた時間内で残りの記録の送信を試みます。
|
||||
|
||||
ネットワーク障害、タイムアウト、サーバーエラーによる送信失敗は業務処理を失敗させず、送信失敗の詳細は DEBUG ログに記録します。サンプリング、バッファ超過、プロセス終了、タスク間の関連付けの期限切れにより、不完全なチェーンになる場合があります。**全件記録モードでも完全な到達は保証されません。** プラットフォーム API の成功応答だけでは、ユーザーがメッセージを読んだことも確認できません。
|
||||
|
||||
## ハートビート、アンケート、旧バージョンのデータ
|
||||
|
||||
アクティブなワークスペースは起動約 30 秒後に最初の `instance_heartbeat` を送信します。通常のデプロイでは以後毎日、Cloud runtime では 5 分ごとに更新します。デプロイ環境、データベース/ベクトルデータベースの種類、サンドボックス設定と可用性、アダプターの種類、および Bot、Pipeline、プラグイン、Agent、イベントプロセッサー、イベントバインディング、MCP サーバー、ナレッジベース、スキルなどの数を含みます。リソース本文や接続用の認証情報は意図的に含めません。
|
||||
|
||||
任意参加のアプリ内アンケートでは、アンケート ID、送信した回答、インスタンス ID、バージョン、完了/閉じた状態を送信します。回答はユーザーが自発的に提供するコンテンツです。
|
||||
|
||||
Space は旧バージョンの `query` と `feature_execution` データにも対応しています。旧クエリ記録にはモデル名、機能カウンター、ユーザー定義のスキル/MCP 名、生の traceback が含まれる場合があります。現在の実行記録の制限は、過去のデータをマスキングしたり、稼働中の旧クライアントの送信内容を変更したりするものではありません。
|
||||
|
||||
## 保存と保持期間
|
||||
|
||||
データは設定された Space サービスに保存されます。実行の生データは 30 日の保持期間に基づき、定期的に上限付きのバッチで削除します。処理の滞留やサービス停止で削除が遅れる場合があります。既存のクエリテレメトリ、アンケート、アカウント、サービスログの保持規則は変更しません。カバレッジ分析は、権限を持つテレメトリ管理ユーザーまたはサービスクライアントのみが利用できます。
|
||||
データは設定された Space サービスに保存されます。実行一覧、チェーン詳細、集計は、権限を持つテレメトリ管理ユーザーまたはサービスクライアントのみが利用できます。`execution_node`、`execution_chain`、旧 `feature_execution` の生データは 30 日の保持期間に基づき、定期的に上限付きバッチで削除します。滞留やサービス停止で削除が遅れる場合があります。旧クエリテレメトリ、ハートビート、アンケート、アカウント、サービスログの保持規則は変更しません。
|
||||
|
||||
無効化すると以後の送信は停止しますが、サーバーに保存済みの記録は削除されません。過去のデータについては [[email protected]](mailto:[email protected]) または利用中の Space 管理者にお問い合わせください。
|
||||
|
||||
@@ -52,8 +69,10 @@ space:
|
||||
disable_telemetry: true
|
||||
```
|
||||
|
||||
このスイッチはクエリ統計、ハートビート、実行テレメトリ、およびアンケート取得を無効にします。引用符を付けず YAML の真偽値を使用してください。既定の有効状態に戻すには `false` に変更し、再起動します。
|
||||
このスイッチは、このページで説明した製品テレメトリとアンケート取得を無効にします。引用符を付けず YAML の真偽値を使用してください。既定の有効状態に戻すには `false` に変更し、再起動します。
|
||||
|
||||
環境変数 `SPACE__DISABLE_TELEMETRY` が設定されている場合、起動時にファイルの設定を上書きするため、併せて変更または削除してください。コンテナの環境変数を変更する場合はコンテナを再作成します。Cloud ではインスタンスの運用者が設定し、そのインスタンスの全ワークスペースに適用されます。Bot の動作や、メッセージングプラットフォーム、モデル提供者、プラグイン自体のプライバシー設定は変更しません。
|
||||
|
||||
Cloud の Plugin Runtime 運用状態の送信は製品テレメトリとは別で、`plugin.runtime_ops.enabled` で制御します。`space.disable_telemetry` では無効になりません。
|
||||
|
||||
[システム設定](../deploy/settings)も参照してください。
|
||||
|
||||
@@ -1,117 +0,0 @@
|
||||
"""Keep the localized Beta policy controls and checklist aligned."""
|
||||
import pathlib
|
||||
import re
|
||||
import unittest
|
||||
|
||||
ROOT = pathlib.Path(__file__).resolve().parents[1]
|
||||
|
||||
|
||||
class BetaDiagnosticsPolicyTest(unittest.TestCase):
|
||||
def test_locales_share_protocol_controls_and_scenarios(self):
|
||||
policies = {
|
||||
locale: (ROOT / locale / 'insight/data-collection-policy.mdx').read_text()
|
||||
for locale in ('en', 'zh', 'ja')
|
||||
}
|
||||
expected_scenarios = [f'B2-{number:02}' for number in range(1, 7)]
|
||||
expected_config = [
|
||||
'space:\n disable_beta_diagnostics: true',
|
||||
'space:\n disable_telemetry: true',
|
||||
]
|
||||
for locale, policy in policies.items():
|
||||
with self.subTest(locale=locale):
|
||||
self.assertEqual(re.findall(r'`(B2-\d{2})`', policy), expected_scenarios)
|
||||
self.assertEqual(re.findall(r'```yaml\n(.*?)\n```', policy, re.S), expected_config)
|
||||
for literal in (
|
||||
'4.11.0-beta.2', '1.5', 'instance_id', 'workspace_uuid',
|
||||
'alpha', '30', '90', '[email protected]', 'traceback',
|
||||
'data/config.yaml', 'SPACE__DISABLE_BETA_DIAGNOSTICS',
|
||||
'SPACE__DISABLE_TELEMETRY', 'space.url', '4.11.0b2+local',
|
||||
):
|
||||
self.assertIn(literal, policy)
|
||||
self.assertEqual(len(re.findall(r'^## ', policy, re.M)), 5)
|
||||
|
||||
def test_english_policy_distinguishes_legacy_content_and_diagnostics(self):
|
||||
policy = (ROOT / 'en/insight/data-collection-policy.mdx').read_text()
|
||||
for required in (
|
||||
'pseudonymous identifiers, not anonymous data',
|
||||
'legacy `error` field can contain a raw traceback',
|
||||
'rules do not sanitize this legacy stream',
|
||||
'this release has no stable opt-in',
|
||||
'does **not** delete records already received',
|
||||
'does not change query telemetry, heartbeat, survey',
|
||||
'diagnostics do not automatically run these actions',
|
||||
'members explicitly authorized for telemetry access',
|
||||
'Ordinary Workspace membership does not itself grant this access',
|
||||
'Telemetry read permission alone does not permit deletion',
|
||||
'Records become eligible for deletion',
|
||||
'not guarantees of deletion at an exact hour',
|
||||
'those environment values override the file at startup',
|
||||
):
|
||||
self.assertIn(required, policy)
|
||||
|
||||
def test_localized_access_and_cleanup_contract(self):
|
||||
required = {
|
||||
'en': ('members explicitly authorized for telemetry access',
|
||||
'Telemetry read permission alone does not permit deletion',
|
||||
'Records become eligible for deletion',
|
||||
'not guarantees of deletion at an exact hour'),
|
||||
'zh': ('获得明确遥测访问授权的成员', '仅有遥测读取权限不能删除数据',
|
||||
'记录达到阈值后具备删除条件', '并非保证在某个精确时刻完成删除'),
|
||||
'ja': ('テレメトリへのアクセスを明示的に許可されたメンバー',
|
||||
'テレメトリの閲覧権限だけでは、削除やエラー状態の変更はできません',
|
||||
'しきい値に達した記録は削除対象',
|
||||
'特定の時刻での削除を保証するものではありません'),
|
||||
}
|
||||
for locale, clauses in required.items():
|
||||
policy = (ROOT / locale / 'insight/data-collection-policy.mdx').read_text()
|
||||
with self.subTest(locale=locale):
|
||||
for clause in clauses:
|
||||
self.assertIn(clause, policy)
|
||||
|
||||
def test_built_policy_html_when_requested(self):
|
||||
import os
|
||||
from html.parser import HTMLParser
|
||||
if os.environ.get('BETA_DIAGNOSTICS_STATIC') != '1':
|
||||
self.skipTest('Run with BETA_DIAGNOSTICS_STATIC=1 after npm run build')
|
||||
|
||||
class VisibleText(HTMLParser):
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
self.parts = []
|
||||
self.tables = 0
|
||||
self.hidden = 0
|
||||
|
||||
def handle_starttag(self, tag, attrs):
|
||||
if tag in ('script', 'style'):
|
||||
self.hidden += 1
|
||||
if tag == 'table':
|
||||
self.tables += 1
|
||||
|
||||
def handle_endtag(self, tag):
|
||||
if tag in ('script', 'style'):
|
||||
self.hidden -= 1
|
||||
|
||||
def handle_data(self, data):
|
||||
if not self.hidden:
|
||||
self.parts.append(data)
|
||||
|
||||
for locale in ('en', 'zh', 'ja'):
|
||||
with self.subTest(locale=locale):
|
||||
html = (ROOT / 'dist/public' / locale /
|
||||
'insight/data-collection-policy/index.html').read_text()
|
||||
parser = VisibleText()
|
||||
parser.feed(html)
|
||||
text = ''.join(parser.parts)
|
||||
self.assertEqual(parser.tables, 2)
|
||||
for literal in ('4.11.0-beta.2', 'disable_beta_diagnostics',
|
||||
'disable_telemetry', 'SPACE__DISABLE_BETA_DIAGNOSTICS',
|
||||
'SPACE__DISABLE_TELEMETRY', '4.11.0b2+local',
|
||||
'instance_id', 'workspace_uuid', 'traceback'):
|
||||
self.assertIn(literal, text)
|
||||
for number in range(1, 7):
|
||||
self.assertIn(f'B2-{number:02}', text)
|
||||
self.assertIn('href="mailto:[email protected]"', html)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
unittest.main()
|
||||
@@ -0,0 +1,100 @@
|
||||
"""Validate localized telemetry controls and the rendered collection policy."""
|
||||
import os
|
||||
import pathlib
|
||||
import re
|
||||
import unittest
|
||||
from html.parser import HTMLParser
|
||||
|
||||
ROOT = pathlib.Path(__file__).resolve().parents[1]
|
||||
LOCALES = ("en", "zh", "ja")
|
||||
|
||||
|
||||
class TelemetryPolicyTest(unittest.TestCase):
|
||||
def test_locales_document_current_protocol_and_opt_out(self):
|
||||
for locale in LOCALES:
|
||||
policy = (ROOT / locale / "insight/data-collection-policy.mdx").read_text(encoding="utf-8")
|
||||
with self.subTest(locale=locale):
|
||||
for literal in (
|
||||
"schema: 2", "execution_node", "execution_chain", "event_id",
|
||||
"instance_id", "workspace_uuid", "instance_heartbeat",
|
||||
"space.execution_trace", "space.execution_trace_sample",
|
||||
"space.telemetry_flush_seconds", "plugin.runtime_ops.enabled",
|
||||
"data/config.yaml", "SPACE__DISABLE_TELEMETRY", "space.url",
|
||||
"feature_execution", "traceback", "[email protected]",
|
||||
):
|
||||
self.assertIn(literal, policy)
|
||||
self.assertEqual(
|
||||
re.findall(r"```yaml\n(.*?)\n```", policy, re.S),
|
||||
["space:\n disable_telemetry: true"],
|
||||
)
|
||||
self.assertEqual(
|
||||
re.findall(r"^\| `(all|sampled|failures|off)`", policy, re.M),
|
||||
["all", "sampled", "failures", "off"],
|
||||
)
|
||||
self.assertNotIn("disable_beta_diagnostics", policy)
|
||||
self.assertNotRegex(policy, r"B2-\d{2}")
|
||||
self.assertIn("(../deploy/settings)", policy)
|
||||
|
||||
def test_settings_examples_share_defaults_and_boolean_opt_out(self):
|
||||
expected = {
|
||||
"execution_trace": "all",
|
||||
"execution_trace_sample": "20",
|
||||
"telemetry_flush_seconds": "180",
|
||||
}
|
||||
for locale in LOCALES:
|
||||
settings = (ROOT / locale / "deploy/settings.mdx").read_text(encoding="utf-8")
|
||||
with self.subTest(locale=locale):
|
||||
blocks = re.findall(r"```yaml\n(.*?)\n```", settings, re.S)
|
||||
self.assertIn("space:\n disable_telemetry: true", blocks)
|
||||
sampling = [block for block in blocks if "execution_trace:" in block]
|
||||
self.assertEqual(len(sampling), 1)
|
||||
fields = dict(re.findall(r"^ (\w+):\s*(\S+)", sampling[0], re.M))
|
||||
self.assertEqual(fields, expected)
|
||||
for literal in ("SPACE__DISABLE_TELEMETRY", "plugin.runtime_ops.enabled"):
|
||||
self.assertIn(literal, settings)
|
||||
self.assertIn("(../insight/data-collection-policy)", settings)
|
||||
|
||||
def test_built_policy_html_when_requested(self):
|
||||
if os.environ.get("TELEMETRY_POLICY_STATIC") != "1":
|
||||
self.skipTest("Run with TELEMETRY_POLICY_STATIC=1 after npm run build")
|
||||
|
||||
class VisibleText(HTMLParser):
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
self.parts = []
|
||||
self.tables = 0
|
||||
self.hidden = 0
|
||||
|
||||
def handle_starttag(self, tag, attrs):
|
||||
if tag in ("script", "style"):
|
||||
self.hidden += 1
|
||||
if tag == "table":
|
||||
self.tables += 1
|
||||
|
||||
def handle_endtag(self, tag):
|
||||
if tag in ("script", "style"):
|
||||
self.hidden -= 1
|
||||
|
||||
def handle_data(self, data):
|
||||
if not self.hidden:
|
||||
self.parts.append(data)
|
||||
|
||||
for locale in LOCALES:
|
||||
with self.subTest(locale=locale):
|
||||
html = (ROOT / "dist/public" / locale /
|
||||
"insight/data-collection-policy/index.html").read_text(encoding="utf-8")
|
||||
parser = VisibleText()
|
||||
parser.feed(html)
|
||||
text = "".join(parser.parts)
|
||||
self.assertEqual(parser.tables, 2)
|
||||
for literal in ("schema: 2", "execution_node", "execution_chain",
|
||||
"instance_id", "workspace_uuid", "event_id",
|
||||
"disable_telemetry", "SPACE__DISABLE_TELEMETRY",
|
||||
"space.telemetry_flush_seconds", "plugin.runtime_ops.enabled"):
|
||||
self.assertIn(literal, text)
|
||||
self.assertNotIn("disable_beta_diagnostics", text)
|
||||
self.assertIn('href="mailto:[email protected]"', html)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
+21
-5
@@ -445,20 +445,36 @@ space:
|
||||
disable_telemetry: true
|
||||
```
|
||||
|
||||
此开关统一关闭查询统计、心跳和功能执行遥测，也会关闭问卷获取。使用 YAML 布尔值，不要加引号。恢复默认开启状态时，改回 `false` 并重启。
|
||||
此开关统一关闭产品遥测（包括心跳和执行记录），并关闭问卷获取。使用 YAML 布尔值，不要加引号。恢复默认开启状态时，改回 `false` 并重启。Cloud 的 Plugin Runtime 运维健康上报由独立的 `plugin.runtime_ops.enabled` 控制。
|
||||
|
||||
如果部署设置了 `SPACE__DISABLE_TELEMETRY`，该环境变量会在启动时覆盖文件设置；请同时修改或移除它。容器环境变量改变后需要重新创建容器。Cloud 由实例运维方配置，对该实例所有工作区生效。此设置不影响机器人正常运行，也不修改消息平台、模型提供商或插件自身的隐私设置。
|
||||
|
||||
### 单事件执行链路
|
||||
|
||||
执行遥测还会计抽样上报单事件链路（一个入站平台事件从来源平台、路由、处理到由此触发的平台 API 调用的全过程）。可在同一 `space` 节点调整抽样：
|
||||
4.11 当前默认对符合上报条件的执行全量记录，包括平台事件、路由、Pipeline / Agent / 插件事件处理器，以及由此触发的平台 API 和工具调用。每个完成的节点生成一条记录，执行结束再生成一条结束记录，由 Space 重组链路。以下为同一 `space` 节点下的默认配置，修改后重启生效：
|
||||
|
||||
平台事件未命中业务路由，或被 `discard` 规则忽略且没有匹配的插件订阅时，整条事件不上报。本地日志和监控保留原有行为。插件订阅匹配、有效交互恢复及独立 WebUI/API/Pipeline 调用仍可上报；命中后的目标不可用、运行失败或 Pipeline 内部过滤也保留。该过滤在采样之前执行，Cloud 的 `all` 和失败兜底都不能绕过它，需要升级 Core 才能生效。
|
||||
|
||||
```yaml
|
||||
space:
|
||||
execution_trace: sampled # off | failures | sampled | all
|
||||
execution_trace_sample: 20 # sampled 模式下：每 N 条成功链路保留一条
|
||||
execution_trace: all # off | failures | sampled | all
|
||||
execution_trace_sample: 20 # sampled 模式下：按事件哈希保留约 1/N 的成功执行
|
||||
telemetry_flush_seconds: 180 # 执行记录缓冲区的刷新间隔，单位为秒
|
||||
```
|
||||
|
||||
`failures` 只保留包含失败、取消或超时阶段的链路。`off` 关闭链路上报，窗口计数不受影响。WebUI 调试执行始终保留，并继续标记为模拟执行。链路的保留期限与功能执行记录一致，为 30 天。
|
||||
社区版的模式行为如下：
|
||||
|
||||
| 模式 | 上报行为 |
|
||||
|---|---|
|
||||
| `all` | 默认值，记录所有符合上报条件的执行的节点和结束记录 |
|
||||
| `sampled` | 按事件标识的稳定哈希决定是否保留，同一次执行共享采样决定；未命中的失败执行仍上报结束记录，但不追补节点 |
|
||||
| `failures` | 普通执行不保留节点，只上报失败、取消、超时或有链路失败原因的结束记录 |
|
||||
| `off` | 不上报执行节点和结束记录，也没有独立的窗口计数继续上报；心跳仍由 `disable_telemetry` 控制 |
|
||||
|
||||
WebUI 调试执行在 `all`、`sampled` 和 `failures` 下均保留并带有调试标记；`off` 或 `disable_telemetry: true` 会停止其上报。**Cloud 在产品遥测启用时固定使用 `all`，不采用上述采样模式配置**；实例运维方仍可使用总开关关闭产品遥测。
|
||||
|
||||
`execution_trace_sample` 接受 1–100000 的整数；`telemetry_flush_seconds` 接受 1–86400 的整数。无效值分别回退为 20 和 180，无效的模式回退为 `all`。抽样不是严格按顺序每 N 条保留一条。
|
||||
|
||||
每次刷新最多发送 128 条，缓冲最多 512 条；发送失败保留重试，缓冲满时丢弃最旧记录，因此全量模式也不保证完整送达。活跃工作区在启动约 30 秒后首次发送心跳，此后普通部署每天一次，Cloud runtime 每 5 分钟一次。执行原始记录按 30 天窗口分批清理，积压可能延迟删除。
|
||||
|
||||
参见[数据收集政策](../insight/data-collection-policy)。
|
||||
|
||||
@@ -1,45 +1,62 @@
|
||||
---
|
||||
title: "数据收集政策"
|
||||
description: "可选遥测、功能执行记录与关闭方法"
|
||||
description: "可选遥测、执行链路、数据范围与关闭方法"
|
||||
---
|
||||
|
||||
LangBot 向配置的 LangBot Space 服务（默认为 `https://space.langbot.app`）发送遥测，用于了解使用情况和改进可靠性。**遥测默认开启，可以关闭。** 功能执行记录复用现有遥测，不再使用独立 Beta 诊断上报。
|
||||
LangBot 向 `space.url` 配置的 LangBot Space 服务（默认为 `https://space.langbot.app`）发送产品遥测，用于了解使用情况和改进可靠性。**遥测默认开启，可以关闭。** 以下说明对应 4.11 当前的执行遥测协议（`schema: 2`）；旧版本数据另见下文。
|
||||
|
||||
## 现有产品遥测
|
||||
## 执行遥测
|
||||
|
||||
启用后，现有查询链路可能发送：
|
||||
符合上报条件的一次执行由共享 `event_id` 的独立记录组成：每个工作流节点完成时生成一条 `execution_node`，执行结束时生成一条 `execution_chain`。Core 将记录放入有界缓冲区，后台批量发送；Space 将节点重组为执行链路。当前发送端不再使用旧的功能窗口计数或在本地拼装完整链路。
|
||||
|
||||
**平台事件没有命中业务路由，或最终命中 `discard`（忽略/丢弃）且没有匹配的插件订阅时，不上报任何执行节点或链路结束记录。** 路由禁用、事件类型或过滤条件不匹配也属于此范围；本地日志和监控仍保留原有行为。主路由未命中但插件事件处理器匹配时，保留实际处理的执行，省略未命中和丢弃旁支的遥测。
|
||||
|
||||
命中业务路由后，目标不可用、执行失败、超时或 Pipeline 内部过滤仍可上报。有效交互回调恢复原处理器、WebUI/API 调试及显式指定 Pipeline 的独立调用也可上报；无效回调不会单独取得上报资格。此过滤先于采样和失败兜底，对 Cloud 同样生效。升级 Core 后生效；旧客户端及已有历史记录不受追溯修改。
|
||||
|
||||
| 数据 | 内容 |
|
||||
|---|---|
|
||||
| 标识与环境 | `instance_id`、`workspace_uuid`、随机 `query_id`、版本、适配器及运行器类型 |
|
||||
| 查询统计 | 模型名称、耗时、时间戳、管道插件名称 |
|
||||
| 功能使用 | 按来源分类的工具调用次数、工具调用轮数、知识库与检索条目数、知识引擎插件 ID、沙箱执行/错误次数、已激活技能名称、已配置 MCP 服务器名称 |
|
||||
| 错误 | 旧 `error` 字段可能包含原始 traceback，包括异常文本 |
|
||||
| 托管运行实例活动 | 托管 SaaS 查询中的 `runtime_instance_id` 用于刷新空闲超时活动，不写入分析事件记录 |
|
||||
| 标识与环境 | `instance_id`、`workspace_uuid`、`event_id`、版本、部署版本类型、时间戳、调试标记与采样信息 |
|
||||
| 执行节点 | 平台事件、路由、Pipeline、Runner、平台 API 和工具调用的操作标识、处理模式、结果、起止时间、父子节点与顺序、路由目标和 Runner 运行标识 |
|
||||
| 链路结束 | 整体结果、关闭原因、耗时、节点数、因采样未上报的节点数、来源、模型名称、适配器、Runner 与管道插件 |
|
||||
| 绑定资源 | Pipeline 或 Agent 获准使用的插件、MCP 服务器、知识库、工具及来源、技能、模型、平台 API 的标识或名称，以及资源选择字段、能力与授权标记；实际字段取决于执行路径 |
|
||||
| 错误 | 经过长度限制和空白清理的简短错误文本，可能包含异常类型与异常消息前缀 |
|
||||
|
||||
功能计数不会主动包含工具参数/结果、检索文本或沙箱代码/输出。**但旧异常文本以及用户自定义的模型、技能、MCP 名称可能含有敏感信息。功能执行记录的内容限制不会为这条旧数据流脱敏。** 不应将现有遥测视为保证不含用户内容。
|
||||
绑定资源表示这次执行被配置或授权使用哪些资源，**不等于实际调用、检索或消耗了这些资源**。路由目标使用 `type:uuid`，不使用用户自定义规则名。
|
||||
|
||||
活跃工作区会在启动后不久、此后每天发送工作区心跳，包含部署平台、数据库/向量数据库类型、沙箱配置与可用性、已启用适配器类型和资源数量，而非资源内容或连接信息。
|
||||
执行记录不会主动采集消息正文、提示词、模型回复、平台用户或群组 ID、工具/API 参数或结果、凭据或完整异常堆栈。**但错误文本截断并非可靠脱敏，异常消息前缀以及自定义的模型、技能或资源名称仍可能含有敏感信息。** 实例与工作区标识可能关联到部署或账户，不能将这些记录视为匿名数据或保证不含用户内容。
|
||||
|
||||
自愿参与的应用内问卷会发送问卷 ID、提交的回答、实例 ID、版本及完成/关闭状态。问卷回答是用户主动提供的内容，不属于 Beta 诊断。
|
||||
### 采样与调试执行
|
||||
|
||||
## 功能执行遥测
|
||||
社区版通过 `space.execution_trace` 控制执行上报：
|
||||
|
||||
功能执行遥测记录平台事件、路由、Pipeline / Agent / 插件事件处理器和平台 API 的执行事实，包括固定的操作标识、适配器和运行器类型、处理模式、结果、次数、首次及末次观测时间、实例与工作区标识、版本及模拟执行标记。Core 在内存中有界合并，再由后台发送；Space 负责路径覆盖分析。
|
||||
| 模式 | 行为 |
|
||||
|---|---|
|
||||
| `all`（默认） | 记录所有符合上报条件的执行的节点和结束记录 |
|
||||
| `sampled` | 根据事件标识的稳定哈希，在入口决定是否采样；成功执行约保留 `1/N`，N 为 `space.execution_trace_sample`（默认 20），同一次执行共享采样决定 |
|
||||
| `failures` | 普通执行不保留节点，只在失败、取消、超时或有链路失败原因时上报结束记录 |
|
||||
| `off` | 关闭节点和链路结束记录；没有继续上报的独立窗口计数，工作区心跳仍由总开关控制 |
|
||||
|
||||
这些执行记录不包含消息、提示词、模型回复、平台用户或群组 ID、工具/API 参数或结果、凭据及原始异常堆栈。实例与工作区标识可能关联到部署或账户，不应视为不可识别。此内容限制仅针对功能执行记录，不改变上述既有查询遥测的数据范围。
|
||||
`sampled` 未命中的执行如果失败，仍会上报链路结束记录，但不会追补已跳过的节点，因此可能只有摘要而没有完整链路。WebUI 调试执行在 `all`、`sampled` 和 `failures` 下均保留，并带有调试标记；`off` 或总开关关闭后不再上报。
|
||||
|
||||
### 单事件执行链路
|
||||
**Cloud 在产品遥测启用时固定使用 `all`**，以避免对成功执行的采样影响活动计数；实例运维方仍可使用 `space.disable_telemetry` 关闭本页所述产品遥测。
|
||||
|
||||
抽样上报的执行记录还可以还原单个事件的处理全过程：一个不可反推的随机链路标识、按顺序记录的阶段（平台事件 → 路由决策 → Pipeline / Agent / 插件事件处理器 → 平台 API 调用）、每个阶段的结果、路由目标标识、执行该事件的 Runner 运行标识，以及链路关闭原因。各字段与其他执行记录一样只使用代码定义的标识；路由目标以 `type:uuid` 形式上报，不使用用户自定义规则名。Core 对单条链路的阶段数和同时在途的链路数都设置了上限，超出的部分会被丢弃。
|
||||
### 发送与完整性
|
||||
|
||||
链路抽样由 `space.execution_trace` 控制：`off`、`failures`（保留含失败、取消或超时阶段的链路）、`sampled`（默认，在上述基础上保留每 N 条成功链路中的一条，N = `space.execution_trace_sample`）与 `all`。WebUI 调试执行始终保留，并继续标记为模拟执行，不计入真实执行统计。
|
||||
记录通过 `POST /api/v1/telemetry` 发送。默认刷新间隔为 180 秒，可通过 `space.telemetry_flush_seconds` 调整。每次刷新最多发送 128 条，内存缓冲最多 512 条；发送成功后才移除对应记录，失败会重试，缓冲满时丢弃最旧记录。停机时尝试在有限时间内发送剩余记录。
|
||||
|
||||
网络不可达、超时或服务端错误不会阻断正常操作，失败详情仅记录在 DEBUG 日志中。队列有上限，故障时记录可能丢失。执行记录用于辅助分析，平台 API 返回成功不代表用户已阅读消息。
|
||||
网络故障、超时或服务端错误不会使业务执行因遥测失败而报错，上报失败详情记录在 DEBUG 日志中。采样、缓冲溢出、进程退出或跨任务关联失效可能造成不完整链路，**全量模式不保证完整送达**。平台 API 返回成功也不代表用户已阅读消息。
|
||||
|
||||
## 心跳、问卷与旧版本数据
|
||||
|
||||
活跃工作区在启动约 30 秒后首次发送 `instance_heartbeat`。普通部署此后每天发送，Cloud runtime 每 5 分钟刷新。心跳包含部署平台、数据库/向量数据库类型、沙箱配置与可用性、适配器类型，以及机器人、Pipeline、插件、Agent、事件处理器、事件绑定、MCP、知识库和技能等资源数量；不主动包含资源正文或连接凭据。
|
||||
|
||||
自愿参与的应用内问卷会发送问卷 ID、提交的回答、实例 ID、版本及完成/关闭状态。问卷回答是用户主动提供的内容。
|
||||
|
||||
Space 仍兼容旧版本的 `query` 和 `feature_execution` 数据。旧查询记录可能含模型名称、功能使用计数、自定义技能/MCP 名称及原始 traceback。当前执行记录的字段限制不会追溯清理这些历史数据，也不会改变仍在运行的旧客户端的上报内容。
|
||||
|
||||
## 存储与保留
|
||||
|
||||
数据存储在所配置的 Space 服务。功能执行原始记录按 30 天保留窗口定期分批清理；服务中断或积压可能延迟删除。该期限不改变既有查询遥测、问卷、账户或服务日志的保留规则。覆盖分析仅供获授权的遥测管理用户或服务客户端访问。
|
||||
数据存储在所配置的 Space 服务。执行列表、链路详情和汇总仅供获授权的遥测管理用户或服务客户端访问。`execution_node`、`execution_chain` 及旧 `feature_execution` 原始记录按 30 天窗口定期分批清理；服务中断或积压可能延迟删除。该期限不改变旧查询遥测、心跳、问卷、账户或服务日志的保留规则。
|
||||
|
||||
关闭遥测会停止后续上报，但不会删除服务端已有记录。如需处理历史数据，请联系 [[email protected]](mailto:[email protected]) 或所用 Space 的管理员。
|
||||
|
||||
@@ -52,8 +69,10 @@ space:
|
||||
disable_telemetry: true
|
||||
```
|
||||
|
||||
此开关统一关闭查询统计、心跳和功能执行遥测，也会关闭问卷获取。使用 YAML 布尔值，不要加引号。恢复默认开启状态时，改回 `false` 并重启。
|
||||
此开关统一关闭本页所述产品遥测，并关闭问卷获取。使用 YAML 布尔值，不要加引号。恢复默认开启状态时，改回 `false` 并重启。
|
||||
|
||||
如果部署设置了 `SPACE__DISABLE_TELEMETRY`，该环境变量会在启动时覆盖文件设置；请同时修改或移除它。容器环境变量改变后需要重新创建容器。Cloud 由实例运维方配置，对该实例所有工作区生效。此设置不影响机器人正常运行，也不修改消息平台、模型提供商或插件自身的隐私设置。
|
||||
|
||||
Cloud 的 Plugin Runtime 运维健康上报独立于产品遥测，由 `plugin.runtime_ops.enabled` 控制，不能通过 `space.disable_telemetry` 关闭。
|
||||
|
||||
参见[系统环境设置](../deploy/settings)。
|
||||
|
||||
Reference in New Issue
Block a user