elsa-core/specs/004-diagnostics-structured-logs/plan.md

Implementation Plan: Diagnostics Structured Logs

Branch: 004-diagnostics-structured-logs | Date: 2026-05-10 | Spec: spec.md
Input: Feature specification from /specs/004-diagnostics-structured-logs/spec.md

Summary

Refactor the unpublished Elsa.ServerLogs module into Elsa.Diagnostics.StructuredLogs, preserving its structured ILogger capture, redaction, bounded in-memory recent history, source metadata, REST API, and SignalR stream while removing names that imply raw stdout/stderr console capture. Add semantic improvements for message template capture from {OriginalFormat} and active logging scope capture.

Technical Context

Language/Version: C# latest, nullable reference types enabled, implicit usings enabled.
Primary Dependencies: Microsoft.Extensions.Logging, Microsoft.Extensions.Options, Microsoft.AspNetCore.SignalR, Elsa feature/module infrastructure, FastEndpoints through Elsa API endpoint patterns, CShells shell feature infrastructure.
Storage: Existing bounded in-memory ring buffer; no EF Core schema changes. Provider abstraction remains available for future shared backends.
Testing: Existing xUnit unit and integration projects renamed with the module; add focused unit tests for message templates, scopes, route/permission constants, and shell option binding.
Target Platform: ASP.NET Core Elsa Server on the repository's supported .NET target frameworks.
Project Type: Modular .NET library inside the existing Elsa solution.
Performance Goals: Preserve bounded memory behavior and live delivery expectations from the current module; no extra unbounded scope/property allocations beyond per-event dictionaries.
Constraints: Breaking rename is acceptable before release; direct stdout/stderr capture and OpenTelemetry trace exploration are out of scope. Redaction must run before buffering or streaming.
Scale/Scope: Rename one Core module, test projects, sample host wiring, routes, permissions, public contracts, shell feature identity, docs, and Speckit artifacts.

Constitution Check

Evaluated against .specify/memory/constitution.md v1.1.0:

Principle	Verdict	Evidence
I. Modular Architecture	PASS	The feature remains a focused module under src/modules/Elsa.Diagnostics.StructuredLogs with contracts, services, endpoints, hub, and feature registration.
II. Composition & Extensibility	PASS	Provider, redactor, source registry, and options boundaries are preserved under structured-log names.
III. Convention-Driven Design	PASS	Rename follows Elsa feature, extension, endpoint, shell feature, and test naming patterns.
IV. Async & Pipeline Execution	PASS	Provider query/subscribe APIs, hub methods, and endpoints remain async and cancellation-aware.
V. Testing Discipline	PASS	Unit/integration tests are renamed and expanded for the new semantic capture requirements.
VI. Trunk-Based Development	PASS	Work is scoped to a single unpublished feature refactor and can merge independently from Studio.
VII. Simplicity, SRP, DRY & KISS	PASS	No durable storage, console redirection, or OpenTelemetry explorer behavior is added.

Project Structure

Documentation (this feature)

specs/004-diagnostics-structured-logs/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── rest-api.md
│   ├── signalr-hub.md
│   └── provider-contract.md
├── checklists/
│   └── requirements.md
└── tasks.md

Source Code (repository root)

src/modules/
└── Elsa.Diagnostics.StructuredLogs/
    ├── Contracts/
    │   ├── IStructuredLogProvider.cs
    │   ├── IStructuredLogRedactor.cs
    │   ├── IStructuredLogSourceRegistry.cs
    │   └── IStructuredLogStreamProvider.cs
    ├── Endpoints/StructuredLogs/
    │   ├── Recent/Endpoint.cs
    │   └── Sources/Endpoint.cs
    ├── Extensions/
    ├── Features/StructuredLogsFeature.cs
    ├── Logging/
    ├── Models/
    ├── Options/StructuredLogsOptions.cs
    ├── Permissions/StructuredLogsPermissions.cs
    ├── Providers/InMemory/
    ├── RealTime/StructuredLogsHub.cs
    ├── Services/
    └── ShellFeatures/StructuredLogsFeature.cs

test/unit/
└── Elsa.Diagnostics.StructuredLogs.UnitTests/

test/integration/
└── Elsa.Diagnostics.StructuredLogs.IntegrationTests/

Structure Decision: Move the existing module and tests to diagnostics structured-log names. Do not create new modules for console streaming or OpenTelemetry exploration in this feature.

Phase 0 Output

See research.md.

Resolved decisions:

• Perform a consistent breaking rename instead of obsolete shims.
• Keep the existing in-memory provider and API/hub shape, with diagnostics structured-log routes.
• Capture message templates from {OriginalFormat} while excluding that key from structured properties.
• Capture active logging scopes through the logging provider's external scope provider.
• Preserve redaction, recursion guard, bounded buffers, source metadata, and dropped-event summaries.

Phase 1 Output

• data-model.md
• contracts/rest-api.md
• contracts/signalr-hub.md
• contracts/provider-contract.md
• quickstart.md

Post-Design Constitution Re-Check

Principle	Verdict	Post-design evidence
I. Modular Architecture	PASS	All renamed code stays inside the structured logs module and exported contracts.
II. Composition & Extensibility	PASS	Provider/redactor/source registry contracts remain the extension points.
III. Convention-Driven Design	PASS	Public APIs use StructuredLog/StructuredLogs consistently.
IV. Async & Pipeline Execution	PASS	Contracts retain async signatures.
V. Testing Discipline	PASS	Tasks include focused regression tests for new semantic fields and renamed surfaces.
VI. Trunk-Based Development	PASS	Core-only implementation is independent of the separate Studio worker.
VII. Simplicity, SRP, DRY & KISS	PASS	Future diagnostics modules are referenced only in docs as out of scope.

Phase 2 Handoff

Use tasks.md as the implementation backlog. Suggested order:

1. Rename projects, solution entries, namespaces, public types, routes, and permissions.
2. Rename feature, shell feature, options, extensions, README, and sample host wiring.
3. Add message template and scope capture in the logger provider.
4. Rename and expand tests.
5. Run targeted builds/tests and commit any fixes.

Complexity Tracking

No constitution violations identified.