feat(operational): add Operational package family for diagnostics and resilience - #61
Merged
Merged
Conversation
- Add diagnostic request headers for debugging, tracing, event logging, cache control, and performance profiling - Implement thread-safe event capture for traces, breadcrumbs, errors, and exceptions - Add configurable trace filtering, sensitive-data obfuscation, and automatic masking - Support forwarding enabled diagnostic events to the disk event log
- Capture exceptions, errors, and breadcrumbs through the diagnostics service - Enrich captured issues with caller member, file, and line context - Preserve exception metadata and attach supplemental capture data - Prevent capture failures from escaping while logging forwarding errors
- Add auto-discoverable Operational feature module with shared feature-flag resolution - Register NoOp diagnostics and issue services when the feature is disabled - Register diagnostics, issue capture, event logging, retry policies, and logging provider when enabled - Preserve standalone Operational registration without requiring the Features engine
- Add explicit DI registration for diagnostics, issue capture, event logging, retries, and logging - Register NoOp services and avoid background work when Operational is disabled - Add application startup integration for eager event-log writer initialization and retention cleanup - Keep Operational usable without requiring the Features framework
- Define the net8.0 Operational package with documentation and NuGet metadata - Reference Operational abstractions, feature integration, and sanitization contracts - Add ASP.NET Core framework support and Polly resilience dependencies - Include package README and NuGet icon assets
- Document diagnostics, issue capture, logging, event writing, retention, and resilience components - Add explicit DI and optional Features Framework integration examples - Describe configuration, package dependencies, target framework, and design boundaries - Clarify dependency injection, correlation ID, and Windows Event Log provider decisions
- Add abstractions for request diagnostics, issue management, and event viewer integration - Define trace, breadcrumb, exception, and error capture APIs with contextual metadata - Establish sanitized payload, obfuscation, feature-state, and event-log capabilities - Preserve provider isolation through pluggable event viewer and future issue-tracking implementations
- Add enablement control with safe NoOp behavior by default - Configure disk event-log location, retention period, and application naming - Define default logging level and retry attempt limits for HTTP and method-level policies
- Add breadcrumb levels for application flow checkpoints - Add diagnostic event types for traces, breadcrumbs, exceptions, and errors - Add trace levels for filtering diagnostic event severity - Enable string-based JSON serialization for diagnostic event types
- Add diagnostic event and payload models with timestamp, severity, message, stack trace, and data - Add platform-neutral event viewer log entry model for pluggable providers - Add sensitive data attribute for configurable property masking - Configure JSON serialization to omit null diagnostic fields
- Provide inert diagnostics, issue management, and event viewer services for disabled Operational flows - Preserve dependency resolution without producing events or starting downstream work - Pass exceptions through unchanged while keeping capture operations non-throwing - Establish provider override floors for future platform-specific implementations
- Write diagnostic events as NDJSON through a background queue - Organize log files by application, date, and correlation identifier - Add per-file synchronization and best-effort event viewer failure forwarding - Add asynchronous retention cleanup for expired date-partitioned logs - Support graceful writer shutdown through disposal
- Add custom logger and provider that forward traces and exceptions to request diagnostics - Map Microsoft logging levels to operational trace levels and honor request trace-level headers - Sanitize log messages and exception data before diagnostics, disk, or event viewer forwarding - Cache loggers by category and provide no-op scope and queued write request support
- Add shared HTTP resilience pipeline with exponential backoff, jitter, and circuit breaking - Retry transient server, timeout, rate-limit, and network failures while excluding permanent client errors - Provide synchronous and asynchronous retry policies for general operations - Log retry attempts and circuit state transitions - Use a no-op pipeline in detected test hosts to avoid backoff delays
- Test request-header enablement, trace filtering, event capture, and payload behavior - Verify issue capture forwarding, exception data enrichment, and safe failure handling - Cover asynchronous event-log writing, cleanup behavior, and disposal - Validate NoOp service guarantees and retry policy success paths
- Provide HTTP context accessors with configurable diagnostic headers - Add default operational options and inert event-log writer factories - Simplify isolated service setup without disk writes or active request contexts
- Configure net8.0 xUnit test project with coverage collection - Add test SDK, xUnit runner, and shared test project references - Keep the test project non-packable and nullable-enabled
- Define cross-platform netstandard2.0 and net8.0 targets for Operational contracts and NoOp services - Add NuGet metadata, generated documentation, README, and package icon configuration - Reference logging abstractions and System.Text.Json without requiring ASP.NET Core
- Describe framework-agnostic diagnostics, issue capture, event viewer, options, models, and NoOp services - Document supported target frameworks, dependency boundaries, and zero-registration behavior - Add namespace usage examples and explain optional Features Framework integration
- Document package roles, dependency direction, public contracts, models, and configuration - Describe diagnostics, issue capture, event logging, custom logging, retry policies, and DI integration - Record design decisions around NoOp safe-off behavior, provider isolation, sanitization, and concurrency - Capture two-layer feature gating, host integration examples, known gaps, risks, and future provider plans
- Add NuGet badges and package-family overview for Operational abstractions and implementation packages - Add package links, installation commands, usage examples, and diagnostic header guidance - Update target framework and ASP.NET Core support listings - Link Operational API and architecture documentation
- Document Operational package topology and standalone or Features Framework integration - Add independent Operational version-family rules and workflow dispatch configuration - Link Operational API and architecture references in the repository documentation index
- Add the sanitization package family to the repository versioning model - Define workflow dispatch ownership for sanitization releases
- Register Operational abstractions, implementation, and test projects - Add Debug and Release build configurations for the new projects - Organize Operational projects under a dedicated solution folder
- Define the PowerCSharpOperationalVersion property at version 1.0.0 - Document the package family scope covering diagnostics, logging, event logging, and resilience
- Return null from trace, breadcrumb, exception, and error capture methods when diagnostics are not enabled - Align event-capture behavior with the diagnostics service contract and NoOp expectations
- Replace exact event-count assertion with a non-empty check to avoid brittle expectations
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR introduces the PowerCSharp.Operational package family, providing opt-in application diagnostics, issue capture, operational logging, and HTTP resilience for ASP.NET Core applications.
Adds PowerCSharp.Operational.Abstractions with zero-dependency contracts, models, enums, options, sensitive-data annotations, and safe NoOp implementations for diagnostics, issue management, and event-viewer logging.
Adds PowerCSharp.Operational with:
Supports two-layer gating: services can be omitted entirely, registered as safe NoOp implementations, or enabled as full operational services through configuration and feature flags.
Adds comprehensive tests for diagnostics behavior, issue capture, NoOp implementations, disk event logging, and retry policy handling.
Adds package documentation, architecture guidance, root README updates, solution registration, and an independent PowerCSharpOperationalVersion package family.
No existing package APIs are changed.