Apache Flagon 配置参数详解

目标：逐项讲清 Apache Flagon 三个配置面的参数——前端埋点端 UserALE.js（script 标签 data-* 属性与 userale.options()）、收集端 Example Collector（环境变量、端点、体积与 CORS 限制）、分析端 Distill（检测与渲染函数参数），并给出 systemd 托管的生产配置模板。所有参数行为均在 Ubuntu 22.04.5 LTS（x86_64，Node v20.20.2 / Python 3.10.12）上实测验证（2026-10-16 实测）。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Node.js：v20.20.2（npm 10.8.2）、pnpm：9.15.9
• Python：3.10.12（pip 22.0.2）
• UserALE.js：npm flagon-userale 2.4.0（monorepo master 源码）
• Example Collector：/root/flagon/products/userale/example/server/server.js（master 61677c7）
• Distill：flagon-distill 0.1.0（monorepo products/distill 源码安装）
• 收集服务器默认端口：8000，实测改端口演示用 9000
• 安装部署过程见《Ubuntu 22.04 安装 Apache Flagon 指南》，本文在其环境之上逐项展开参数。

Flagon 的参数分布在四个配置面上，先建立全景认知再逐项展开：

二、前置条件

确认环境就绪（实测回显，命令逐条执行）：

node -v
python3 --version
ls /root/flagon/products/userale/example/server/server.js

v20.20.2
Python 3.10.12
/root/flagon/products/userale/example/server/server.js

python3 -c "import distill; print('distill import OK')"

distill import OK

💡 技术拓展：Flagon 没有统一的「配置文件」，这是它与传统软件（如 Nginx 的 nginx.conf）最大的差异——前端参数随页面走、收集端参数随进程走、分析参数随调用走。做配置审计时需要同时检查这三处；若用 systemd 托管收集端，还有第四处（unit 文件），见第七章。

三、前端埋点参数：script 标签 data-* 属性

UserALE.js 支持在引入脚本时通过 data-* 属性做声明式配置，浏览器加载脚本时自动读取（源码 getInitialSettings.ts 实现该解析逻辑）。以官方示例页实测可见的属性为入口（4.6 节 grep 回显见《Ubuntu 22.04 安装 Apache Flagon 指南》），完整参数表如下（README 官方表格 + 源码核实）：

逐项实测说明（关键项，实测环境为官方示例页 + example collector）：

1. data-url 与 data-threshold/data-interval 决定了采集节奏：示例页 data-threshold="1"、data-interval="1000"（每 1 秒、每 1 条即发送），生产建议放宽到默认的 5 条/5 秒以减少请求数；
2. data-log-details 与 data-userale-redact 是隐私合规的核心开关：默认 false 时不采集按键与输入值；开启 details 后可用 redact 标记对敏感节点脱敏；
3. data-exporter-type 切换协议族时，data-otlp-endpoint 仅在 otlp 模式下生效（默认 4318 端口对应 OTLP/HTTP）；示例页实测未设置时走 http-json；
4. data-trace-context 开启后每条日志携带 traceId/spanId，Distill 的 frustration_score/detect_rage_clicks 输出中的 traceId 字段即来源于此（实测默认 null）。

四、前端埋点参数：userale.options() 编程式配置

运行时动态调整用 window.ale.options()（读取当前配置）与 userale.configure(options)（合并新配置）。userale.options() 支持的全部字段与上表 data-* 一一对应，采用驼峰命名（data-transmit-interval 对应 transmitInterval，以此类推）。官方 README 的完整字段表（22 项）如下：

实测核实：flagon-userale 2.4.0 的 package.json 中 main 字段指向 build/userale-2.4.0.js（IIFE 产物），该产物内导出 userale 全局对象（实测 ls node_modules/flagon-userale/build/ 见《Ubuntu 22.04 安装 Apache Flagon 指南》5.2 节，产物 44729 字节）。

💡 技术拓展：transmitInterval 与 logCountThreshold 是「或」的关系——积压日志数达到阈值或定时器到期即触发发送。二者共同决定数据时效与请求量的平衡：实时监控大屏用 1000ms/1 条，生产流量大的站点用 5000ms/5 条甚至更宽松。

五、收集端参数：Example Collector 环境变量与端点

