mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-28 19:35:27 +08:00
docs: document optional execution telemetry in settings and policy
This commit is contained in:
RockChinQ
@@ -484,3 +484,20 @@ At startup, LangBot applies these overrides and writes the resulting configurati
|
||||
<Note>
|
||||
In Docker deployments, set unified `BOX__*` variables on the `langbot` service. LangBot sends Box configuration to `langbot_box` through INIT RPC; variables set directly on `langbot_box` are not read.
|
||||
</Note>
|
||||
|
||||
## Optional telemetry
|
||||
|
||||
Telemetry is enabled by default and can be disabled.
|
||||
|
||||
Set the following in the existing `space` section of `data/config.yaml`, preserve other settings, and restart LangBot:
|
||||
|
||||
```yaml
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
See [Data Collection Policy](../insight/data-collection-policy).
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
title: "Data Collection Policy"
|
||||
description: "Existing telemetry, Beta diagnostics, retention and opt-out controls"
|
||||
description: "Optional telemetry, execution observations 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. **Existing product telemetry and Beta diagnostics are separate data streams.** This page describes Core 4.11.0-beta.2 diagnostics schema v1; it does not change existing product analytics settings.
|
||||
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
|
||||
|
||||
@@ -17,71 +17,37 @@ When enabled, the existing query path can send:
|
||||
| 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 new content-free diagnostics rules do not sanitize this legacy stream.** Do not treat existing telemetry as guaranteed content-free.
|
||||
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.
|
||||
|
||||
## Beta diagnostics v1 — 4.11.0-beta.2
|
||||
## Execution telemetry
|
||||
|
||||
Beta diagnostics are **on by default in Beta builds only**. Stable, alpha and release-candidate builds do not enable this producer; this release has no stable opt-in. There is no additional setup, consent wizard or required testing step. Collection runs in the background with bounded queues, batches, timeouts and retries; unavailable diagnostics services must not hold up normal bot use. Queue limits and network failures can cause diagnostic records to be lost.
|
||||
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.
|
||||
|
||||
Diagnostics record only allowlisted, content-free metadata from instrumented operations:
|
||||
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.
|
||||
|
||||
- Core/SDK/public plugin or runner versions, build revision, deployment/environment categories and supported/configured capabilities.
|
||||
- Operation and event categories, processor type, execution stage, observed outcome, counts and duration.
|
||||
- Fixed reason codes, error categories and fingerprints built from code identifiers, **not exception messages or raw tracebacks**.
|
||||
- Independent `instance_id` and optional `workspace_uuid`, plus opaque event/trace/span/run identifiers to correlate diagnostic steps. Instance-level events may have no Workspace.
|
||||
- Sender health counters such as generated, acknowledged, retried and dropped records.
|
||||
|
||||
**These are pseudonymous identifiers, not anonymous data.** An instance and a Workspace are distinct identity dimensions; neither is a substitute for the other. Identifiers may be associated with an account or deployment. “Unauthenticated reporter” does not mean unidentifiable.
|
||||
|
||||
### Excluded from Beta diagnostic records
|
||||
|
||||
No messages, prompts, model replies, raw platform events, tool/API arguments or results, form values, file/media contents, filenames or local paths, raw URLs/query strings, credentials, platform user/group IDs, user-defined resource names, or raw exceptions/tracebacks. Public component IDs and fixed operation categories are used instead of arbitrary text. Network infrastructure necessarily sees a sender's IP address for delivery and abuse prevention; this is not a promise that all service access logs are IP-free.
|
||||
|
||||
Diagnostics help find compatibility failures and regressions in observed paths. They are separate from query usage, retention/funnel statistics, account bindings and managed runtime idle-timeout activity. A platform API accepting a request does **not** prove a user received or read a message. Missing records or an untested path do not demonstrate success.
|
||||
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.
|
||||
|
||||
## Storage and retention
|
||||
|
||||
Data sent to the default service is stored on servers operated for LangBot Space. Beta diagnostics can be read by administrators, members explicitly authorized for telemetry access, and authorized service API clients. Ordinary Workspace membership does not itself grant this access. **Server default cleanup thresholds are 30 days for diagnostic detail and 90 days for aggregates**, with configuration bounded by those limits. Records become eligible for deletion at these thresholds; a scheduled worker removes them in bounded batches. Backlogs or service interruptions can delay removal, so these are not guarantees of deletion at an exact hour. These periods apply to the new diagnostic stream, not retroactively to existing product telemetry, surveys, service logs or account records. Existing telemetry continues under its existing product-analytics retention settings.
|
||||
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.
|
||||
|
||||
Opting out stops future diagnostic sends and clears local pending diagnostic records once the setting takes effect. It does **not** delete records already received by the server. For historical deletion, contact [[email protected]](mailto:[email protected]) or your Space administrator; active administrators and authorized service API clients can delete diagnostics scoped to an instance and, where applicable, a Workspace. Telemetry read permission alone does not permit deletion or error-status changes. Share identifiers privately, not in a public issue.
|
||||
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.
|
||||
|
||||
## Opt-out controls
|
||||
## Disabling telemetry
|
||||
|
||||
To disable only Beta diagnostics, update the existing `space` section in `data/config.yaml`, preserving your other settings, then restart LangBot:
|
||||
|
||||
```yaml
|
||||
space:
|
||||
disable_beta_diagnostics: true
|
||||
```
|
||||
|
||||
This does not change query telemetry, heartbeat, survey or other product analytics settings.
|
||||
|
||||
To disable Core telemetry, including Beta diagnostics, use the master switch and restart:
|
||||
Set the following in the existing `space` section of `data/config.yaml`, preserve other settings, and restart LangBot:
|
||||
|
||||
```yaml
|
||||
space:
|
||||
disable_telemetry: true
|
||||
```
|
||||
|
||||
The master switch takes precedence over the Beta setting. It also disables the existing query/heartbeat sends and survey fetching. Use YAML booleans (`true`/`false`), not quoted strings. If your deployment sets `SPACE__DISABLE_BETA_DIAGNOSTICS` or `SPACE__DISABLE_TELEMETRY`, those environment values override the file at startup; update or remove them too, then restart the process (recreate a container when changing its environment). Diagnostics also require a configured `space.url`; local-version builds such as `4.11.0b2+local` do not enable the producer. These controls do not disable the bot or alter the privacy settings of your messaging platforms, plugins, model providers or other online services.
|
||||
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.
|
||||
|
||||
## Optional Beta test checklist — 4.11.0-beta.2 / v1
|
||||
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.
|
||||
|
||||
Use a test bot, test Workspace and non-sensitive sample data. Only test capabilities your installed adapter and plugins support. This checklist is optional; diagnostics do not automatically run these actions.
|
||||
|
||||
| Scenario ID | What to check |
|
||||
|---|---|
|
||||
| `B2-01` | Start/restart the installation; check platform and Runtime connections and one normal reply. |
|
||||
| `B2-02` | Trigger a matching and non-matching route; where configured, test Pipeline, Agent and plugin event processors separately. |
|
||||
| `B2-03` | Exercise a configured tool/plugin/MCP call and a reply; check the actual destination and content yourself. |
|
||||
| `B2-04` | In a safe test environment, cancel a run or reproduce a known failure; confirm the bot remains usable. |
|
||||
| `B2-05` | If supported, test streaming and an interaction callback; check partial replies, timeout and resume behavior. |
|
||||
| `B2-06` | If checking diagnostics controls, disable diagnostics, restart and confirm normal bot use. A maintainer can separately verify no new diagnostic requests and that pending records are cleared. |
|
||||
|
||||
Do not kick, mute, delete or otherwise modify production users/data just to create diagnostic samples. Report the scenario ID, exact Core/SDK versions, platform, approximate UTC time, expected versus actual behavior and whether it was a real platform or WebUI debug test. Remove secrets and personal data from any manually submitted logs/screenshots. After a fix, repeat the same scenario on the new build. Diagnostic coverage supplements these checks; it does not replace them.
|
||||
|
||||
*Policy version: 1.5 · Last updated: September 15, 2026*
|
||||
See [System Settings](../deploy/settings).
|
||||
|
||||
@@ -396,3 +396,20 @@ space:
|
||||
<Note>
|
||||
Docker では統一された `BOX__*` 環境変数を `langbot` サービスに設定してください。LangBot は INIT RPC で Box 設定を `langbot_box` へ渡すため、`langbot_box` に直接設定した変数は読み取られません。
|
||||
</Note>
|
||||
|
||||
## 任意のテレメトリ
|
||||
|
||||
既定で有効ですが、無効にできます。
|
||||
|
||||
`data/config.yaml` の既存の `space` セクションで次を設定し、他の設定を保持したうえで LangBot を再起動します。
|
||||
|
||||
```yaml
|
||||
space:
|
||||
disable_telemetry: true
|
||||
```
|
||||
|
||||
このスイッチはクエリ統計、ハートビート、実行テレメトリ、およびアンケート取得を無効にします。引用符を付けず YAML の真偽値を使用してください。既定の有効状態に戻すには `false` に変更し、再起動します。
|
||||
|
||||
環境変数 `SPACE__DISABLE_TELEMETRY` が設定されている場合、起動時にファイルの設定を上書きするため、併せて変更または削除してください。コンテナの環境変数を変更する場合はコンテナを再作成します。Cloud ではインスタンスの運用者が設定し、そのインスタンスの全ワークスペースに適用されます。Bot の動作や、メッセージングプラットフォーム、モデル提供者、プラグイン自体のプライバシー設定は変更しません。
|
||||
|
||||
[データ収集ポリシー](../insight/data-collection-policy)も参照してください。
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
title: "データ収集ポリシー"
|
||||
description: "既存のテレメトリ、Beta 診断、保存期間とオプトアウト"
|
||||
description: "任意のテレメトリ、実行記録と無効化の方法"
|
||||
---
|
||||
|
||||
LangBot は利用状況の把握と信頼性の改善のため、設定された LangBot Space サービス（既定は `https://space.langbot.app`）にテレメトリを送信します。**既存の製品テレメトリと Beta 診断は別のデータストリームです。** 本ページは Core 4.11.0-beta.2 の診断スキーマ v1 を説明するもので、既存の製品分析設定を変更するものではありません。
|
||||
LangBot は利用状況の把握と信頼性の改善のため、設定された LangBot Space サービス（既定は `https://space.langbot.app`）にテレメトリを送信します。**既定で有効ですが、無効にできます。** 実行記録は既存のテレメトリを利用し、独立した Beta 診断の送信機能は使用しません。
|
||||
|
||||
## 既存の製品テレメトリ
|
||||
|
||||
@@ -17,71 +17,37 @@ LangBot は利用状況の把握と信頼性の改善のため、設定された
|
||||
| エラー | 旧 `error` フィールドには、例外メッセージを含む生の traceback が入ることがあります |
|
||||
| マネージド実行環境の活動 | マネージド SaaS クエリの `runtime_instance_id` はアイドルタイムアウトの活動更新に使用され、分析イベントレコードには保存されません |
|
||||
|
||||
機能カウンターは、ツールの引数/結果、検索テキスト、サンドボックスのコード/出力を意図的に含めません。**ただし、旧方式の例外テキストやユーザー定義のモデル・スキル・MCP 名には機密情報が含まれる可能性があります。新しい内容非収集の診断ルールは、この既存ストリームを無害化するものではありません。** 既存のテレメトリについて、ユーザーコンテンツを一切含まないとは保証できません。
|
||||
機能カウンターは、ツールの引数/結果、検索テキスト、サンドボックスのコード/出力を意図的に含めません。**ただし、旧方式の例外テキストやユーザー定義のモデル・スキル・MCP 名には機密情報が含まれる可能性があります。実行記録の内容制限は、この既存ストリームを無害化するものではありません。** 既存のテレメトリについて、ユーザーコンテンツを一切含まないとは保証できません。
|
||||
|
||||
アクティブなワークスペースは、起動直後とその後毎日ハートビートを送信します。デプロイ環境、データベース/ベクトルデータベースの種類、サンドボックス設定と可用性、有効なアダプターの種類、リソース数を含みますが、リソース内容や接続情報は含めません。
|
||||
|
||||
任意参加のアプリ内アンケートでは、アンケート ID、送信した回答、インスタンス ID、バージョン、完了/閉じた状態を送信します。回答はユーザーが提供するコンテンツであり、Beta 診断ではありません。
|
||||
|
||||
## Beta 診断 v1 — 4.11.0-beta.2
|
||||
## 実行テレメトリ
|
||||
|
||||
Beta 診断は**Beta 版のみで既定で有効**です。安定版、alpha 版、rc 版ではこの送信機能は有効にならず、今回のリリースでは安定版のオプトインも提供しません。追加の設定、同意ウィザード、必須のテスト手順はありません。収集はバックグラウンドで行い、キュー、バッチ、タイムアウト、再試行には上限があります。診断サービスが利用できなくても、通常の Bot 利用を妨げない設計です。キュー上限や通信障害により診断記録が失われることがあります。
|
||||
プラットフォームイベント、ルーティング、Pipeline / Agent / プラグインのイベントプロセッサー、プラットフォーム API の実行を記録します。コードで定義された操作識別子、アダプターとランナーの種類、処理モード、結果、回数、最初と最後の観測時刻、インスタンスとワークスペースの識別子、バージョン、模擬実行フラグを含みます。Core は上限付きのカウンターをメモリ内で集計し、バックグラウンドで送信します。カバレッジ分析は Space が行います。
|
||||
|
||||
診断対象の操作から、許可リストにある、業務コンテンツを含まないメタデータのみを記録します。
|
||||
この実行記録には、メッセージ、プロンプト、モデルの回答、プラットフォームのユーザー/グループ ID、ツール/API の引数や結果、認証情報、生の例外 traceback は含めません。インスタンスとワークスペースの識別子がデプロイ環境やアカウントに結び付く場合があります。この制限は実行記録に適用され、上記の既存クエリテレメトリの収集範囲は変更しません。
|
||||
|
||||
- Core/SDK/公開プラグインまたはランナーのバージョン、ビルド revision、デプロイ/環境の分類、対応・設定済み機能。
|
||||
- 操作とイベントの分類、プロセッサーの種類、実行段階、観測された結果、回数と所要時間。
|
||||
- 固定の理由コード、エラー分類、コード識別子から生成するフィンガープリント。**例外メッセージや生の traceback は使用しません。**
|
||||
- 独立した `instance_id` と任意の `workspace_uuid`、および手順を関連付ける不透明な event/trace/span/run 識別子。インスタンス単位のイベントにはワークスペースがない場合があります。
|
||||
- 生成、受信確認、再試行、破棄などの送信側の状態カウンター。
|
||||
|
||||
**これらは仮名化された識別子であり、匿名データではありません。** インスタンスとワークスペースは異なる識別軸で、互いの代わりにはなりません。識別子がアカウントやデプロイ環境と結び付く場合があります。「未認証の報告元」は「識別できない」という意味ではありません。
|
||||
|
||||
### Beta 診断記録に含めないもの
|
||||
|
||||
メッセージ、プロンプト、モデルの回答、生のプラットフォームイベント、ツール/API の引数や結果、フォーム値、ファイル/メディア内容、ファイル名やローカルパス、生の URL/クエリ文字列、認証情報、プラットフォームのユーザー/グループ ID、ユーザー定義のリソース名、生の例外や traceback は含めません。任意のテキストではなく、公開コンポーネント ID と固定の操作分類を使います。通信基盤は配信と不正利用防止のため送信元 IP を扱います。すべてのサービスアクセスログに IP が含まれないという保証ではありません。
|
||||
|
||||
診断は、観測された経路での互換性問題や回帰の発見に用います。クエリ利用量、リテンション/ファネル統計、アカウントの紐付け、マネージド環境のアイドルタイムアウト活動とは分離しています。プラットフォーム API がリクエストを受け付けても、ユーザーがメッセージを受信・閲覧したことの証明にはなりません。記録がない経路や未テストの経路を成功とはみなしません。
|
||||
接続障害、タイムアウト、サーバーエラーが通常の操作を妨げることはありません。失敗の詳細は DEBUG ログのみに記録します。キューには上限があり、障害時に記録が失われる場合があります。記録は分析の補助情報であり、プラットフォーム API の成功応答だけではメッセージが読まれたことを確認できません。
|
||||
|
||||
## 保存と保持期間
|
||||
|
||||
既定のサービスに送信されたデータは、LangBot Space のために運用されるサーバーに保存されます。管理者、テレメトリへのアクセスを明示的に許可されたメンバー、および認可されたサービス API クライアントは Beta 診断を閲覧できます。通常のワークスペースのメンバーであるだけでは、この権限は得られません。**サーバーの既定削除しきい値は診断の詳細が 30 日、集計データが 90 日**で、設定はこれらの期間を上限とします。しきい値に達した記録は削除対象となり、定期実行のワーカーが処理量を制限したバッチで削除します。処理の滞留やサービス停止により削除が遅れる場合があり、特定の時刻での削除を保証するものではありません。この期間は新しい診断ストリームにのみ適用され、既存の製品テレメトリ、アンケート、サービスログ、アカウント記録の保持規則を遡って変更しません。既存テレメトリは従来の製品分析の保持設定に従います。
|
||||
データは設定された Space サービスに保存されます。実行の生データは 30 日の保持期間に基づき、定期的に上限付きのバッチで削除します。処理の滞留やサービス停止で削除が遅れる場合があります。既存のクエリテレメトリ、アンケート、アカウント、サービスログの保持規則は変更しません。カバレッジ分析は、権限を持つテレメトリ管理ユーザーまたはサービスクライアントのみが利用できます。
|
||||
|
||||
オプトアウト設定が反映されると、以降の診断送信を停止し、ローカルの未送信診断記録を消去します。サーバーがすでに受信した記録は**削除されません**。過去のデータの削除は [[email protected]](mailto:[email protected]) または利用中の Space 管理者に依頼してください。有効なアカウントを持つ管理者と認可されたサービス API クライアントは、インスタンスと該当するワークスペースを指定して診断を削除できます。テレメトリの閲覧権限だけでは、削除やエラー状態の変更はできません。識別子は公開 Issue に載せず、非公開で共有してください。
|
||||
無効化すると以後の送信は停止しますが、サーバーに保存済みの記録は削除されません。過去のデータについては [[email protected]](mailto:[email protected]) または利用中の Space 管理者にお問い合わせください。
|
||||
|
||||
## オプトアウト
|
||||
## テレメトリの無効化
|
||||
|
||||
Beta 診断のみを無効にするには、`data/config.yaml` の既存の `space` セクションで次を設定し、他の設定を保持したうえで LangBot を再起動します。
|
||||
|
||||
```yaml
|
||||
space:
|
||||
disable_beta_diagnostics: true
|
||||
```
|
||||
|
||||
クエリテレメトリ、ハートビート、アンケート、その他の製品分析設定は変更しません。
|
||||
|
||||
Beta 診断を含む Core テレメトリを無効にするには、マスタースイッチを設定して再起動します。
|
||||
`data/config.yaml` の既存の `space` セクションで次を設定し、他の設定を保持したうえで LangBot を再起動します。
|
||||
|
||||
```yaml
|
||||
space:
|
||||
disable_telemetry: true
|
||||
```
|
||||
|
||||
マスタースイッチは Beta 設定より優先され、既存のクエリ/ハートビート送信とアンケート取得も無効にします。引用符付き文字列ではなく、YAML の真偽値（`true`/`false`）を使ってください。デプロイ環境で `SPACE__DISABLE_BETA_DIAGNOSTICS` または `SPACE__DISABLE_TELEMETRY` が設定されている場合、起動時に環境変数がファイルの設定を上書きします。これらも変更または削除してプロセスを再起動してください（コンテナの環境変数を変更する場合は再作成が必要です）。診断には `space.url` の設定も必要です。`4.11.0b2+local` のようなローカルバージョン識別子を持つビルドでは送信機能は有効になりません。Bot 自体は無効にならず、メッセージングプラットフォーム、プラグイン、モデル提供者、その他のオンラインサービスのプライバシー設定も変更しません。
|
||||
このスイッチはクエリ統計、ハートビート、実行テレメトリ、およびアンケート取得を無効にします。引用符を付けず YAML の真偽値を使用してください。既定の有効状態に戻すには `false` に変更し、再起動します。
|
||||
|
||||
## 任意の Beta テストチェックリスト — 4.11.0-beta.2 / v1
|
||||
環境変数 `SPACE__DISABLE_TELEMETRY` が設定されている場合、起動時にファイルの設定を上書きするため、併せて変更または削除してください。コンテナの環境変数を変更する場合はコンテナを再作成します。Cloud ではインスタンスの運用者が設定し、そのインスタンスの全ワークスペースに適用されます。Bot の動作や、メッセージングプラットフォーム、モデル提供者、プラグイン自体のプライバシー設定は変更しません。
|
||||
|
||||
テスト用 Bot、テスト用ワークスペース、機密性のないサンプルデータを使い、インストール済みのアダプターとプラグインが対応する機能だけを試してください。このチェックリストは任意です。診断がこれらの操作を自動実行することはありません。
|
||||
|
||||
| シナリオ ID | 確認内容 |
|
||||
|---|---|
|
||||
| `B2-01` | 起動/再起動し、プラットフォームと Runtime の接続、通常の返信を確認する。 |
|
||||
| `B2-02` | ルートが一致する場合と一致しない場合を試す。設定している場合は Pipeline、Agent、プラグインのイベントプロセッサーを個別に確認する。 |
|
||||
| `B2-03` | 設定済みのツール/プラグイン/MCP 呼び出しと返信を試し、実際の宛先と内容を自分で確認する。 |
|
||||
| `B2-04` | 安全なテスト環境で実行をキャンセルするか既知の不具合を再現し、その後も Bot を利用できることを確認する。 |
|
||||
| `B2-05` | 対応している場合はストリーミングと対話コールバックを試し、部分的な返信、タイムアウト、再開動作を確認する。 |
|
||||
| `B2-06` | 診断設定を確認する場合は無効化して再起動し、Bot の通常利用を確認する。保守担当者は別途、新規診断リクエストがないことと未送信記録の消去を確認できる。 |
|
||||
|
||||
診断サンプルを作るためだけに、本番のユーザー/データを退出、ミュート、削除、変更しないでください。報告にはシナリオ ID、正確な Core/SDK バージョン、プラットフォーム、おおよその UTC 時刻、期待した動作と実際の動作、実プラットフォームか WebUI デバッグかを記載してください。手動で送るログやスクリーンショットからは秘密情報と個人情報を除いてください。修正後は新しいビルドで同じシナリオを再確認します。診断のカバレッジはこれらの確認を補助するもので、代替するものではありません。
|
||||
|
||||
*ポリシーバージョン：1.5 · 最終更新：2026 年 9 月 15 日*
|
||||
[システム設定](../deploy/settings)も参照してください。
|
||||
|
||||
@@ -433,3 +433,20 @@ space:
|
||||
<Note>
|
||||
Docker 部署中，统一把 `BOX__*` 环境变量设置在 `langbot` 服务上。LangBot 会通过 INIT RPC 将 Box 配置传给 `langbot_box`；直接在 `langbot_box` 服务上设置 `LANGBOT_BOX_*` 或 `BOX__*` 不会被读取。
|
||||
</Note>
|
||||
|
||||
## 可选遥测
|
||||
|
||||
遥测默认开启，可以关闭。
|
||||
|
||||
在 `data/config.yaml` 的现有 `space` 节点中设置以下值，保留其他配置，然后重启 LangBot：
|
||||
|
||||
```yaml
|
||||
space:
|
||||
disable_telemetry: true
|
||||
```
|
||||
|
||||
此开关统一关闭查询统计、心跳和功能执行遥测，也会关闭问卷获取。使用 YAML 布尔值，不要加引号。恢复默认开启状态时，改回 `false` 并重启。
|
||||
|
||||
如果部署设置了 `SPACE__DISABLE_TELEMETRY`，该环境变量会在启动时覆盖文件设置；请同时修改或移除它。容器环境变量改变后需要重新创建容器。Cloud 由实例运维方配置，对该实例所有工作区生效。此设置不影响机器人正常运行，也不修改消息平台、模型提供商或插件自身的隐私设置。
|
||||
|
||||
参见[数据收集政策](../insight/data-collection-policy)。
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
title: "数据收集政策"
|
||||
description: "现有遥测、Beta 诊断、保留期限与退出方式"
|
||||
description: "可选遥测、功能执行记录与关闭方法"
|
||||
---
|
||||
|
||||
LangBot 向配置的 LangBot Space 服务（默认为 `https://space.langbot.app`）发送遥测，用于了解使用情况、改进可靠性。**现有产品遥测与 Beta 诊断是两条独立的数据流。** 本页说明 Core 4.11.0-beta.2 的诊断协议 v1，不改变现有产品分析设置。
|
||||
LangBot 向配置的 LangBot Space 服务（默认为 `https://space.langbot.app`）发送遥测，用于了解使用情况和改进可靠性。**遥测默认开启，可以关闭。** 功能执行记录复用现有遥测，不再使用独立 Beta 诊断上报。
|
||||
|
||||
## 现有产品遥测
|
||||
|
||||
@@ -17,71 +17,37 @@ LangBot 向配置的 LangBot Space 服务（默认为 `https://space.langbot.app
|
||||
| 错误 | 旧 `error` 字段可能包含原始 traceback，包括异常文本 |
|
||||
| 托管运行实例活动 | 托管 SaaS 查询中的 `runtime_instance_id` 用于刷新空闲超时活动，不写入分析事件记录 |
|
||||
|
||||
功能计数不会主动包含工具参数/结果、检索文本或沙箱代码/输出。**但旧异常文本以及用户自定义的模型、技能、MCP 名称可能含有敏感信息。新的无内容诊断规则不会为这条旧数据流脱敏。** 不应将现有遥测视为保证不含用户内容。
|
||||
功能计数不会主动包含工具参数/结果、检索文本或沙箱代码/输出。**但旧异常文本以及用户自定义的模型、技能、MCP 名称可能含有敏感信息。功能执行记录的内容限制不会为这条旧数据流脱敏。** 不应将现有遥测视为保证不含用户内容。
|
||||
|
||||
活跃工作区会在启动后不久、此后每天发送工作区心跳，包含部署平台、数据库/向量数据库类型、沙箱配置与可用性、已启用适配器类型和资源数量，而非资源内容或连接信息。
|
||||
|
||||
自愿参与的应用内问卷会发送问卷 ID、提交的回答、实例 ID、版本及完成/关闭状态。问卷回答是用户主动提供的内容，不属于 Beta 诊断。
|
||||
|
||||
## Beta 诊断 v1 — 4.11.0-beta.2
|
||||
## 功能执行遥测
|
||||
|
||||
Beta 诊断**仅在 Beta 版本默认开启**；稳定版、alpha 和 rc 版本不启用该发送器，本次发布不提供稳定版主动开启选项。不增加配置向导、同意弹窗或必做测试步骤。采集在后台运行，队列、批次、超时和重试均有上限；诊断服务不可用不应阻塞正常使用。队列限制或网络故障可能导致诊断记录丢失。
|
||||
功能执行遥测记录平台事件、路由、Pipeline / Agent / 插件事件处理器和平台 API 的执行事实，包括固定的操作标识、适配器和运行器类型、处理模式、结果、次数、首次及末次观测时间、实例与工作区标识、版本及模拟执行标记。Core 在内存中有界合并，再由后台发送；Space 负责路径覆盖分析。
|
||||
|
||||
诊断仅记录已埋点操作中白名单允许的、不含业务内容的元数据：
|
||||
这些执行记录不包含消息、提示词、模型回复、平台用户或群组 ID、工具/API 参数或结果、凭据及原始异常堆栈。实例与工作区标识可能关联到部署或账户，不应视为不可识别。此内容限制仅针对功能执行记录，不改变上述既有查询遥测的数据范围。
|
||||
|
||||
- Core/SDK/公开插件或运行器版本、构建 revision、部署/环境类别，以及支持或已配置的能力。
|
||||
- 操作和事件类别、处理器类型、执行阶段、观测结果、次数和耗时。
|
||||
- 固定原因码、错误类别及由代码标识生成的指纹，**不使用异常消息或原始 traceback**。
|
||||
- 相互独立的 `instance_id` 与可选 `workspace_uuid`，以及用于关联步骤的不透明事件/trace/span/run 标识。实例级事件可能没有工作区。
|
||||
- 生成、确认接收、重试、丢弃等发送器健康计数。
|
||||
|
||||
**这些是假名化标识，而非匿名数据。** 实例和工作区是不同的身份维度，不能互相替代；标识可能关联到账户或部署。“未经认证的报告者”不代表无法识别。
|
||||
|
||||
### Beta 诊断记录不包含什么
|
||||
|
||||
不包含消息、提示词、模型回复、原始平台事件、工具/API 参数或结果、表单值、文件/媒体内容、文件名或本地路径、原始 URL/查询字符串、凭据、平台用户/群组 ID、用户自定义资源名、原始异常或 traceback。使用公开组件 ID 和固定操作类别，而非任意文本。网络基础设施为传输和防滥用必然会接触发送者 IP；这不表示所有服务访问日志都不含 IP。
|
||||
|
||||
诊断用于发现已观测路径中的兼容性问题和回归，与查询使用量、留存/漏斗统计、账户绑定及托管实例空闲超时活动分离。平台 API 接受请求**不等于**用户已收到或读到消息。没有记录或尚未测试的路径不能视为成功。
|
||||
网络不可达、超时或服务端错误不会阻断正常操作，失败详情仅记录在 DEBUG 日志中。队列有上限，故障时记录可能丢失。执行记录用于辅助分析，平台 API 返回成功不代表用户已阅读消息。
|
||||
|
||||
## 存储与保留
|
||||
|
||||
发送到默认服务的数据存储于为 LangBot Space 运维的服务器，管理员、获得明确遥测访问授权的成员及获授权的服务 API 客户端可以读取 Beta 诊断；普通工作区成员身份本身不授予此权限。**服务器默认清理阈值为诊断明细 30 天、聚合数据 90 天**，配置以这些期限为上限。记录达到阈值后具备删除条件，由定期运行的工作线程分批、有界地清理；积压或服务中断可能延迟删除，并非保证在某个精确时刻完成删除。这些期限仅适用于新诊断数据流，不追溯改变现有产品遥测、问卷、服务日志或账户记录的保留规则；现有遥测继续使用既有产品分析保留设置。
|
||||
数据存储在所配置的 Space 服务。功能执行原始记录按 30 天保留窗口定期分批清理；服务中断或积压可能延迟删除。该期限不改变既有查询遥测、问卷、账户或服务日志的保留规则。覆盖分析仅供获授权的遥测管理用户或服务客户端访问。
|
||||
|
||||
退出设置生效后，停止后续诊断发送并清空本地待发送诊断记录，**不会**删除服务器已经接收的历史记录。如需删除历史数据，请联系 [[email protected]](mailto:[email protected]) 或所用 Space 的管理员；账户状态正常的管理员及获授权的服务 API 客户端可按实例及适用的工作区范围删除诊断。仅有遥测读取权限不能删除数据或更改错误状态。请私下提供标识，不要贴到公开 Issue 中。
|
||||
关闭遥测会停止后续上报，但不会删除服务端已有记录。如需处理历史数据，请联系 [[email protected]](mailto:[email protected]) 或所用 Space 的管理员。
|
||||
|
||||
## 退出方式
|
||||
## 关闭遥测
|
||||
|
||||
仅关闭 Beta 诊断：在 `data/config.yaml` 现有的 `space` 部分更新以下设置，保留其他配置，然后重启 LangBot：
|
||||
|
||||
```yaml
|
||||
space:
|
||||
disable_beta_diagnostics: true
|
||||
```
|
||||
|
||||
这不会改变查询遥测、心跳、问卷或其他产品分析设置。
|
||||
|
||||
关闭 Core 遥测（包括 Beta 诊断）：使用总开关，然后重启：
|
||||
在 `data/config.yaml` 的现有 `space` 节点中设置以下值，保留其他配置，然后重启 LangBot：
|
||||
|
||||
```yaml
|
||||
space:
|
||||
disable_telemetry: true
|
||||
```
|
||||
|
||||
总开关优先于 Beta 设置，也会关闭现有查询/心跳发送和问卷获取。请使用 YAML 布尔值（`true`/`false`），不要加引号。如果部署设置了 `SPACE__DISABLE_BETA_DIAGNOSTICS` 或 `SPACE__DISABLE_TELEMETRY`，启动时环境变量会覆盖文件设置；请同时修改或移除这些变量，然后重启进程（修改容器环境变量时需重新创建容器）。诊断还要求配置 `space.url`；带本地版本标记的构建（如 `4.11.0b2+local`）不会启用发送器。这些开关不会停用机器人，也不会修改消息平台、插件、模型提供商或其他在线服务的隐私设置。
|
||||
此开关统一关闭查询统计、心跳和功能执行遥测，也会关闭问卷获取。使用 YAML 布尔值，不要加引号。恢复默认开启状态时，改回 `false` 并重启。
|
||||
|
||||
## 可选 Beta 测试清单 — 4.11.0-beta.2 / v1
|
||||
如果部署设置了 `SPACE__DISABLE_TELEMETRY`，该环境变量会在启动时覆盖文件设置；请同时修改或移除它。容器环境变量改变后需要重新创建容器。Cloud 由实例运维方配置，对该实例所有工作区生效。此设置不影响机器人正常运行，也不修改消息平台、模型提供商或插件自身的隐私设置。
|
||||
|
||||
使用测试机器人、测试工作区和非敏感示例数据，只测试已安装适配器及插件支持的能力。本清单完全可选；诊断不会自动执行这些操作。
|
||||
|
||||
| 场景 ID | 检查内容 |
|
||||
|---|---|
|
||||
| `B2-01` | 启动/重启安装，检查平台和 Runtime 连接，并完成一次正常回复。 |
|
||||
| `B2-02` | 分别触发匹配和不匹配的路由；按实际配置分别测试 Pipeline、Agent 和插件事件处理器。 |
|
||||
| `B2-03` | 调用已配置的工具/插件/MCP 并回复，人工核对实际目标和内容。 |
|
||||
| `B2-04` | 在安全测试环境取消运行或复现已知故障，确认机器人仍可继续使用。 |
|
||||
| `B2-05` | 如支持，测试流式回复及交互回调，检查部分回复、超时和恢复行为。 |
|
||||
| `B2-06` | 如需检查诊断开关，关闭诊断、重启并确认机器人正常使用；维护者可另行核实没有新诊断请求且待发送记录已清空。 |
|
||||
|
||||
不要为了产生诊断样本而在生产环境踢人、禁言、删除或修改用户/数据。反馈时提供场景 ID、准确的 Core/SDK 版本、平台、大致 UTC 时间、预期与实际表现，并区分真实平台与 WebUI 调试。主动提交日志/截图前去除秘密和个人信息。修复后在新构建上重复同一场景。诊断覆盖只能补充这些检查，不能替代人工验证。
|
||||
|
||||
*政策版本：1.5 · 最后更新：2026 年 9 月 15 日*
|
||||
参见[系统环境设置](../deploy/settings)。
|
||||
|
||||
Reference in New Issue
Block a user