mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-28 19:35:27 +08:00
docs: document per-event execution chains
Chains share the execution telemetry channel: one bounded, content-free chain per inbound platform event (platform event -> routing -> Pipeline/Agent/plugin processor -> platform API calls), sampled by space.execution_trace (off | failures | sampled | all). Chains keep only code-defined identifiers, report routing targets as type:uuid instead of user-defined rule names, and share the 30-day retention of execution records.
This commit is contained in:
Hyu
@@ -500,4 +500,16 @@ This switch disables query statistics, heartbeat and execution telemetry, as wel
|
||||
|
||||
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:
|
||||
|
||||
```yaml
|
||||
space:
|
||||
execution_trace: sampled # off | failures | sampled | all
|
||||
execution_trace_sample: 20 # with 'sampled': keep every N-th successful chain
|
||||
```
|
||||
|
||||
`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.
|
||||
|
||||
See [Data Collection Policy](../insight/data-collection-policy).
|
||||
|
||||
@@ -29,6 +29,12 @@ Execution observations cover platform events, routing, Pipeline / Agent / plugin
|
||||
|
||||
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.
|
||||
|
||||
### Per-event execution chains
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
@@ -412,4 +412,16 @@ space:
|
||||
|
||||
環境変数 `SPACE__DISABLE_TELEMETRY` が設定されている場合、起動時にファイルの設定を上書きするため、併せて変更または削除してください。コンテナの環境変数を変更する場合はコンテナを再作成します。Cloud ではインスタンスの運用者が設定し、そのインスタンスの全ワークスペースに適用されます。Bot の動作や、メッセージングプラットフォーム、モデル提供者、プラグイン自体のプライバシー設定は変更しません。
|
||||
|
||||
### イベント単位の実行チェーン
|
||||
|
||||
実行テレメトリは、サンプリングしたイベント単位のチェーン（受信した 1 つのプラットフォームイベントが、発生元からルーティング、処理、その結果生じたプラットフォーム API 呼び出しに至るまで）も報告します。サンプリングは同じ `space` セクションで調整します。
|
||||
|
||||
```yaml
|
||||
space:
|
||||
execution_trace: sampled # off | failures | sampled | all
|
||||
execution_trace_sample: 20 # sampled の場合：成功したチェーンの N 件に 1 件を保持
|
||||
```
|
||||
|
||||
`failures` は失敗・キャンセル・タイムアウトした段階を含むチェーンのみを保持します。`off` はチェーンを無効にしますが、集計カウンターは継続します。WebUI のデバッグ実行は常に保持され、模擬実行として記録されます。チェーンの保持期間は実行記録と同じ 30 日です。
|
||||
|
||||
[データ収集ポリシー](../insight/data-collection-policy)も参照してください。
|
||||
|
||||
@@ -29,6 +29,12 @@ LangBot は利用状況の把握と信頼性の改善のため、設定された
|
||||
|
||||
この実行記録には、メッセージ、プロンプト、モデルの回答、プラットフォームのユーザー/グループ ID、ツール/API の引数や結果、認証情報、生の例外 traceback は含めません。インスタンスとワークスペースの識別子がデプロイ環境やアカウントに結び付く場合があります。この制限は実行記録に適用され、上記の既存クエリテレメトリの収集範囲は変更しません。
|
||||
|
||||
### イベント単位の実行チェーン
|
||||
|
||||
サンプリングされた実行記録は、1 つの受信イベントの処理過程を順序付きで示す場合があります。推測できないランダムなチェーン識別子、観測された段階（プラットフォームイベント → ルーティング判断 → Pipeline / Agent / プラグインのイベントプロセッサー → プラットフォーム API 呼び出し）、各段階の結果、ルーティング先の識別子、実行した Runner の実行識別子、チェーンを閉じた理由です。各項目は上記と同じコード定義の識別子のみを使用し、ルーティング先は `type:uuid` 形式で報告され、ユーザー定義のルール名は使用しません。Core は 1 チェーンあたりの段階数と同時に保持するチェーン数に上限を設け、超過分は破棄します。
|
||||
|
||||
チェーンのサンプリングは `space.execution_trace` で設定します。`off`、`failures`（失敗・キャンセル・タイムアウトした段階を含むチェーンを保持）、`sampled`（既定。それらに加えて成功したチェーンの N 件に 1 件を保持。N = `space.execution_trace_sample`）、`all` です。WebUI のデバッグ実行は常に保持され、模擬実行として記録されるため、実際の実行統計には含まれません。
|
||||
|
||||
接続障害、タイムアウト、サーバーエラーが通常の操作を妨げることはありません。失敗の詳細は DEBUG ログのみに記録します。キューには上限があり、障害時に記録が失われる場合があります。記録は分析の補助情報であり、プラットフォーム API の成功応答だけではメッセージが読まれたことを確認できません。
|
||||
|
||||
## 保存と保持期間
|
||||
|
||||
@@ -449,4 +449,16 @@ space:
|
||||
|
||||
如果部署设置了 `SPACE__DISABLE_TELEMETRY`，该环境变量会在启动时覆盖文件设置；请同时修改或移除它。容器环境变量改变后需要重新创建容器。Cloud 由实例运维方配置，对该实例所有工作区生效。此设置不影响机器人正常运行，也不修改消息平台、模型提供商或插件自身的隐私设置。
|
||||
|
||||
### 单事件执行链路
|
||||
|
||||
执行遥测还会计抽样上报单事件链路（一个入站平台事件从来源平台、路由、处理到由此触发的平台 API 调用的全过程）。可在同一 `space` 节点调整抽样：
|
||||
|
||||
```yaml
|
||||
space:
|
||||
execution_trace: sampled # off | failures | sampled | all
|
||||
execution_trace_sample: 20 # sampled 模式下：每 N 条成功链路保留一条
|
||||
```
|
||||
|
||||
`failures` 只保留包含失败、取消或超时阶段的链路。`off` 关闭链路上报，窗口计数不受影响。WebUI 调试执行始终保留，并继续标记为模拟执行。链路的保留期限与功能执行记录一致，为 30 天。
|
||||
|
||||
参见[数据收集政策](../insight/data-collection-policy)。
|
||||
|
||||
@@ -29,6 +29,12 @@ LangBot 向配置的 LangBot Space 服务（默认为 `https://space.langbot.app
|
||||
|
||||
这些执行记录不包含消息、提示词、模型回复、平台用户或群组 ID、工具/API 参数或结果、凭据及原始异常堆栈。实例与工作区标识可能关联到部署或账户，不应视为不可识别。此内容限制仅针对功能执行记录，不改变上述既有查询遥测的数据范围。
|
||||
|
||||
### 单事件执行链路
|
||||
|
||||
抽样上报的执行记录还可以还原单个事件的处理全过程：一个不可反推的随机链路标识、按顺序记录的阶段（平台事件 → 路由决策 → Pipeline / Agent / 插件事件处理器 → 平台 API 调用）、每个阶段的结果、路由目标标识、执行该事件的 Runner 运行标识，以及链路关闭原因。各字段与其他执行记录一样只使用代码定义的标识；路由目标以 `type:uuid` 形式上报，不使用用户自定义规则名。Core 对单条链路的阶段数和同时在途的链路数都设置了上限，超出的部分会被丢弃。
|
||||
|
||||
链路抽样由 `space.execution_trace` 控制：`off`、`failures`（保留含失败、取消或超时阶段的链路）、`sampled`（默认，在上述基础上保留每 N 条成功链路中的一条，N = `space.execution_trace_sample`）与 `all`。WebUI 调试执行始终保留，并继续标记为模拟执行，不计入真实执行统计。
|
||||
|
||||
网络不可达、超时或服务端错误不会阻断正常操作，失败详情仅记录在 DEBUG 日志中。队列有上限，故障时记录可能丢失。执行记录用于辅助分析，平台 API 返回成功不代表用户已阅读消息。
|
||||
|
||||
## 存储与保留
|
||||
|
||||
Reference in New Issue
Block a user