ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Elsa Diagnostics Console Logs REST API 契约深度解析:Recent 查询与 Sources 枚举接口实战

Elsa Diagnostics Console Logs REST API 契约深度解析:Recent 查询与 Sources 枚举接口实战 后端工作流自动化流程编排低代码【免费下载链接】elsa-coreThe Workflow Engine for .NET项目地址https://gitcode.com/gh_mirrors/el/elsa-core点击查看免费下载本篇技术指南围绕 Elsa Workflow Engineelsa-core中006-diagnostics-console-logs特性分支的 REST API 契约展开系统讲解控制台日志诊断模块暴露的两个核心端点——近期日志回放POST /diagnostics/console-logs/recent与日志来源枚举GET /diagnostics/console-logs/sources。读完本文你将掌握请求/响应数据契约、权限与脱敏边界、服务端限制与排序规则并能结合源码理解底层缓冲、过滤与来源标识的实现原理。一、契约总览两个端点、一个权限、一条安全底线控制台日志诊断Diagnostics Console Logs是 Elsa 一个**可选启用opt-in**的核心诊断模块用于在不借助 Shell 访问的情况下查看后端进程的原始stdout/stderr输出。它独立于结构化日志Elsa.Diagnostics.StructuredLogs不解析 ILogger 记录、不提供持久化审计存储、不调用编排器日志 API仅聚焦原始控制台行的捕获、过滤、脱敏与转发。REST API 契约定义于 rest-api.md其核心约定可概括为项目约定路由前缀全部端点使用 Elsa API 路由前缀通常为/elsa/api统一权限两个端点均要求read:diagnostics:console-logs权限认证模型复用 Elsa 既有的认证、授权与跨域CORS机制安全底线行文本与来源元数据在离开后端前必须完成脱敏redaction从源码看权限常量定义在 ConsoleLogsResourcePermissions.cspublic const string ConsoleLogs diagnostics/console-logs;并通过IPermissionDescriptorProvider向权限目录贡献View动词描述符。也就是说契约文档中的read:diagnostics:console-logs实际由资源diagnostics/console-logs 动词View组合构成端点通过RequirePermission(...)引用常量而非字符串字面量避免权限名漂移。二、端点一查询近期控制台日志2.1 请求契约POST /diagnostics/console-logs/recent请求体为ConsoleLogFilter用于描述查询条件。契约文档给出了如下示例{ sourceId: local, stream: stdout, query: workflow, from: 2026-05-18T10:00:00Z, to: 2026-05-18T10:05:00Z, limit: 100 }在服务端实现中该请求体反序列化为 ElsaConsoleLogFilter.cs 中定义的ElsaConsoleLogFilter记录类型。除契约文档示例中的五个字段外实现还扩展了以下字段供 Studio 侧按工作流上下文过滤WorkflowInstanceId、WorkflowDefinitionId、WorkflowDefinitionVersionId按工作流实例/定义过滤ActivityInstanceId、ActivityId、ActivityNodeId按活动实例/节点过滤MetadataIReadOnlyDictionarystring, string按附加元数据键值过滤。2.2 响应契约响应体为RecentConsoleLogsResult契约文档示例{ items: [ { id: 01j..., timestamp: 2026-05-18T10:00:01Z, receivedAt: 2026-05-18T10:00:01Z, sequence: 42, stream: stdout, text: Workflow order-123 started, source: { id: local, displayName: elsa-server, serviceName: Elsa.Server.Web, processId: 12345, machineName: dev-machine, podName: null, containerName: null, namespace: null, nodeName: null, lastSeen: 2026-05-18T10:00:01Z, health: connected }, truncated: false, dropped: null } ], dropped: [] }响应中每条日志行的关键语义id日志行唯一标识时间有序 ID示例中缩写为01j...timestamp行产生的时间戳receivedAt后端接收时间戳过滤与排序基于receivedAtsequence来源内的局部序号source-local sequence用于多来源合并时的排序辅助streamstdout或stderrtext已脱敏的原始行文本source来源描述符详见第四节truncated是否因超长而被截断dropped该行是否伴随丢弃信息当缓冲或订阅队列溢出时非空顶层dropped数组本次查询涉及的来源丢弃行汇总。2.3 服务端强制规则契约文档明确列出了四条服务端规则结合源码可以逐一印证规则 1limit 服务端钳制。服务器将limit钳制在ConsoleLogsOptions.MaxRecentQuerySize之内。在 ElsaConsoleLogRecentBuffer.cs 中var limit filter.Limit is 0 ? Math.Min(filter.Limit.Value, _maxQuerySize) : _maxQuerySize; return snapshot .Where(line Matches(line, filter)) .TakeLast(limit) .ToArray();即无论调用方传入多大的limit实际返回数量都不会超过MaxRecentQuerySize该选项的默认值为250见下文第四节且RecentCapacity默认值为 2000共同构成内存有界的保证。规则 2返回的文本与来源元数据均已脱敏。脱敏发生在捕获/脱敏边界内REST 端点、SignalR 推送、近期缓冲与 Provider 存储只能见到脱敏后的内容对应功能需求 FR-024、FR-027a。规则 3ANSI 转义序列默认剥离。契约文档表述为默认剥离除非宿主选择保留。需要注意实现细节在 ElsaConsoleLogOptions.cs 的ConfigureDefaults中PreserveAnsi被设置为true保留而 README 中说明PreserveAnsi false才在服务端剥离。这与契约文档默认剥离在表述上存在版本差异——以当前仓库源码为准当前默认行为是保留 ANSI交由消费端如 Studio 的Raw ANSI开关决定渲染或剥离。此外颜色是否真正出现在捕获流中还取决于 .NET 控制台 Logger 的ColorBehaviorSimpleConsoleFormatter默认在输出被重定向Docker、K8s、IDE 内运行时抑制颜色如需强制可在appsettings.json配置Logging:Console:FormatterOptions:ColorBehavior Enabled。规则 4结果确定性排序。查询结果按接收顺序received order确定性排序并带有基于来源的稳定 tiebreaker以处理多来源时钟偏差或序号重叠场景对应 FR-033。2.4 端点实现要点Recent/Endpoint.cs 使用 FastEndpoints 实现Verbs(FastEndpoints.Http.POST); Routes(/diagnostics/console-logs/recent); RequirePermission(ConsoleLogsResourcePermissions.ConsoleLogs, CoreVerbs.View);执行流程为读取 JSON 请求体 → 反序列化为ElsaConsoleLogFilterJSON 非法时返回 400 Bad Request→ 经ConsoleLogFilterMapper.ToStreamingFilter转换为共享核心模型的ConsoleLogFilter→ 调用IConsoleLogProvider.GetRecentAsync获取结果。可见 REST 层只是薄薄的适配层真正逻辑在 Provider 与缓冲中。三、端点二枚举控制台日志来源3.1 请求契约GET /diagnostics/console-logs/sources无请求参数响应体为ConsoleLogSource的集合[ { id: local, displayName: elsa-server, serviceName: Elsa.Server.Web, processId: 12345, machineName: dev-machine, podName: null, containerName: null, namespace: null, nodeName: null, lastSeen: 2026-05-18T10:00:01Z, health: connected } ]该端点实现于 Sources/Endpoint.cs同样要求RequirePermission(..., CoreVerbs.View)内部直接调用IConsoleLogProvider.ListSourcesAsync。3.2 来源描述符字段说明字段含义id来源唯一标识如local或机器名-进程IDdisplayName展示名默认取自 Pod 名HOSTNAME环境变量或来源 IDserviceName服务名取自OTEL_SERVICE_NAME或应用域友好名processId/machineName进程 ID 与机器名podName/containerName/namespace/nodeNameKubernetes 场景下的可空标识来自HOSTNAME、CONTAINER_NAME、POD_NAMESPACE、NODE_NAME环境变量lastSeen最后一次收到行或心跳的时间healthconnected/stale/disconnected三种健康状态来源元数据在 ElsaConsoleLogOptions.cs 中从环境变量自动装配var sourceId ${Environment.MachineName}-{Environment.ProcessId}; var podName Environment.GetEnvironmentVariable(HOSTNAME); options.SourceId sourceId; options.SourceDisplayName !string.IsNullOrWhiteSpace(podName) ? podName : sourceId; options.ServiceName Environment.GetEnvironmentVariable(OTEL_SERVICE_NAME) ?? AppDomain.CurrentDomain.FriendlyName; SetMetadata(options, kubernetes.pod.name, podName); SetMetadata(options, kubernetes.namespace.name, Environment.GetEnvironmentVariable(POD_NAMESPACE)); SetMetadata(options, container.name, Environment.GetEnvironmentVariable(CONTAINER_NAME)); SetMetadata(options, kubernetes.node.name, Environment.GetEnvironmentVariable(NODE_NAME));这正是单进程捕获优先、集群能力通过来源身份与 Provider 边界延后提供设计思路的落地本地开发、测试与单节点宿主使用进程内捕获未来共享/外部 Provider 可在不改变 Studio 侧契约的前提下聚合多个 Core 实例的日志。3.3 来源枚举的契约规则契约文档给出三条规则权限一致来源列表与行级访问使用同一个read:diagnostics:console-logs权限不存在列出来源更宽松的旁路元数据脱敏敏感来源元数据在 Provider 存储或返回之前即被脱敏FR-027Kubernetes 命名空间、容器名等可能包含敏感信息的字段受到同等保护失效来源可继续列出处于 stale 或 disconnected 状态的来源在近期历史仍被保留期间继续可列出对应 FR-029 与用户故事 P3 场景 3来源停止心跳或行后被标记为失效但不会立刻丢失近期历史。四、配置项与默认值速查结合 README.md 与 ElsaConsoleLogOptions.cs当前仓库支持的宿主配置项及默认值如下配置项默认值说明SourceId机器名-进程ID默认来源标识SourceDisplayNamePod 名或来源 ID来源展示名ServiceNameOTEL_SERVICE_NAME或应用域友好名来源服务名PreserveAnsitrue是否保留 ANSI 转义序列false时服务端剥离RecentCapacity2000近期历史环形缓冲容量MaxRecentQuerySize250单次 recent 查询最大返回行数服务端钳制上限SubscriberCapacity—实时订阅者队列容量见 SignalR 契约MaxLineLength—单行最大长度超长截断并标记truncated模块注册方式Program.csservices.AddElsa(elsa { elsa.UseConsoleLogs(options { options.RecentCapacity 5_000; options.SubscriberCapacity 1_000; options.MaxRecentQuerySize 1_000; options.MaxLineLength 16_384; options.PreserveAnsi true; // 将颜色原样传递给消费端 }); }); app.UseConsoleLogs(); // 映射实时 SignalR Hub五、与实时链路的关系与边界REST 端点是控制台日志诊断的回放层backfill实时能力由 SignalR Hub/elsa/hubs/diagnostics/console-logs提供见 signalr-hub.md。二者共享同一套ConsoleLogFilter语义与read:diagnostics:console-logs权限。典型调用流程为先调用POST /diagnostics/console-logs/recent获取有界的有序回填再订阅实时流接收新行实时订阅支持SubscribeAsync/UpdateFilterAsync不重连即可更换过滤条件/UnsubscribeAsync并可能收到丢弃行摘要与来源状态变更事件。需要特别强调的边界对应 FR-002、FR-004、FR-032本 REST 契约仅覆盖原始 stdout/stderr 行与结构化日志Elsa.Diagnostics.StructuredLogs、结构化日志持久化、Trace 瀑布、Metrics 及 OpenTelemetry 探索完全分离近期历史属于运维排障数据而非持久审计日志需要长期保留的宿主应继续使用既有可观测性或平台日志系统Kubernetes/Docker 编排器日志 API、厂商 sink、OpenTelemetry 集成不在本特性范围内。六、质量保障与验证锚点仓库中与本文契约对应的验证资产包括ConsoleLogsAuthorizationTests.cs验证未认证/未授权调用者对 recent、sources 与 hub 的访问一律被拒绝对应 SC-003ConsoleLogsModuleTests.cs验证模块接线与端点行为ConsoleLogsHubSourceStatusTests.cs验证来源健康状态流转ConsoleLogsNamingTests.cs 与 ConsoleLogsRegistrationTests.cs验证命名稳定与模块注册。这些测试与契约文档共同构成了契约—实现—验证的闭环限制钳制、权限一致、脱敏先行、来源失效保留等规则均有对应测试与源码锚点便于读者在 Elsa.Diagnostics.ConsoleLogs 模块内继续深入探索。赞分享后端工作流自动化流程编排低代码【免费下载链接】elsa-coreThe Workflow Engine for .NET项目地址https://gitcode.com/gh_mirrors/el/elsa-core点击查看免费下载相关推荐Elsa Diagnostics Structured Logs REST API 契约深度解析结构化日志的查询、来源与兼容边界Elsa Diagnostics Structured Logs REST API 契约深度解析结构化日志的查询、来源与兼容边界 本指南以 Elsa core后端工作流自动化流程编排低代码Elsa Server Logs REST API 实战指南实时日志流的查询接口与安全契约Elsa Server Logs REST API 实战指南实时日志流的查询接口与安全契约 Elsa Server Logs Elsa.Diagnostic后端工作流自动化流程编排低代码三条命令跑通skill-installer 一键安装 Codex 技能三条命令跑通skill installer 一键安装 Codex 技能 给 Codex 加个技能过去要克隆仓库、翻目录、手动拷文件夹慢还容易装重。awesAI 技能AI 插件工作流自动化人工智能上一篇Task 命令行接口CLI完全参考命令、Flags、退出码与配置优先级实战指南下一篇7个终极Claude-Flow工作流模式从单功能脚本到企业级多项目管理创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表