SemianiakaVY/elsa-core
1
0
Fork 0
Code Issues Pull requests Actions 1 Packages Projects Releases Wiki Activity
elsa-core/specs/004-diagnostics-structured-logs/tasks.md
Sipke Schoorstra ab3e46bbe2
[codex] Add live server log streaming diagnostics (#7438) 
* Add live server logs Spec Kit plan

* Implement live server logs diagnostics module

* Add server log sources and redaction hardening

* Add diagnostics unit tests

* Harden server log hub subscriptions

* Secure server log hub permissions

* Validate server log filter updates

* Add diagnostics logger and source tests

* Add diagnostics integration test project

* Add multi-source diagnostics provider coverage

* Broadcast server log source changes

* Document diagnostics server log streaming

* Add diagnostics sample host wiring

* Record diagnostics validation results

* Address server log PR feedback

* Rename diagnostics module to server logs

* Add server logs shell feature

* Make server logs shell options bindable

* Accept read wildcard for server logs

* Align server logs authorization with API patterns

* Update CShells structure and logging levels, add diagnostics module

* Rename PostgreSql shell feature classes for consistency

* Switch from Sqlite to PostgreSQL for workflow and identity persistence, add QuartzPostgreSql configuration

* Refactor server logs into diagnostics structured logs (#7440)

* Specify diagnostics structured logs refactor

* docs: clarify structured logs spec

* docs: plan diagnostics structured logs

* docs: add diagnostics structured logs tasks

* refactor: rename server logs to diagnostics structured logs

* Refactor PostgreSql persistence features to use centralized entity model handler registration.

* Refactor EFCore persistence features to centralize entity model handler registration for MySql, Sqlite, and Oracle providers.

* Integrate structured logs by renaming server logs, adjusting appsettings, and updating project references.

* Switch from PostgreSQL to Sqlite for workflow and identity persistence, update appsettings configuration.
2026-05-11 00:08:52 +02:00

12 KiB
Raw Blame History

Tasks: Diagnostics Structured Logs

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

Tests: Included because the specification defines independent tests for renamed module identity, semantic capture, redaction, scopes, filtering, live streams, and docs.

Organization: Tasks are grouped by user story so each increment can be validated 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 (Rename Skeleton)

Purpose: Move the existing unpublished module and tests to the diagnostics structured logs identity.

  • T001 Rename src/modules/Elsa.ServerLogs/Elsa.ServerLogs.csproj to src/modules/Elsa.Diagnostics.StructuredLogs/Elsa.Diagnostics.StructuredLogs.csproj.
  • T002 Rename test/unit/Elsa.ServerLogs.UnitTests/Elsa.ServerLogs.UnitTests.csproj to test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/Elsa.Diagnostics.StructuredLogs.UnitTests.csproj.
  • T003 Rename test/integration/Elsa.ServerLogs.IntegrationTests/Elsa.ServerLogs.IntegrationTests.csproj to test/integration/Elsa.Diagnostics.StructuredLogs.IntegrationTests/Elsa.Diagnostics.StructuredLogs.IntegrationTests.csproj.
  • T004 Update Elsa.sln project names and paths for the renamed module and test projects.
  • T005 Update sample host references in src/apps/Elsa.Server.Web/Elsa.Server.Web.csproj.

Phase 2: Foundational (Blocking Rename Prerequisites)

Purpose: Rename shared contracts, models, options, permissions, services, and folders before story-specific behavior changes.

Critical: No story work should begin until these shared names compile.

  • T006 Rename namespaces from Elsa.ServerLogs to Elsa.Diagnostics.StructuredLogs across src/modules/Elsa.Diagnostics.StructuredLogs.
  • T007 [P] Rename model types in src/modules/Elsa.Diagnostics.StructuredLogs/Models from ServerLog* to StructuredLog*.
  • T008 [P] Rename provider contracts in src/modules/Elsa.Diagnostics.StructuredLogs/Contracts from IServerLog* to IStructuredLog*.
  • T009 [P] Rename option type ServerLogStreamingOptions to StructuredLogsOptions in src/modules/Elsa.Diagnostics.StructuredLogs/Options/StructuredLogsOptions.cs.
  • T010 [P] Rename permission type and value in src/modules/Elsa.Diagnostics.StructuredLogs/Permissions/StructuredLogsPermissions.cs.
  • T011 Rename service, logging, provider, and real-time types in src/modules/Elsa.Diagnostics.StructuredLogs to structured-log names.
  • T012 Update source code references after renames in src/modules/Elsa.Diagnostics.StructuredLogs.
  • T013 Update test namespaces and project references in test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests and test/integration/Elsa.Diagnostics.StructuredLogs.IntegrationTests.

Checkpoint: Renamed projects and test projects should compile far enough to expose behavior-specific failures.

Phase 3: User Story 1 - Install a clearly named structured logs module (Priority: P1) MVP

Goal: Hosts enable a diagnostics structured logs module whose APIs, shell feature, installed feature name, routes, and docs no longer imply raw server console logs.

Independent Test: Build a host and tests using Elsa.Diagnostics.StructuredLogs, StructuredLogsFeature, UseStructuredLogs, diagnostics routes, and diagnostics permission names.

Tests for User Story 1

  • T014 [P] [US1] Update module identity assertions in test/integration/Elsa.Diagnostics.StructuredLogs.IntegrationTests/StructuredLogsModuleTests.cs.
  • T015 [P] [US1] Add route and permission naming assertions in test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/StructuredLogsNamingTests.cs.
  • T016 [P] [US1] Add shell feature option binding assertions in test/integration/Elsa.Diagnostics.StructuredLogs.IntegrationTests/StructuredLogsModuleTests.cs.

Implementation for User Story 1

  • T017 [US1] Rename Core feature to StructuredLogsFeature in src/modules/Elsa.Diagnostics.StructuredLogs/Features/StructuredLogsFeature.cs.
  • T018 [US1] Rename fluent module extension to UseStructuredLogs in src/modules/Elsa.Diagnostics.StructuredLogs/Extensions/ModuleExtensions.cs.
  • T019 [US1] Rename application/hub mapping extension to UseStructuredLogs and MapStructuredLogsHub in src/modules/Elsa.Diagnostics.StructuredLogs/Extensions.
  • T020 [US1] Move FastEndpoints folders/routes to diagnostics structured-log names in src/modules/Elsa.Diagnostics.StructuredLogs/Endpoints/StructuredLogs.
  • T021 [US1] Rename shell feature to diagnostics structured logs and keep bindable public option properties in src/modules/Elsa.Diagnostics.StructuredLogs/ShellFeatures/StructuredLogsFeature.cs.
  • T022 [US1] Update sample host wiring to UseStructuredLogs in src/apps/Elsa.Server.Web/Program.cs.
  • T023 [US1] Update package metadata in src/modules/Elsa.Diagnostics.StructuredLogs/Elsa.Diagnostics.StructuredLogs.csproj.

Checkpoint: User Story 1 is functional through code-based and shell-based module activation.

Phase 4: User Story 2 - Preserve semantic log data for inspection (Priority: P2)

Goal: Captured records include rendered messages, original templates, structured properties, active scopes, exceptions, source metadata, and trace/span IDs after redaction.

Independent Test: Emit ILogger calls with message templates, named arguments, scopes, exceptions, workflow/correlation context, and active Activity; verify captured semantic fields.

Tests for User Story 2

  • T024 [P] [US2] Add message template capture tests in test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/Logging/StructuredLogLoggerProviderTests.cs.
  • T025 [P] [US2] Add active scope capture tests in test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/Logging/StructuredLogLoggerProviderTests.cs.
  • T026 [P] [US2] Update redaction tests for renamed scope/property models in test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/Redaction/StructuredLogRedactorTests.cs.
  • T027 [P] [US2] Update filter/provider tests for renamed semantic fields in test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests.

Implementation for User Story 2

  • T028 [US2] Implement ISupportExternalScope in src/modules/Elsa.Diagnostics.StructuredLogs/Logging/StructuredLogLoggerProvider.cs.
  • T029 [US2] Capture active scopes in src/modules/Elsa.Diagnostics.StructuredLogs/Logging/StructuredLogLogger.cs.
  • T030 [US2] Populate MessageTemplate from {OriginalFormat} in src/modules/Elsa.Diagnostics.StructuredLogs/Logging/StructuredLogLogger.cs.
  • T031 [US2] Keep {OriginalFormat} out of structured properties in src/modules/Elsa.Diagnostics.StructuredLogs/Logging/StructuredLogLogger.cs.
  • T032 [US2] Preserve redaction of messages, exceptions, scopes, and structured properties in src/modules/Elsa.Diagnostics.StructuredLogs/Services/StructuredLogRedactor.cs.
  • T033 [US2] Preserve recursion guard for internal structured-log categories in src/modules/Elsa.Diagnostics.StructuredLogs/Logging/StructuredLogLogger.cs.

Checkpoint: User Stories 1 and 2 work together with semantic template/scope capture and existing safety behavior.

Phase 5: User Story 3 - Keep structured logs separate from console logs and telemetry exploration (Priority: P3)

Goal: Contracts and documentation make the module boundary clear: structured ILogger events only, not stdout/stderr capture or trace/metric exploration.

Independent Test: Review API routes, hub routes, models, permissions, docs, and feature metadata for structured-log naming and explicit out-of-scope notes.

Tests for User Story 3

  • T034 [P] [US3] Add README boundary assertions or doc smoke coverage in test/integration/Elsa.Diagnostics.StructuredLogs.IntegrationTests/StructuredLogsModuleTests.cs.
  • T035 [P] [US3] Add route contract assertions for diagnostics paths in test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/StructuredLogsNamingTests.cs.

Implementation for User Story 3

  • T036 [US3] Update README boundary language in src/modules/Elsa.Diagnostics.StructuredLogs/README.md.
  • T037 [US3] Ensure REST routes use /diagnostics/structured-logs in src/modules/Elsa.Diagnostics.StructuredLogs/Endpoints/StructuredLogs.
  • T038 [US3] Ensure SignalR route uses /elsa/hubs/diagnostics/structured-logs in src/modules/Elsa.Diagnostics.StructuredLogs/Extensions/EndpointRouteBuilderExtensions.cs.
  • T039 [US3] Ensure permission value is read:diagnostics:structured-logs in src/modules/Elsa.Diagnostics.StructuredLogs/Permissions/StructuredLogsPermissions.cs.
  • T040 [US3] Update Speckit quickstart validation notes in specs/004-diagnostics-structured-logs/quickstart.md.

Checkpoint: Structured logs, console streaming, and OpenTelemetry exploration have clean documented boundaries.

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Search cleanup, validation, and implementation commit readiness.

  • T041 [P] Remove active Elsa.ServerLogs references from production source, tests, projects, README, and sample host wiring.
  • T042 [P] Remove active ServerLogStreaming references from production source, tests, projects, README, and sample host wiring.
  • T043 [P] Update generated XML include filters in renamed test .csproj files.
  • T044 Run dotnet build src/modules/Elsa.Diagnostics.StructuredLogs/Elsa.Diagnostics.StructuredLogs.csproj.
  • T045 Run dotnet test test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/Elsa.Diagnostics.StructuredLogs.UnitTests.csproj.
  • T046 Run dotnet test test/integration/Elsa.Diagnostics.StructuredLogs.IntegrationTests/Elsa.Diagnostics.StructuredLogs.IntegrationTests.csproj.
  • T047 Run rg "Elsa\\.ServerLogs|ServerLogStreaming|server-logs|read:server-logs" src test.

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 can run after or alongside US1 implementation once names compile.
  • Phase 5 US3: Depends on route/permission names from US1.
  • Phase 6 Polish: Depends on selected story implementation.

User Story Dependencies

  • US1 (P1): First executable slice; establishes final module identity.
  • US2 (P2): Builds on renamed logging provider and models.
  • US3 (P3): Builds on renamed routes, permissions, and docs.

Parallel Opportunities

  • T002 and T003 can run in parallel after T001.
  • T007 through T010 can run in parallel once the module folder is renamed.
  • US1 tests T014 through T016 can run in parallel.
  • US2 tests T024 through T027 can run in parallel.
  • US3 tests T034 and T035 can run in parallel.
  • Polish checks T041 through T043 can run in parallel before builds/tests.

Parallel Example: User Story 2

Task: "Add message template capture tests in test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/Logging/StructuredLogLoggerProviderTests.cs"
Task: "Add active scope capture tests in test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/Logging/StructuredLogLoggerProviderTests.cs"
Task: "Update redaction tests for renamed scope/property models in test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/Redaction/StructuredLogRedactorTests.cs"
Task: "Update filter/provider tests for renamed semantic fields in test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests"

Implementation Strategy

MVP First

  1. Complete Phase 1 and Phase 2.
  2. Complete Phase 3 only.
  3. Build the module and verify code/shell activation names.
  4. Continue to semantic capture after the renamed surface is stable.

Incremental Delivery

  1. US1: consistent diagnostics structured logs identity.
  2. US2: message templates, scopes, and preserved structured data.
  3. US3: documented module boundary and diagnostics contracts.
  4. Polish: search cleanup, builds, and tests.

Notes

  • Do not modify the separate elsa-studio repository.
  • Do not implement console stdout/stderr capture in this feature.
  • Do not implement OpenTelemetry trace or metric exploration in this feature.
  • Preserve bounded buffering, source behavior, redaction order, and dropped-event summaries.