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

193 lines
12 KiB
Markdown
Raw Blame History

# Tasks: Diagnostics Structured Logs
**Input**: Design documents from `/specs/004-diagnostics-structured-logs/`
**Prerequisites**: [plan.md](./plan.md), [spec.md](./spec.md), [research.md](./research.md), [data-model.md](./data-model.md), [contracts/](./contracts), [quickstart.md](./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](./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.
- [X] T001 Rename `src/modules/Elsa.ServerLogs/Elsa.ServerLogs.csproj` to `src/modules/Elsa.Diagnostics.StructuredLogs/Elsa.Diagnostics.StructuredLogs.csproj`.
- [X] T002 Rename `test/unit/Elsa.ServerLogs.UnitTests/Elsa.ServerLogs.UnitTests.csproj` to `test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/Elsa.Diagnostics.StructuredLogs.UnitTests.csproj`.
- [X] T003 Rename `test/integration/Elsa.ServerLogs.IntegrationTests/Elsa.ServerLogs.IntegrationTests.csproj` to `test/integration/Elsa.Diagnostics.StructuredLogs.IntegrationTests/Elsa.Diagnostics.StructuredLogs.IntegrationTests.csproj`.
- [X] T004 Update `Elsa.sln` project names and paths for the renamed module and test projects.
- [X] 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.
- [X] T006 Rename namespaces from `Elsa.ServerLogs` to `Elsa.Diagnostics.StructuredLogs` across `src/modules/Elsa.Diagnostics.StructuredLogs`.
- [X] T007 [P] Rename model types in `src/modules/Elsa.Diagnostics.StructuredLogs/Models` from `ServerLog*` to `StructuredLog*`.
- [X] T008 [P] Rename provider contracts in `src/modules/Elsa.Diagnostics.StructuredLogs/Contracts` from `IServerLog*` to `IStructuredLog*`.
- [X] T009 [P] Rename option type `ServerLogStreamingOptions` to `StructuredLogsOptions` in `src/modules/Elsa.Diagnostics.StructuredLogs/Options/StructuredLogsOptions.cs`.
- [X] T010 [P] Rename permission type and value in `src/modules/Elsa.Diagnostics.StructuredLogs/Permissions/StructuredLogsPermissions.cs`.
- [X] T011 Rename service, logging, provider, and real-time types in `src/modules/Elsa.Diagnostics.StructuredLogs` to structured-log names.
- [X] T012 Update source code references after renames in `src/modules/Elsa.Diagnostics.StructuredLogs`.
- [X] 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
- [X] T014 [P] [US1] Update module identity assertions in `test/integration/Elsa.Diagnostics.StructuredLogs.IntegrationTests/StructuredLogsModuleTests.cs`.
- [X] T015 [P] [US1] Add route and permission naming assertions in `test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/StructuredLogsNamingTests.cs`.
- [X] T016 [P] [US1] Add shell feature option binding assertions in `test/integration/Elsa.Diagnostics.StructuredLogs.IntegrationTests/StructuredLogsModuleTests.cs`.
### Implementation for User Story 1
- [X] T017 [US1] Rename Core feature to `StructuredLogsFeature` in `src/modules/Elsa.Diagnostics.StructuredLogs/Features/StructuredLogsFeature.cs`.
- [X] T018 [US1] Rename fluent module extension to `UseStructuredLogs` in `src/modules/Elsa.Diagnostics.StructuredLogs/Extensions/ModuleExtensions.cs`.
- [X] T019 [US1] Rename application/hub mapping extension to `UseStructuredLogs` and `MapStructuredLogsHub` in `src/modules/Elsa.Diagnostics.StructuredLogs/Extensions`.
- [X] T020 [US1] Move FastEndpoints folders/routes to diagnostics structured-log names in `src/modules/Elsa.Diagnostics.StructuredLogs/Endpoints/StructuredLogs`.
- [X] T021 [US1] Rename shell feature to diagnostics structured logs and keep bindable public option properties in `src/modules/Elsa.Diagnostics.StructuredLogs/ShellFeatures/StructuredLogsFeature.cs`.
- [X] T022 [US1] Update sample host wiring to `UseStructuredLogs` in `src/apps/Elsa.Server.Web/Program.cs`.
- [X] 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
- [X] T024 [P] [US2] Add message template capture tests in `test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/Logging/StructuredLogLoggerProviderTests.cs`.
- [X] T025 [P] [US2] Add active scope capture tests in `test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/Logging/StructuredLogLoggerProviderTests.cs`.
- [X] T026 [P] [US2] Update redaction tests for renamed scope/property models in `test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/Redaction/StructuredLogRedactorTests.cs`.
- [X] T027 [P] [US2] Update filter/provider tests for renamed semantic fields in `test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests`.
### Implementation for User Story 2
- [X] T028 [US2] Implement `ISupportExternalScope` in `src/modules/Elsa.Diagnostics.StructuredLogs/Logging/StructuredLogLoggerProvider.cs`.
- [X] T029 [US2] Capture active scopes in `src/modules/Elsa.Diagnostics.StructuredLogs/Logging/StructuredLogLogger.cs`.
- [X] T030 [US2] Populate `MessageTemplate` from `{OriginalFormat}` in `src/modules/Elsa.Diagnostics.StructuredLogs/Logging/StructuredLogLogger.cs`.
- [X] T031 [US2] Keep `{OriginalFormat}` out of structured properties in `src/modules/Elsa.Diagnostics.StructuredLogs/Logging/StructuredLogLogger.cs`.
- [X] T032 [US2] Preserve redaction of messages, exceptions, scopes, and structured properties in `src/modules/Elsa.Diagnostics.StructuredLogs/Services/StructuredLogRedactor.cs`.
- [X] 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
- [X] T034 [P] [US3] Add README boundary assertions or doc smoke coverage in `test/integration/Elsa.Diagnostics.StructuredLogs.IntegrationTests/StructuredLogsModuleTests.cs`.
- [X] T035 [P] [US3] Add route contract assertions for diagnostics paths in `test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/StructuredLogsNamingTests.cs`.
### Implementation for User Story 3
- [X] T036 [US3] Update README boundary language in `src/modules/Elsa.Diagnostics.StructuredLogs/README.md`.
- [X] T037 [US3] Ensure REST routes use `/diagnostics/structured-logs` in `src/modules/Elsa.Diagnostics.StructuredLogs/Endpoints/StructuredLogs`.
- [X] T038 [US3] Ensure SignalR route uses `/elsa/hubs/diagnostics/structured-logs` in `src/modules/Elsa.Diagnostics.StructuredLogs/Extensions/EndpointRouteBuilderExtensions.cs`.
- [X] T039 [US3] Ensure permission value is `read:diagnostics:structured-logs` in `src/modules/Elsa.Diagnostics.StructuredLogs/Permissions/StructuredLogsPermissions.cs`.
- [X] 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.
- [X] T041 [P] Remove active `Elsa.ServerLogs` references from production source, tests, projects, README, and sample host wiring.
- [X] T042 [P] Remove active `ServerLogStreaming` references from production source, tests, projects, README, and sample host wiring.
- [X] T043 [P] Update generated XML include filters in renamed test `.csproj` files.
- [X] T044 Run `dotnet build src/modules/Elsa.Diagnostics.StructuredLogs/Elsa.Diagnostics.StructuredLogs.csproj`.
- [X] T045 Run `dotnet test test/unit/Elsa.Diagnostics.StructuredLogs.UnitTests/Elsa.Diagnostics.StructuredLogs.UnitTests.csproj`.
- [X] T046 Run `dotnet test test/integration/Elsa.Diagnostics.StructuredLogs.IntegrationTests/Elsa.Diagnostics.StructuredLogs.IntegrationTests.csproj`.
- [X] 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
```text
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.
Reference in a new issue View git blame Copy permalink