Apache Burr 配置参数详解

Apache Burr 0.42.0 配置参数详解：应用构建器各方法、运行期 halt 控制、本地与 S3 跟踪存储参数、Web UI 服务端 CLI 选项与环境变量，均含实测回显。

Apache BurrBurr2026/10/14

Apache Burr 配置参数详解

目标：以 burr 0.42.0（实际安装主体 apache-burr 0.42.0）为基线，详解 Apache Burr 的配置体系：应用构建期 ApplicationBuilder 各链式方法、运行期 run/iterate 控制参数、本地与 S3 跟踪存储参数，以及 Web UI 服务端 CLI 选项与环境变量。文中参数均来自源码核对与真实环境实测，Python 3.10.12（Ubuntu 22.04）。

一、配置体系总览

Apache Burr 的配置分布在四个层级，分别控制状态机结构、执行行为、轨迹存储与服务形态：

配置层级主要入口作用
应用构建期ApplicationBuilder 链式方法定义动作、转移、初始状态、入口、跟踪与持久化
运行期Application.run / iterate控制执行、暂停点与外部输入
跟踪存储with_tracker 与 TrackingClient记录执行轨迹并落盘或上传
服务端burr CLI 选项与环境变量控制 Web UI 服务端口、监听地址、存储后端

💡 技术拓展：Python 工作流框架生态中，Prefect、Airflow 侧重大规模调度与分布式编排，Temporal 主打长期运行工作流与持久化执行，而 Apache Burr 主打轻量级状态机与可观测性，适合对话机器人、智能体、模拟仿真等决策型应用，单机 pip 安装即可快速跑通，无需额外调度集群。

二、应用构建期配置（ApplicationBuilder）

所有应用级配置通过 ApplicationBuilder 链式方法声明，最终由 build() 生成 Application 对象。以下按方法逐个说明，配套的验证应用沿用快速入门中的计数器状态机。

2.1 动作声明（@action 与 with_actions）

@action 装饰器通过 reads（读取的状态键）与 writes（写入的状态键）声明动作对状态的读写契约，with_actions 将动作注册到应用：

@action(reads=[], writes=["count"])
def counter(state: State) -> State:
    return state.update(count=state["count"] + 1)

@action(reads=["count"], writes=["result"])
def summarize(state: State) -> State:
    return state.update(result=f"count reached {state['count']}")

app = ApplicationBuilder().with_actions(counter=counter, summarize=summarize)

实测回显（with_actions 后落盘的 graph.json 中动作结构，含源码、输入与可选输入声明）：

{"type": "action", "name": "counter", "reads": [], "writes": ["count"], "code": "@action(reads=[], writes=[\"count\"])\ndef counter(state: State) -> State:\n    return state.update(count=state[\"count\"] + 1)\n", "inputs": [], "optional_inputs": []}

2.2 转移规则（with_transitions）

with_transitions 接收 (from_action, to_action, condition) 三元组定义状态机边；condition 使用 expr("表达式") 或 default 兜底：

.with_transitions(
    ("counter", "counter", expr("count < 3")),
    ("counter", "summarize", default),
)

实测坑：第三项直接传字符串会在 build 时崩溃，实测回显为 AttributeError: 'str' object has no attribute 'name'，必须使用 expr 或 default 包装。落盘的 graph.json 中转移结构实测回显：

{"type": "transition", "from_": "counter", "to": "counter", "condition": "count < 3"}
{"type": "transition", "from_": "counter", "to": "summarize", "condition": "default"}

2.3 初始状态与入口（with_state / with_entrypoint）

with_state 以关键字参数设置初始状态，with_entrypoint 指定首个执行的动作：

.with_state(count=0, result="")
.with_entrypoint("counter")

2.4 标识符（with_identifiers）

with_identifiers(app_id, partition_key, sequence_id) 显式指定应用标识：app_id 默认自动生成 UUID；partition_key 用于区分同一项目的应用分组（如用户 ID），与持久化和查询强相关；sequence_id 用于从指定序列号启动。实测中省略参数时，每次运行自动生成 UUID 目录（见后续落盘回显）。

2.5 跟踪与生命周期钩子（with_tracker / with_hooks）

with_tracker(tracker="local", project="default", params=None, use_otel_tracing=False)：tracker 传字符串 local 时按 project 与 params 实例化 LocalTrackingClient（params 支持 storage_dir、serde_kwargs 透传），也可直接传入 TrackingClient 实例；use_otel_tracing 开启 OpenTelemetry 追踪，需安装 burr[opentelemetry]。with_hooks 挂载任意生命周期适配器（追踪、度量、日志）。实测回显（with_tracker(project="burr-quickstart") 后落盘结构）：

ls ~/.burr/burr-quickstart/1b853a06-13d9-44e2-83a0-55897f602302/
graph.json
log.jsonl
metadata.json

2.6 状态持久化与初始化（with_state_persister / initialize_from）

