OneUptime 工作流运行与日志Runs Logs完全指南状态语义、执行追踪与故障排错【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime工作流的每一次执行都会在 OneUptime 中留下一份完整记录——它何时运行、是否成功、每一个组件块分别做了什么。这份记录被称为一次运行Run而本指南将围绕运行与日志的完整生命周期展开如何找到它们、如何解读七种运行状态、如何利用Steps步骤与Full Log完整日志两个视图定位故障并给出从工作流没跑到变量为空的常见排错路径。读完本文你将能够像排查任何生产系统一样熟练地对一条 OneUptime 工作流做运行审计、错误定位与状态研判。本文以仓库中的德文版文档 runs-and-logs.md 为主体并结合工作流引擎的核心源码运行器 RunWorkflow.ts、状态枚举 WorkflowStatus.ts、步骤追踪结构 StepTrace.ts、模板引用语法 TemplateSyntax.ts展开印证。什么是工作流运行Run每次工作流被触发OneUptime 都会保存一份发生了什么的事后记录——运行的时间、是否成功、以及每个组件块具体做了什么。这份记录就是运行Run。它承担三个职责确认工作流正常工作看到一次Executed运行等于确认整条链路走完了排查工作流故障失败的运行携带错误信息与失败步骤的完整上下文回溯历史活动查看过去 30 天内任何一次运行的数据与轨迹。从实现上看运行记录对应数据库中的WorkflowLog模型运行器在每次状态变更时都会把状态、日志文本、步骤追踪stepTrace和恢复数据resumeData写回该记录——这一点在 RunWorkflow.ts 的主流程中可以看到创建日志时先写入Scheduled状态随后依次改写为Running、Waiting、Success/Error/Timeout等终态。在哪些页面查看运行记录OneUptime 提供了三个不同粒度的查看入口按覆盖面从大到小排列页面你能看到什么工作流Workflows→ 运行与日志Runs Logs项目内所有工作流的全部运行记录支持按工作流名称、状态和时间筛选某个工作流Workflow→ 运行与日志Runs Logs仅这一个工作流的运行记录这里的筛选器不再是工作流而是运行 IDRun ID单条运行通过运行行上的查看日志View Logs按钮打开——注意运行行本身不可点击必须使用按钮运行状态全解析一次运行的生命周期由多种状态描述。下表汇总了全部七种状态及其含义状态含义已计划Scheduled触发器已触发运行已排队等待 Runner 拾取。通常只持续一瞬间。若一条运行超过 5 分钟仍停留在 Scheduled即视为失败——说明没有任何 Runner 接收它运行中Running工作流正在执行。长时间运行的组件块会让运行持续停留在此状态等待中Waiting运行被停放在一个Sleep休眠组件块上到点会自动继续。等待期间不占用任何 WorkerExecuted运行顺利到达终点、没有失败。这就是成功状态——标签上显示的是Executed而非 Success错误Error运行因某个组件块抛错而停止。此外以下情况也会落入 Error已排队的运行始终无人拾取、休眠运行的续跑丢失、定时表达式无法解析、或工作流在运行中途被停用超时Timeout运行时长超过了允许的限额。限额配置参见 工作流配置与安全Execution Exceeded Current Plan项目已用尽最近 30 天的工作流运行额度或订阅处于未付费状态。该运行会被记录但不会真正执行。仅适用于 OneUptime Cloud源码层面的印证状态枚举定义在 WorkflowStatus.ts 中内部取值为Scheduled、Running、Waiting、Success、Error、Timeout和WorkflowCountExceeded——可见 UI 标签如 Executed、Execution Exceeded Current Plan与内部存储值并不完全一致这是产品层的文案映射排错时不必惊讶于这种差异。关于错误分支与 Executed 的边界需要特别澄清一个容易误判的点一个组件块把控制流转交给它的Error输出口例如 API 组件遇到 4xx 状态码并不会让整次运行失败。此时错误分支照常执行运行最终仍然以Executed结束。只是该步骤本身会被标记为红色方便你找到它。代码侧印证了这一点在 RunWorkflow.ts 的recordStep中步骤的成败判定是是否有 errorMessage 或是否从error端口离开executedPort error但这只影响单步的颜色与状态只有组件真正抛出异常或调用options.onError才会走didWorkflowErrorOut路径最终把整次运行写成Error。也就是说步骤级错误 ≠ 运行级错误读取运行记录时必须同时注意两个层级。如何解读一次运行点击运行行的查看日志View Logs即可打开运行详情。Workflow Run视图包含两个选项卡。Steps步骤选项卡Steps按执行顺序为每个运行过的组件块渲染一行。每一行展示组件块的标题它的组件 IDcomponent id执行耗时它经由哪个输出口离开显示为→ success、→ error、→ yes等。展开一行会得到两个细节区块Received收到的变量全部解析完成后该组件块实际拿到的配置参数Returned返回的该组件块产生的结果。失败的步骤以红色呈现并且默认展开错误信息打印在Received区块之上。对应到数据结构Steps 视图渲染的正是WorkflowStepTraceEntry定义见 StepTrace.ts每条记录包含componentId、metadataId、title、status、startedAt、completedAt、durationInMs、脱敏后的argumentValues对应 Received与returnValues对应 Returned、executedPort离开的输出口失败时还带errorMessage。这套结构由 Runner 写入、API 返回、Dashboard 渲染三个环节共享同一份类型定义。Full Log完整日志选项卡Full Log是 Runner 打印的原始、逐行日志包含所有组件块自行记录的输出。当Steps视图不足以解释失败原因时就到这里翻原始日志。实现上运行器将所有日志行累积在内存数组中最后以\n拼接写入WorkflowLog.logs字段见 RunWorkflow.ts 中对this.logs.join(\n)的使用因此它是排查问题的最后兜底。组件 ID 与引用语法的关系一个值得牢记的细节每个步骤标题下方印出的组件 ID正是你可以直接粘进{{local.components.id.returnValues.…}}引用里的那串字符串——这是拿到一条正确引用的最快路径。引用语法的完整形态定义在 TemplateSyntax.ts 中componentReturnValueReference函数生成的引用格式为{{local.components.componentId.returnValues.returnValueId}}同文件还定义了另外两种根路径本地变量{{local.variables.name}}variableReference和全局变量{{global.variables.name}}globalVariableReference。运行器在执行时正是按local.variables、local.components.id.returnValues、global.variables这个 storage map 结构去解析引用的。100 步上限与值截断一次运行只保留最近 100 个步骤。对于超长或多次被恢复续跑多次 Sleep 恢复的运行被丢弃的早期步骤位置会显示一条琥珀色提示说明此处有步骤被截断而不是让用户误以为这是一条完整的运行。数值上限在 StepTrace.ts 中定义MAX_TRACE_STEPS 100同时MAX_TRACE_VALUE_LENGTH 4000——单个值超过 4000 字符会被截断并追加后缀… (truncated)即TRUNCATED_VALUE_SUFFIX。截断策略是字符串直接截断结构化对象按 JSON 序列化长度判断过长则整体替换为截断后的 JSON 文本避免把序列化对象拦腰切断产生看似数据实则无法解析的内容。appendTraceStep在达到上限时丢弃最旧的步骤并置truncated: true——因为一次失败运行的排查总是从尾部往前读丢掉的是最不重要的头部。敏感信息脱敏Steps 视图展示的值是变量填充后组件块实际看到的内容但有两个例外密钥Secrets与组件标记为敏感sensitive的字段会被遮蔽redacted超长值会被以… (truncated)截断。源码对此有双重保障redactSensitiveComponentValuesForLogs按组件元数据中isSensitive标记把字段替换为WORKFLOW_LOG_REDACTED_VALUEredactSecretValues则递归地扫描整个追踪结构包括键名——因为工作流变量可能被替换进 JSON 属性名比如 HTTP 头名称把所有密钥内容擦除。cleanLogs会在每次持久化前对日志文本与步骤追踪统一执行脱敏见 RunWorkflow.ts。值得一提的还有从休眠恢复resume的运行其恢复数据中刻意不持久化变量而是恢复时重新读取从根上保证密钥不会进入resumeData。从 Builder 启动运行边跑边看如果你从Builder构建器内直接启动一次运行打开的正是这同一个运行详情视图并且它会实时跟随这次运行——你可以看着它一步步执行而不用事后再去翻找。这对于快速验证手动运行是否正常非常有用。常见排错实战场景一我的工作流没有运行按以下顺序排查确认工作流已启用在它的Overview概览页面检查是否处于Enabled状态。新工作流默认是停用的而停用的工作流会拒绝一切运行——包括手动触发OneUptime 事件触发器确认事件确实发生过——打开对应记录查看其历史Webhook 触发器确认外部系统发送到了正确的 URL——大多数工具在发出 Webhook 时都有日志去那边查定时Schedule触发器确认 cron 表达式与你预期的时间匹配。如果运行确实出现了但状态是Execution Exceeded Current Plan那么说明项目已经用尽了最近 30 天的工作流运行额度或订阅未付费。该运行的日志里会写明已用次数与当前计划的限额。此状态仅适用于 OneUptime Cloud。补充一个源码角度的细节如果运行一直停留在Scheduled说明触发已发生但没有任何 Runner 拾取——运行器创建WorkflowLog时初始写入的就是Scheduled状态见 RunWorkflow.ts只有 Runner 真正开始执行时才会更新为Running。超过 5 分钟仍未拾取即按文档规则视为失败。场景二后面的组件块从来没执行某个组件块不运行绝大多数情况是连线wiring问题。打开Builder检查前一个组件块的输出口是否连接到了这个组件块的输入口前一个组件块是否走了与你预期不同的输出口——走了Error而不是Success或走了No而不是YesSteps选项卡会明确显示它实际走了哪个输出口→ error、→ yes等。代码层面还有一个值得知道的兜底机制如果某个组件块抛出的错误在图中没有对应的错误分支可走运行器会抛出异常并终止运行而若图中出现循环依赖某组件已执行过又被推入执行栈运行器会抛出Cyclic Workflow Detected错误并停止执行——这类问题同样会在 Steps 视图与 Full Log 中留下痕迹。场景三变量传进来是空的打开这次运行查看失败步骤的Received区块如果看到的是字面的{{local.components.…}}文本说明引用没有被解析。这通常是组件 ID 或返回值 ID 拼写错误——记住引用用的是组件块的Identifier标识符而不是它在画布上显示的名称。同时检查local.components本身的拼写{{local.componets.api-get-1.returnValues.response-body}}会被当作字面文本原样发出而这次运行依然报告Executed不会报错如果看到的是空字符串说明前面的组件块虽然执行了但没有产生这个字段。Full Log选项卡中有一条警告行会点名列出每一个未能解析的引用——这通常是最快的定位方式。该行为由运行器在参数替换后主动写入logUnresolvedReferences会对比替换前后的值凡是{{...}}原样出现在输出中的引用都会以Warning: ... did not resolve to anything and was left as literal text的形式记录到日志见 RunWorkflow.ts。这条警告的意义在于未解析的引用既不报错也不阻塞静默地以字面文本通过如果不主动点名排查者根本无法区分引用写错与值本来就是这段文本。场景四手动运行正常但从触发器触发就不行打开Builder点击运行工作流Run Workflow把触发器各字段填成真实触发器会发送的值然后把这个运行在Received下的取值与真实运行的取值并排对比。差异通常只是一个字段名或类型。重新执行一个工作流没有重试这次运行按钮。OneUptime 不会自动重新执行旧的运行因为运行带来的副作用——Slack 消息、API 调用、工单tickets——不一定能安全地重复执行。要重新完成这项工作有两种方式修复工作流然后让下一次真实触发器再次触发它打开Builder使用相同的值点击运行工作流。这一设计取舍也体现在执行模型上触发子工作流的组件见 Workflow 组件定义是fire-and-forget语义——它只负责把子工作流入队不等待其完成因此重复执行必须由操作者明确发起。运行记录保留多久OneUptime Cloud运行记录保留30 天到期后删除——这就是为什么两个运行列表都自我描述为覆盖最近 30 天自托管Self-hosted运行记录一直保留直到你手动删除。如果某个工作流运行极其频繁、把历史记录刷得杂乱可以停用或删除该工作流让它不再继续产生噪音。另一个兼容性细节在步骤追踪step tracing功能上线之前记录的老运行没有 Steps 内容只会显示Full Log。代码侧parseTrace对无法解析的历史数据会宽容地返回空追踪视图随之回退到原始日志见 StepTrace.ts因此老数据不会导致页面报错。继续阅读工作流配置与安全Configuration Safety——超时、递归限制、隐藏密钥工作流变量Variables——在组件块中使用的变量语法工作流组件Components——每个组件块分别产生什么。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考