SemianiakaVY/elsa-core
1
0
Fork 0
Code Issues Pull requests Actions 1 Packages Projects Releases Wiki Activity
elsa-core/specs/006-diagnostics-console-logs/tasks.md
Sipke Schoorstra 43108c2e48
Add diagnostics console logs (#7462) 
* feat: add diagnostics console logs

* test: avoid secret-like redaction fixtures

* fix: address console logs review feedback

* fix: harden console log capture lifecycle

* fix: report console log drop summaries

* fix: address diagnostics review cleanups
2026-05-18 02:16:46 +02:00

17 KiB
Raw Blame History

Tasks: Diagnostics Console Logs

Input: Design documents from /specs/006-diagnostics-console-logs/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md

Tests: Included because the specification requires validation coverage for capture, stream identity, filtering, buffering, dropped counts, authorization, redaction, source health, provider boundaries, and feedback-loop prevention.

Organization: Tasks are grouped by user story so each increment can be implemented and tested independently.

Format: [ID] [P?] [Story] Description

  • [P]: Can run in parallel with other marked tasks after prerequisites are satisfied.
  • [Story]: User story label from spec.md.
  • Every task includes the primary file path to edit or create.

Phase 1: Setup

Purpose: Create the Core module and test project skeletons.

  • T001 [P] Create console logs module project in src/modules/Elsa.Diagnostics.ConsoleLogs/Elsa.Diagnostics.ConsoleLogs.csproj.
  • T002 [P] Create unit test project in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Elsa.Diagnostics.ConsoleLogs.UnitTests.csproj.
  • T003 [P] Create integration test project in test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/Elsa.Diagnostics.ConsoleLogs.IntegrationTests.csproj.
  • T004 Add the console logs projects to Elsa.sln.
  • T005 [P] Add module global usings in src/modules/Elsa.Diagnostics.ConsoleLogs/Usings.cs.
  • T006 [P] Add unit test global usings in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Usings.cs.
  • T007 [P] Add integration test global usings in test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/Usings.cs.

Phase 2: Foundational

Purpose: Add shared contracts, models, options, registration, and permissions that block all user stories.

Critical: No user story work should begin until these shared contracts and registration surfaces exist.

  • T008 [P] Add console log models in src/modules/Elsa.Diagnostics.ConsoleLogs/Models/ConsoleLogLine.cs.
  • T009 [P] Add console source model and health enum in src/modules/Elsa.Diagnostics.ConsoleLogs/Models/ConsoleLogSource.cs.
  • T010 [P] Add filter, recent result, dropped summary, and stream item models in src/modules/Elsa.Diagnostics.ConsoleLogs/Models/ConsoleLogFilter.cs.
  • T011 [P] Add provider contract in src/modules/Elsa.Diagnostics.ConsoleLogs/Contracts/IConsoleLogProvider.cs.
  • T012 [P] Add redactor contract in src/modules/Elsa.Diagnostics.ConsoleLogs/Contracts/IConsoleLogRedactor.cs.
  • T013 [P] Add source registry contract in src/modules/Elsa.Diagnostics.ConsoleLogs/Contracts/IConsoleLogSourceRegistry.cs.
  • T014 [P] Add capture contract in src/modules/Elsa.Diagnostics.ConsoleLogs/Contracts/IConsoleLogCapture.cs.
  • T015 [P] Add host options in src/modules/Elsa.Diagnostics.ConsoleLogs/Options/ConsoleLogsOptions.cs.
  • T016 [P] Add permission constant in src/modules/Elsa.Diagnostics.ConsoleLogs/Permissions/ConsoleLogsPermissions.cs.
  • T017 Add service registration extension in src/modules/Elsa.Diagnostics.ConsoleLogs/Extensions/ServiceCollectionExtensions.cs.
  • T018 Add application and endpoint route extensions in src/modules/Elsa.Diagnostics.ConsoleLogs/Extensions/ApplicationBuilderExtensions.cs.
  • T019 Add module feature registration in src/modules/Elsa.Diagnostics.ConsoleLogs/Features/ConsoleLogsFeature.cs.
  • T020 Add shell feature registration in src/modules/Elsa.Diagnostics.ConsoleLogs/ShellFeatures/ConsoleLogsFeature.cs.
  • T021 [P] Add feature and naming contract tests in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/ConsoleLogsNamingTests.cs.
  • T022 [P] Add default registration tests in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/ConsoleLogsRegistrationTests.cs.

Checkpoint: Shared contracts, options, permission, and feature registration are ready for story work.

Phase 3: User Story 1 - Tail raw backend console output (Priority: P1) MVP

Goal: Authorized users can request recent stdout/stderr lines and receive live console line events while host console output still reaches its original destination.

Independent Test: Enable console logs, write distinct complete stdout/stderr lines, request recent lines, subscribe live, and verify ordered source-aware events plus preserved original console output.

Tests for User Story 1

  • T023 [P] [US1] Add capture tee preservation tests in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Capture/ConsoleCaptureTeeTests.cs.
  • T024 [P] [US1] Add partial-line buffering and idle flush tests in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Capture/ConsoleLineBufferTests.cs.
  • T025 [P] [US1] Add truncation and ANSI default handling tests in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Capture/ConsoleLineFormatterTests.cs.
  • T026 [P] [US1] Add in-memory recent and live provider tests in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/InMemory/InMemoryConsoleLogProviderTests.cs.
  • T027 [P] [US1] Add recent endpoint contract tests in test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/ConsoleLogsRecentEndpointTests.cs.
  • T028 [P] [US1] Add SignalR subscribe/unsubscribe integration tests in test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/ConsoleLogsHubTests.cs.

Implementation for User Story 1

  • T029 [P] [US1] Implement line buffer in src/modules/Elsa.Diagnostics.ConsoleLogs/Services/ConsoleLineBuffer.cs.
  • T030 [P] [US1] Implement line formatter for truncation and ANSI handling in src/modules/Elsa.Diagnostics.ConsoleLogs/Services/ConsoleLineFormatter.cs.
  • T031 [US1] Implement stdout/stderr capture tee in src/modules/Elsa.Diagnostics.ConsoleLogs/Services/ConsoleCaptureTee.cs.
  • T032 [US1] Implement in-memory provider with bounded recent history and live queues in src/modules/Elsa.Diagnostics.ConsoleLogs/Providers/InMemory/InMemoryConsoleLogProvider.cs.
  • T033 [US1] Implement recent endpoint in src/modules/Elsa.Diagnostics.ConsoleLogs/Endpoints/ConsoleLogs/Recent/Endpoint.cs.
  • T034 [US1] Implement SignalR client contract in src/modules/Elsa.Diagnostics.ConsoleLogs/RealTime/IConsoleLogsClient.cs.
  • T035 [US1] Implement SignalR hub subscribe and unsubscribe flow in src/modules/Elsa.Diagnostics.ConsoleLogs/RealTime/ConsoleLogsHub.cs.
  • T036 [US1] Wire capture startup and shutdown in src/modules/Elsa.Diagnostics.ConsoleLogs/Services/ConsoleLogCaptureHostedService.cs.
  • T037 [US1] Run dotnet test test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Elsa.Diagnostics.ConsoleLogs.UnitTests.csproj.

Checkpoint: User Story 1 is fully functional and independently testable as the MVP.

Phase 4: User Story 2 - Filter, secure, and redact console output (Priority: P2)

Goal: Operators can filter console output while Core enforces a dedicated permission and redacts sensitive line text and source metadata before provider boundaries.

Independent Test: Connect authorized and unauthorized callers, write secret-like console lines, apply filters, and verify unauthorized access is rejected while authorized callers receive only redacted matching lines.

Tests for User Story 2

  • T038 [P] [US2] Add redaction tests for line text and source metadata in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Redaction/ConsoleLogRedactorTests.cs.
  • T039 [P] [US2] Add filter evaluator tests for source, stream, query, time range, and limit in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Filtering/ConsoleLogFilterTests.cs.
  • T040 [P] [US2] Add authorization tests for recent and source endpoints in test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/ConsoleLogsAuthorizationTests.cs.
  • T041 [P] [US2] Add SignalR authorization and filter-update tests in test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/ConsoleLogsHubAuthorizationTests.cs.
  • T042 [P] [US2] Add redaction-before-provider boundary tests in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Redaction/ConsoleLogProviderRedactionTests.cs.

Implementation for User Story 2

  • T043 [P] [US2] Implement default redaction rules in src/modules/Elsa.Diagnostics.ConsoleLogs/Services/ConsoleLogRedactor.cs.
  • T044 [P] [US2] Implement filter evaluator in src/modules/Elsa.Diagnostics.ConsoleLogs/Services/ConsoleLogFilterEvaluator.cs.
  • T045 [US2] Apply redaction before provider publication in src/modules/Elsa.Diagnostics.ConsoleLogs/Services/ConsoleCaptureTee.cs.
  • T046 [US2] Enforce server-clamped recent query limits in src/modules/Elsa.Diagnostics.ConsoleLogs/Endpoints/ConsoleLogs/Recent/Endpoint.cs.
  • T047 [US2] Secure recent and source endpoints with read:diagnostics:console-logs in src/modules/Elsa.Diagnostics.ConsoleLogs/Endpoints/ConsoleLogs/Recent/Endpoint.cs.
  • T048 [US2] Secure SignalR hub with read:diagnostics:console-logs in src/modules/Elsa.Diagnostics.ConsoleLogs/RealTime/ConsoleLogsHub.cs.
  • T049 [US2] Implement hub filter update behavior in src/modules/Elsa.Diagnostics.ConsoleLogs/RealTime/ConsoleLogsHub.cs.
  • T050 [US2] Run dotnet test test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/Elsa.Diagnostics.ConsoleLogs.IntegrationTests.csproj.

Checkpoint: User Stories 1 and 2 work together with authorization, filtering, and redaction.

Phase 5: User Story 3 - Identify console sources in clustered deployments (Priority: P3)

Goal: Operators can view source-aware merged console output, filter to one source, and see source health without changing Studio-facing contracts.

Independent Test: Simulate multiple provider sources, request sources, subscribe to merged output, filter to one source, and verify source health plus dropped-line metadata.

Tests for User Story 3

  • T051 [P] [US3] Add source registry tests for current source metadata and health transitions in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Sources/ConsoleLogSourceRegistryTests.cs.
  • T052 [P] [US3] Add multi-source ordering tests in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/InMemory/InMemoryConsoleLogProviderSourceTests.cs.
  • T053 [P] [US3] Add dropped-line summary tests for buffer and subscriber overflow in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/InMemory/InMemoryConsoleLogProviderDroppedLineTests.cs.
  • T054 [P] [US3] Add source endpoint integration tests in test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/ConsoleLogsSourcesEndpointTests.cs.
  • T055 [P] [US3] Add source status SignalR integration tests in test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/ConsoleLogsHubSourceStatusTests.cs.

Implementation for User Story 3

  • T056 [P] [US3] Implement source registry in src/modules/Elsa.Diagnostics.ConsoleLogs/Services/ConsoleLogSourceRegistry.cs.
  • T057 [US3] Add source health timeout handling in src/modules/Elsa.Diagnostics.ConsoleLogs/Services/ConsoleLogSourceHealthService.cs.
  • T058 [US3] Add deterministic multi-source ordering in src/modules/Elsa.Diagnostics.ConsoleLogs/Providers/InMemory/InMemoryConsoleLogProvider.cs.
  • T059 [US3] Add dropped-line summary publication in src/modules/Elsa.Diagnostics.ConsoleLogs/Providers/InMemory/InMemoryConsoleLogProvider.cs.
  • T060 [US3] Implement sources endpoint in src/modules/Elsa.Diagnostics.ConsoleLogs/Endpoints/ConsoleLogs/Sources/Endpoint.cs.
  • T061 [US3] Stream source status changes through SignalR in src/modules/Elsa.Diagnostics.ConsoleLogs/RealTime/ConsoleLogsHub.cs.
  • T062 [US3] Run dotnet test test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Elsa.Diagnostics.ConsoleLogs.UnitTests.csproj.

Checkpoint: All user stories are independently functional and source-aware.

Phase 6: Documentation & Polish

Purpose: Update public docs, sample guidance, boundary assertions, and validation.

  • T063 [P] Add console logs README in src/modules/Elsa.Diagnostics.ConsoleLogs/README.md.
  • T064 [P] Update quickstart implementation notes in specs/006-diagnostics-console-logs/quickstart.md.
  • T065 [P] Add module boundary assertions in test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/ConsoleLogsModuleTests.cs.
  • T066 Update sample host wiring only if the sample opts into console logs in src/apps/Elsa.Server.Web/Program.cs.
  • T067 Run dotnet build src/modules/Elsa.Diagnostics.ConsoleLogs/Elsa.Diagnostics.ConsoleLogs.csproj.
  • T068 Run dotnet test test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Elsa.Diagnostics.ConsoleLogs.UnitTests.csproj.
  • T069 Run dotnet test test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/Elsa.Diagnostics.ConsoleLogs.IntegrationTests.csproj.
  • T070 Run rg "StructuredLogs|OpenTelemetry|Kubernetes|Docker|OTLP|Loki|Seq" src/modules/Elsa.Diagnostics.ConsoleLogs specs/006-diagnostics-console-logs and record boundary findings in specs/006-diagnostics-console-logs/tasks.md.

Dependencies & Execution Order

Phase Dependencies

  • Phase 1 Setup: No dependencies.
  • Phase 2 Foundational: Depends on Phase 1 and blocks all user stories.
  • Phase 3 US1: Depends on Phase 2; MVP.
  • Phase 4 US2: Depends on Phase 2 and should follow US1 validation for an end-to-end capture path.
  • Phase 5 US3: Depends on Phase 2 and can proceed after provider/source contracts exist, but final validation should follow US1.
  • Phase 6 Polish: Depends on selected story implementation.

User Story Dependencies

  • US1 (P1): First executable slice; no dependency on US2 or US3.
  • US2 (P2): Uses US1 capture/provider surfaces but remains independently testable through redaction, filtering, authorization, and hub filter updates.
  • US3 (P3): Uses shared provider/source contracts and adds multi-source behavior without changing US1 or US2 contracts.

Parallel Opportunities

  • T001 through T003 and T005 through T007 can run in parallel.
  • T008 through T016 and T021 through T022 can run in parallel after project creation.
  • US1 tests T023 through T028 can run in parallel.
  • US2 tests T038 through T042 can run in parallel.
  • US3 tests T051 through T055 can run in parallel.
  • Documentation tasks T063 through T065 can run in parallel after implementation APIs settle.

Parallel Example: User Story 1

Task: "Add capture tee preservation tests in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Capture/ConsoleCaptureTeeTests.cs"
Task: "Add partial-line buffering and idle flush tests in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Capture/ConsoleLineBufferTests.cs"
Task: "Add truncation and ANSI default handling tests in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Capture/ConsoleLineFormatterTests.cs"
Task: "Add in-memory recent and live provider tests in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/InMemory/InMemoryConsoleLogProviderTests.cs"

Parallel Example: User Story 2

Task: "Add redaction tests for line text and source metadata in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Redaction/ConsoleLogRedactorTests.cs"
Task: "Add filter evaluator tests for source, stream, query, time range, and limit in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Filtering/ConsoleLogFilterTests.cs"
Task: "Add authorization tests for recent and source endpoints in test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/ConsoleLogsAuthorizationTests.cs"
Task: "Add SignalR authorization and filter-update tests in test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/ConsoleLogsHubAuthorizationTests.cs"

Parallel Example: User Story 3

Task: "Add source registry tests for current source metadata and health transitions in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/Sources/ConsoleLogSourceRegistryTests.cs"
Task: "Add multi-source ordering tests in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/InMemory/InMemoryConsoleLogProviderSourceTests.cs"
Task: "Add dropped-line summary tests for buffer and subscriber overflow in test/unit/Elsa.Diagnostics.ConsoleLogs.UnitTests/InMemory/InMemoryConsoleLogProviderDroppedLineTests.cs"
Task: "Add source endpoint integration tests in test/integration/Elsa.Diagnostics.ConsoleLogs.IntegrationTests/ConsoleLogsSourcesEndpointTests.cs"

Implementation Strategy

MVP First

  1. Complete Phase 1 and Phase 2.
  2. Complete Phase 3 only.
  3. Run the US1 unit and integration tests.
  4. Stop and validate recent backfill, live stdout/stderr streaming, and preserved console output.

Incremental Delivery

  1. US1: raw stdout/stderr capture, bounded recent history, and live streaming.
  2. US2: authorization, filtering, redaction, and provider-boundary safety.
  3. US3: source health, multi-source ordering, dropped summaries, and source endpoint behavior.
  4. Polish: docs, sample guidance, boundary checks, builds, and tests.

Notes

  • Boundary scan result: only explicit out-of-scope documentation references were found; source matches for Sequence and StripAnsiEscapeSequences are expected identifier matches, not external provider integrations.
  • Do not touch elsa-studio for this Core feature.
  • Do not implement durable console log persistence in this feature.
  • Do not implement Kubernetes, Docker, vendor sink, or OpenTelemetry integrations.
  • Preserve redaction-before-provider boundaries.
  • Keep Elsa.Diagnostics.StructuredLogs separate from console logs.