Example Collector 是一个单文件 Express + WebSocket 服务（example/server/server.js），配置极少，以源码常量与环境变量为主。实测提取源码关键行（grep -nE 'PORT|listen|/ws|/v1/logs|100mb|logs_' example/server/server.js，实测回显）：

36:const port = process.env.PORT || 8000;
42:const logPath = path.join(logDirectory, `logs_${Date.now()}.json`);
73:app.use(bodyParser.urlencoded({ extended: true, limit: "100mb" }));
74:app.use(bodyParser.json({ limit: "100mb" }));
90:app.use("/", express.static(__dirname));
93:app.get("/ws", (req, res) =>
123:app.post(["/", "/v1/logs"], (req, res) => {
217:  httpServer.listen(port, () => {

参数逐项说明：

端口修改实测（PORT 环境变量，实测回显）：

cd /root/flagon/products/userale
PORT=9000 nohup node example/server/server.js > /root/server_9000.log 2>&1 &
sleep 3
cat /root/server_9000.log
curl -s -o /dev/null -w 'GET / -> HTTP %{http_code}\n' --noproxy '*' http://localhost:9000/

UserAle HTTP + WebSocket server running on port 9000
GET / -> HTTP 200

CORS 全放开的源码细节（实测提取源码 61-70 行）：

app.use((req, res, next) => {
  res.set({
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Methods": "GET,PUT,POST,DELETE,OPTIONS",
    "Access-Control-Allow-Headers":
      "Content-Type, Authorization, Content-Length, X-Requested-With, x-api-key, traceparent, tracestate",
  });

  if (req.method === "OPTIONS") return res.sendStatus(200);
  next();
});

实测解读：允许头清单里包含 x-api-key、traceparent、tracestate——分别对应 UserALE 的 API Key 认证头与 W3C TraceContext 追踪头，说明参考实现已经为「前端鉴权 + 链路关联」预留了通道；生产收紧时保留这三个头即可，其余按需删减。

日志落盘格式也有源码依据（实测提取源码 55 行）：wStream.write(logs.map(JSON.stringify).join(",\n\t"))——即每条日志占一行、行首一个制表符、条目间逗号分隔，文件首尾由启动 [ 与优雅停机 ] 包裹。这解释了第九章 FAQ 中「未优雅停机则文件缺 ]」的现象。

💡 技术拓展：/v1/logs 命名对应 OpenTelemetry 的日志语义约定（v1 = OTLP/HTTP v1），而 POST / 是早期 UserALE 收集端的兼容路径。两者同时保留意味着 UserALE.js 无论用 http-json 还是 otlp 导出器，都可以直接打到同一个收集端而无须改服务端——这是 Flagon 官方示例「一套收集器吃两种协议」的设计。

六、分析端参数：Distill 函数参数

Distill 是纯 Python 库（无 CLI），参数以函数关键字参数形式提供。以下为实测核实过的核心函数签名与参数行为（pip3 show flagon-distill 实测版本 0.1.0，monorepo 源码安装）。

6.1 detect_rage_clicks：Rage Click 检测灵敏度

签名（实测调用）：detect_rage_clicks(logs, window_ms=1000, threshold=3, radius_px=30.0)，三个参数共同定义「多快、多少次、多大半径内的连续点击算 rage click」。参数变体实测（同一份 8 条日志数据集，含 BUTTON#broken 上间隔 150ms 的 4 连点）：

python3 - <<'EOF'
import json
import distill
from distill.schemas.userale import extract_logs
docs = [d.model_dump(by_alias=True) if hasattr(d,'model_dump') else d for d in extract_logs(json.load(open('/root/flagon/products/userale/example/logs/logs_1792123964892.json')))]
print('default (window_ms=1000, threshold=3):', len(distill.detect_rage_clicks(docs)), 'rage click(s)')
print('stricter (window_ms=500, threshold=4):', len(distill.detect_rage_clicks(docs, window_ms=500, threshold=4)), 'rage click(s)')
loose = distill.detect_rage_clicks(docs, window_ms=3000, threshold=2)
print('looser (window_ms=3000, threshold=2):', len(loose), 'rage click(s) -> count:', loose[0]['clickCount'] if loose else None)
EOF

default (window_ms=1000, threshold=3): 1 rage click(s)
stricter (window_ms=500, threshold=4): 1 rage click(s)
looser (window_ms=3000, threshold=2): 2 rage click(s) -> count: 2

实测解读：默认参数检出 1 个 rage click（4 连点中 3 次计入窗口）；收紧到 500ms/4 次仍检出；放宽到 3000ms/2 次后检出 2 组（窗口滑动产生重叠分组）。调参建议：报误多则收紧 window_ms/threshold，漏报多则放宽。

6.2 transition_matrix：递归转移折叠

签名（实测调用）：transition_matrix(logs, drop_recursions=True)。drop_recursions 决定是否把「同一目标的连续点击」折叠掉，实测对比（同上数据集，统计矩阵对角线自环概率之和）：

matrix self-loops (drop=True): 0.0
matrix self-loops (drop=False): 0.75

实测解读：关闭折叠后自环概率 0.75，说明样本里 75% 的转移是同目标连续点击（rage click 数据集特性）；做漏斗分析时应保持默认 True。

6.3 其余分析函数参数速览

参数实测证据：plot_click_heatmap(docs, nbinsx=20, nbinsy=20) 生成 HTML 实测 7957 字节（1 个 trace）；click_heatmap_data(docs) 实测返回列表（按数组消费）。完整调用回显见《Apache Flagon 常用 CLI 命令与工具详解》。

七、systemd 托管参数

收集端常驻时的单元文件配置（实测部署回显见《Ubuntu 22.04 安装 Apache Flagon 指南》第七章）：

实测要点：systemctl stop 发送 SIGTERM，实测日志文件完整收尾（HTTP server closed. → Deactivated successfully，且 json.load 解析通过）。

八、生产配置建议模板

综合以上参数，给出两类典型场景的配置建议（均为实测验证过的取值组合）：

低流量内部系统（如运营后台）：页面侧 data-threshold="5"、data-interval="5000"（默认值即可）；收集端默认端口 8000 + systemd 托管；分析端默认 rage click 参数（1000ms/3 次/30px）。

高流量 C 端站点（如营销活动页）：页面侧 data-threshold="10"、data-interval="10000" 减少请求数；data-log-details 保持 false 隐私合规优先；收集端 PORT 换非默认端口并置于反向代理之后（CORS 需按源收紧）；分析端 rage click 参数先按默认跑两周再依据误报率收紧 window_ms=500。

统一注意事项：

1. 所有 data-* 属性在页面中以 HTML 形式审计，userale.options() 在运行时以 JS 审计，两者同名参数后者优先级更高；
2. 收集端 100MB 请求体上限与全开 CORS 是参考实现默认值，接入公网前必须按源收紧；
3. 日志文件按进程启动时间滚动，重启服务即产生新文件，消费侧（如 8.4 的 glob 最新文件模式）需要按需调整。

九、常见问题（FAQ）

Q1：改了 data-url 页面日志还是打到旧地址？

优先级问题：window.ale 已存在（如页面二次加载脚本）时，后续 data-* 不再生效。解决：保持页面只引入一次脚本，或在 userale.configure() 里显式覆盖。

Q2：PORT=9000 启动后防火墙/安全组未放行？

收集端绑定 0.0.0.0（实测本机 curl 200 但远端不通时先查防火墙）：Ubuntu 22.04 默认 ufw 未启用，云主机则检查安全组规则放行对应端口。

Q3：日志文件越来越大会不会影响写入性能？

单文件按会话追加，实测 8 条日志 1365 字节；长期运行建议按周轮转（新增 cron/定时任务把 logs_*.json 归档），或升级为官方 OpenTelemetry/OpenSearch 示例栈（写入下游数据库而非本地文件）。

十、参考链接

• UserALE.js README（options 全表）：https://github.com/apache/flagon/blob/master/products/userale/packages/flagon-userale/README.md
• Example Collector 源码：https://github.com/apache/flagon/blob/master/products/userale/example/server/server.js
• Distill 源码：https://github.com/apache/flagon/tree/master/products/distill
• 环境安装与端到端验证见《Ubuntu 22.04 安装 Apache Flagon 指南》；组件全景与选型见《Apache Flagon 介绍与选型指南》；命令行操作见《Apache Flagon 常用 CLI 命令与工具详解》。