with_state_persister(persister, on_every="step") 按指定间隔持久化状态，当前仅支持 step；传入非法值实测回显：

ValueError: on_every month not supported

initialize_from(initializer, resume_at_next_action, default_state, default_entrypoint, fork_from_app_id, fork_from_partition_key) 从持久化状态恢复运行，或通过 fork_from_app_id 从既有应用分支出新应用。

2.7 子应用与并行（with_spawning_parent / with_parallel_executor / with_typing）

with_spawning_parent(app_id, sequence_id, partition_key) 声明当前应用由父应用在指定序列号处派生的父子跟踪关系（区别于 fork 的断点续跑，spawn 表示应用完全内嵌于父应用中）。with_parallel_executor(executor_factory) 为动作提供并行执行线程池工厂。with_typing(typing_system) 为状态启用类型系统校验。

三、运行期配置（run / iterate）

Application.run(halt_before, halt_after, inputs) 串行执行至结束或命中暂停条件：halt_after 在目标动作执行完成后暂停，halt_before 在目标动作执行前暂停，inputs 传入动作所需外部输入。实测回显（halt_after=["summarize"]）：

stopped after action: summarize
result: {}
final state: {'count': 3, 'result': 'count reached 3', '__SEQUENCE_ID': 3, '__PRIOR_STEP': 'summarize'}

iterate 与 run 参数一致，但以生成器形式逐步产出，便于流式消费每个步骤的状态与结果。

四、跟踪与存储配置（LocalTrackingClient / S3TrackingClient）

4.1 本地跟踪 LocalTrackingClient

构造参数：project（必填，项目名仅允许字母数字与下划线、连字符）、storage_dir（默认 ~/.burr）、serde_kwargs（序列化参数）。轨迹按 基目录/项目/应用ID 三级目录组织，默认落在 ~/.burr/<project>/<app_id>/，内含 graph.json、metadata.json、log.jsonl。执行日志行实测回显（begin_entry 与 end_entry 各一条，end_entry 携带该步完整状态）：

{"type":"begin_entry","start_time":"2026-10-13T15:52:26.177326","action":"counter","inputs":{},"sequence_id":0}
{"type":"end_entry","end_time":"2026-10-13T15:52:26.177503","action":"counter","result":{},"exception":null,"state":{"count":1,"result":"","__SEQUENCE_ID":0,"__PRIOR_STEP":"counter"},"sequence_id":0}

4.2 S3 跟踪 S3TrackingClient

构造参数：project（必填）、bucket（必填）、region、endpoint_url（兼容 S3 的对象存储如 MinIO 可指定）、non_blocking（异步写）、flush_interval（批量刷写间隔，默认 5 秒）、unique_tracker_id、serde_kwargs。与 Web UI 服务端 --backend s3 配合使用，将轨迹写入对象存储。程序示例：

from burr.tracking.s3client import S3TrackingClient

client = S3TrackingClient(
    project="burr-quickstart",
    bucket="burr-traces",
    endpoint_url="http://127.0.0.1:9000",
)

五、Web UI 服务端配置

5.1 CLI 选项

burr 主命令实测帮助回显：

Usage: burr [OPTIONS]

Options:
  --port INTEGER        Port to run the server on
  --dev-mode            Run the server in development mode
  --no-open             Run the server without opening it
  --no-copy-demo_data   Don't copy demo data over.
  --host TEXT           Host to run the server on -- use 0.0.0.0 if you want
                        to expose it to the network
  --backend [local|s3]  Backend to use for the server.
  --help                Show this message and exit.

各选项作用：--port 监听端口；--host 监听地址，0.0.0.0 表示对外暴露；--dev-mode 开发模式（自动重载）；--no-open 不自动打开浏览器；--no-copy-demo_data 跳过演示数据初始化；--backend 指定服务端轨迹后端，local 读取 ~/.burr，s3 读取对象存储。

5.2 环境变量

服务端还支持以下环境变量（来自 burr.tracking.server 源码核对）：

环境变量默认值作用
PORT8000uvicorn 监听端口
BURR_SERVE_STATICtrue是否由服务端托管前端静态资源
BURR_BACKEND_IMPLburr.tracking.server.backend.LocalBackend服务端轨迹后端实现类路径
burr_path~/.burr本地后端轨迹数据目录
BURR_SERVER_ROOT~/.burr_serverS3 后端相关服务器根目录

实测回显（不设置 PORT 时以 CLI --port 7241 启动，服务监听 7241 并对外提供 /ready、/api/v0/version、/api/v0/projects 等接口）：

INFO:     Uvicorn running on http://0.0.0.0:7241 (Press CTRL+C to quit)

六、验证与参考链接

综合验证：以上述配置项构建并运行计数状态机应用，完成四次动作执行，tracker 落盘 2 个应用目录；Web UI 服务启动后 /ready 返回 200，/api/v0/version 返回 {"version":"0.42.0"}，/api/v0/projects 中可见 burr-quickstart 项目，配置体系全链路可用。