Logging & Error Handling
Relevant source files
The following files were used as context for generating this wiki page:
Logging and error handling within SecretForge AI are designed to provide high-level observability, security auditing, and robust failure recovery across its edge-native architecture. The system utilizes structured logging to capture context-rich data, performance metrics to monitor global latency, and standardized error responses to ensure a consistent developer experience.
The architecture prioritizes security by ensuring that sensitive secret values are never logged, while maintaining a comprehensive audit trail with timestamps and unique identifiers for every operation. This framework supports compliance requirements such as SOC 2 and GDPR by tracking access patterns and identifying anomalies in real-time.
Sources: packages/api/src/utils/logger.ts:1-5, SECURITY_SUMMARY.md:68-75, README.md:129-135
Structured Logging Architecture
SecretForge AI employs a centralized Logger class that produces structured JSON logs. These logs are compatible with Cloudflare Workers' console output and include standardized fields such as log levels, ISO timestamps, and contextual metadata like Request IDs and User IDs.
Logging Components
The logging system consists of several specialized classes designed for different monitoring needs:
| Component | Purpose | Key Features |
|---|---|---|
| Logger | General-purpose structured logging | Support for levels (DEBUG to FATAL), context merging, and child loggers. |
| PerformanceMonitor | Latency and timing tracking | Records execution duration and generates P50/P95/P99 statistics. |
| ErrorTracker | Failure frequency monitoring | Tracks error types and triggers fatal alerts on high-frequency repetition. |
| HealthChecker | System status verification | Runs registered checks to determine if the system is 'healthy' or 'degraded'. |
| MetricsCollector | Quantitative data gathering | Collects counters, gauges, and histograms for monitoring trends. |
Sources: packages/api/src/utils/logger.ts:7-248
Log Levels
The system defines a hierarchy of log levels to control the verbosity of the output:
- DEBUG: Detailed information for development and troubleshooting.
- INFO: Standard operational messages (Default minimum level).
- WARN: Non-critical issues or slow operations (e.g., operations > 1000ms).
- ERROR: Recoverable errors with error names, messages, and stacks.
- FATAL: Critical failures that may require immediate attention.
Sources: packages/api/src/utils/logger.ts:8-15, packages/api/src/utils/logger.ts:133-138
The following diagram illustrates the flow of log generation from an application event to the final structured output:
The diagram shows how the log method processes messages by verifying levels, merging context, and serializing the entry for Cloudflare's runtime.
Sources: packages/api/src/utils/logger.ts:84-110
Standardized Error Handling
SecretForge AI uses a standardized error format for all API responses to ensure predictability for client integrations. Every error response includes an error object containing a message, a specific error code, and a timestamp.
Error Response Structure
When an API request fails (e.g., 404 for a missing secret or 401 for unauthorized access), the response body follows this schema:
{
"error": {
"message": "Detailed error description",
"code": "ERROR_CODE_STRING",
"timestamp": "2025-11-22T12:00:00.000Z"
}
}
Sources: packages/api/src/tests/api.integration.test.ts:251-262
Automated Error Tracking
The ErrorTracker tracks occurrences of specific error types. If a specific error type occurs more than 10 times, the system escalates the log level to FATAL to signal a potential systemic issue.
The sequence diagram details the escalation logic within the ErrorTracker class.
Sources: packages/api/src/utils/logger.ts:192-205
Performance Monitoring and Health Checks
To maintain high availability and performance across the edge, the system tracks the duration of critical operations.
Timing Utilities
Developers can monitor performance using three primary methods:
- PerformanceMonitor.record: Manually record the duration of an operation.
- timed Decorator: An async function decorator that automatically records timing metrics.
- time Helper: A wrapper function for timing specific code blocks.
Sources: packages/api/src/utils/logger.ts:130-184
System Health Monitoring
The HealthChecker aggregates multiple registered checks (e.g., database connectivity or KV store availability) to return a unified system status.
| Status | Condition |
|---|---|
| Healthy | All registered checks passed. |
| Degraded | One or more non-critical checks failed (Future implementation). |
| Unhealthy | One or more registered checks failed or threw an error. |
Sources: packages/api/src/utils/logger.ts:218-248, packages/api/src/tests/api.integration.test.ts:38-48
Security and Compliance in Logging
The logging system is a critical component of the project's security posture, as outlined in the Security Summary.
Security Guardrails
- Secret Masking: Secret values are strictly masked or omitted from logs. decypted values are never cached or stored in logs.
- Audit Trail: Logs capture IP addresses, user agents, and timestamps to provide an audit trail for SOC 2 and GDPR compliance.
- Sanitization: Input sanitization prevents injection attacks that could be triggered by malformed secret values during export or logging.
Sources: SECURITY_SUMMARY.md:68-80, SYSTEM_EVALUATION.md:154-165
Conclusion
The logging and error handling infrastructure in SecretForge AI provides a robust foundation for maintaining a secure and performant secret management platform. By combining structured logging with automated error tracking and performance monitoring, the system enables rapid debugging while strictly adhering to zero-trust security principles. This integrated approach ensures that the platform remains compliant and reliable as it scales across the edge.