Observability & Logging
Relevant source files
The following files were used as context for generating this wiki page:
- app/Support/Observability/DomainLogger.php
- app/Support/Observability/SensitiveDataRedactor.php
- app/Support/Observability/LogContext.php
- config/observability.php
- app/Console/Commands/ObservabilityHealthCommand.php
- tests/Feature/Observability/DomainLoggerTest.php
- tests/Feature/Docs/Phase54ObservabilityDocTest.php
The Observability & Logging system in RateGuru provides a structured foundation for monitoring domain events, ensuring data privacy through redaction, and maintaining request traceability. It shifts logging from simple text messages to structured data objects that include request IDs, security tags, and performance metrics.
The system is designed to facilitate debugging in production environments while strictly adhering to security requirements, such as redacting sensitive information (e.g., passwords) before they reach the log storage.
Sources: tests/Feature/Docs/Phase54ObservabilityDocTest.php:9-12, app/Support/Observability/DomainLogger.php:7-15
Domain Logging Architecture
The core of the observability system is the DomainLogger, which wraps the standard Laravel logging facility to enforce structure and privacy. It categorizes events into levels such as info, warning, error, and a specialized security type.
Data Flow for Log Events
When a domain event occurs, data flows through several layers of processing—context enrichment, data redaction, and finally, dispatching to the configured log channel.
The diagram shows the transformation of raw event data into structured, redacted logs.
Sources: app/Support/Observability/DomainLogger.php:20-55, tests/Feature/Observability/DomainLoggerTest.php:48-73
Key Components
| Component | Responsibility |
|---|---|
DomainLogger | Primary API for logging structured domain events. |
LogContext | Manages global metadata, specifically the unique Request ID. |
SensitiveDataRedactor | Identifies and masks sensitive keys in the log payload. |
ObservabilityHealthCommand | CLI tool to verify configuration and vendor status. |
Sources: app/Support/Observability/DomainLogger.php, app/Support/Observability/LogContext.php, app/Support/Observability/SensitiveDataRedactor.php, app/Console/Commands/ObservabilityHealthCommand.php
Data Privacy & Redaction
Security is integrated into the logging pipeline via the SensitiveDataRedactor. Before any data is written to the logs, the payload is scanned for sensitive keys. If a match is found, the value is replaced with a [redacted] placeholder.
Redaction Logic
The system targets specific keys defined in the observability.php configuration. Common targets include:
passwordpassword_confirmationtokenapi_key
Sources: app/Support/Observability/SensitiveDataRedactor.php:12-25, tests/Feature/Observability/DomainLoggerTest.php:65-74, app/Console/Commands/ObservabilityHealthCommand.php:41-48
Request Traceability
Every log entry is automatically tagged with a request_id. This allows developers to correlate multiple log lines originating from a single HTTP request or background job execution.
The sequence shows how the LogContext provides the necessary metadata to the DomainLogger.
Sources: app/Support/Observability/LogContext.php:7-15, app/Support/Observability/DomainLogger.php:60-65, tests/Feature/Observability/DomainLoggerTest.php:57-63
Configuration and Health
The observability system behavior is controlled via config/observability.php. Developers can verify the health of these configurations using the rateguru:observability:health command.
Health Check Metrics
The health command evaluates the following:
- Request ID: Confirms the header name used for tracing.
- Redaction Status: Checks if redaction is enabled and lists protected keys.
- Slow Actions: Verifies thresholds for logging slow operations.
- External Vendors: Reports the configuration status of optional integrations like Sentry, Datadog, or Nightwatch.
Sources: app/Console/Commands/ObservabilityHealthCommand.php:17-33, app/Console/Commands/ObservabilityHealthCommand.php:59-73
Configuration Options
| Option | Type | Description |
|---|---|---|
request_id.header | string | The HTTP header name for the request ID (e.g., X-Request-ID). |
redaction.enabled | boolean | Whether sensitive data stripping is active. |
redaction.keys | array | List of field names to redact in log payloads. |
slow_actions.default_threshold_ms | integer | Milliseconds before an action is logged as "slow". |
Sources: app/Console/Commands/ObservabilityHealthCommand.php:35-57, config/observability.php
Summary
Observability in RateGuru ensures that domain events are captured in a structured, searchable format without compromising user privacy. By enforcing a unified logging pipeline through the DomainLogger, the project maintains high standards for security (via redaction) and debuggability (via Request IDs and health monitoring).
Sources: tests/Feature/Docs/Phase54ObservabilityDocTest.php:9-14, app/Support/Observability/DomainLogger.php:7-18