| name | error-tracking |
| description | Implement error tracking and observability using Prometheus (metrics) and Loki (logs). Covers centralized exception handling, structured logging, and performance monitoring for .NET services. |
| type | guardrail |
| enforcement | suggest |
| priority | high |
ABOUTME: Error handling + observability rules for .NET services.
ABOUTME: Read referenced resources before applying.
Error Tracking & Observability Guidelines
Project-Agnostic Observability Patterns for .NET
Placeholders use {Placeholder} syntax - see docs/TEMPLATE_GLOSSARY.md.
Purpose
Standardize error handling + observability with OpenTelemetry, Prometheus, Loki.
When This Skill Activates
- Keywords: error handling, logging, observability, metrics, tracing
- File patterns:
**/Program.cs, **/*Controller.cs, **/*Handler.cs, **/*.razor
Non‑Inferable Rules (Must Follow)
- Do not swallow exceptions.
- Use RFC 7807 ProblemDetails for API errors.
- Sentry is not used — use OTEL + Prometheus + Loki.
- Chained IExceptionHandler (not middleware):
ValidationExceptionHandler (handles validation exceptions → 400) → GlobalExceptionHandler (catch-all → 500 in prod, full detail in dev). Each returns true to stop the chain once handled.
- .NET 10 handled-exception diagnostics:
app.UseExceptionHandler() currently runs without a SuppressDiagnosticsCallback override. In .NET 10, handled exceptions may suppress logs/metrics/events by default once an IExceptionHandler returns true. Treat this as an explicit observability decision when editing exception handling.
- RFC 7807 extensions: All ProblemDetails include
traceId (HttpContext.TraceIdentifier), timestamp (ISO 8601), and correlationId when available. 500 errors hide detail in production.
- CorrelationIdMiddleware: Reads
X-Correlation-ID or X-Request-ID from inbound requests, generates GUID if absent, pushes to Serilog.LogContext. Added to response headers.
- RequestLoggingMiddleware: Structured logging with method, path, status, duration, userId, tenantId, correlationId.
- BusinessMetrics (OpenTelemetry): Meter
"Explore.Business" with counters: events.created, events.published, registrations.created, organizations.created, authorization.decisions. All tagged with tenant_id, resource_type.
- PerformanceBehavior (MediatR pipeline): Warning for >500ms, error for >3000ms. Includes handler name and elapsed time.
- Rate limiting 429: Rejection response is RFC 6585 ProblemDetails with
Retry-After when available plus X-RateLimit-Limit and X-RateLimit-Remaining.
Resources (Read Before Applying)
Related Documentation
