MindooDB includes a comprehensive logging system designed for security, debugging, and production monitoring. The logger provides structured logging with automatic sanitization of sensitive data, hierarchical context, and configurable log levels.
The logging system consists of:
- Log Levels: Five levels (ERROR, WARN, INFO, DEBUG, TRACE) to control verbosity
- Automatic Sanitization: Redacts sensitive data (keys, tokens, passwords) from log output
- Context Hierarchy: Child loggers provide contextual information (e.g.,
Tenant:abc123.BaseMindooDB) - Stack Trace Preservation: Error stack traces are preserved while sanitizing sensitive content
The logging system supports five log levels, ordered by severity:
| Level | Value | Description | Use Case |
|---|---|---|---|
| ERROR | 0 | Critical errors that require attention | Production monitoring |
| WARN | 1 | Warning messages for potential issues | Production monitoring |
| INFO | 2 | General informational messages | Default level, production use |
| DEBUG | 3 | Detailed debugging information | Development and troubleshooting |
| TRACE | 4 | Very verbose tracing information | Deep debugging |
When a log level is set, all messages at that level and below are displayed. For example, setting INFO will show ERROR, WARN, and INFO messages, but not DEBUG or TRACE.
In Node.js, configure the log level using the MINDOO_LOG_LEVEL environment variable:
# Set log level via environment variable
export MINDOO_LOG_LEVEL=DEBUG
# Or inline with your command
MINDOO_LOG_LEVEL=DEBUG node your-app.js
# In package.json scripts
{
"scripts": {
"dev": "MINDOO_LOG_LEVEL=DEBUG node src/index.js",
"start": "MINDOO_LOG_LEVEL=INFO node src/index.js"
}
}Supported values: ERROR, WARN, INFO, DEBUG, TRACE (case-insensitive)
Default: INFO (if not set)
In browser environments, configure the log level using one of these methods:
Set the log level in browser localStorage before initializing MindooDB:
// Set log level before creating tenant factory
localStorage.setItem('MINDOO_LOG_LEVEL', 'DEBUG');
// Now initialize MindooDB
const factory = new BaseMindooTenantFactory(storeFactory, cryptoAdapter);Note: The logging system does not read URL parameters for security reasons. Setting log levels via URL parameters would be a security risk, as attackers could enable verbose logging by tricking users into visiting malicious URLs. Always use localStorage or programmatic configuration instead.
For more control, you can create a custom logger and pass it to the factory:
import { MindooLogger, LogLevel } from '@mindoodb/core';
// Create a logger with specific level
const logger = new MindooLogger(LogLevel.DEBUG, 'MyApp', true);
// Pass it to the factory
const factory = new BaseMindooTenantFactory(
storeFactory,
cryptoAdapter,
logger
);The logger automatically detects the environment:
- Node.js: Reads from
process.env.MINDOO_LOG_LEVEL - Browser: Reads from
localStorage.getItem('MINDOO_LOG_LEVEL')or falls back to default
The logger automatically redacts sensitive information from log output to prevent accidental exposure:
-
PEM Keys: Any string containing
BEGINandKEY(e.g.,-----BEGIN PRIVATE KEY-----)- Redacted as:
[REDACTED: Key]
- Redacted as:
-
JWT Tokens: Long strings (>100 chars) matching JWT pattern (
xxx.yyy.zzz)- Redacted as:
[REDACTED: Token]
- Redacted as:
-
Base64 Encrypted Data: Long base64 strings (>200 chars)
- Redacted as:
[REDACTED: Encrypted Data]
- Redacted as:
-
Passwords: Short strings (<100 chars) containing "password" or "pwd"
- Redacted as:
[REDACTED: Password]
- Redacted as:
Error stack traces are preserved for debugging purposes. The logger sanitizes sensitive content within stack traces while maintaining:
- File paths and line numbers
- Function names
- Call stack structure
Example:
try {
// Some operation that might log sensitive data
} catch (error) {
logger.error('Operation failed', error);
// Stack trace is preserved, but sensitive strings in the error message are sanitized
}The logger supports hierarchical context for better traceability:
MindooTenantFactory
└── Tenant:abc123
├── Directory
└── BaseMindooDB:my-db
└── RSAEncryption
Each component creates child loggers with additional context:
// In BaseMindooTenantFactory
const tenantLogger = this.logger.createChild(`Tenant:${tenantId}`);
// In BaseMindooTenant
const dbLogger = this.logger.createChild(`BaseMindooDB:${dbId}`);Log messages include the full context path:
[INFO][MindooTenantFactory.Tenant:abc123.BaseMindooDB:my-db] Database opened successfully
The logger is automatically integrated into MindooDB components. You typically don't need to use it directly:
import { BaseMindooTenantFactory } from '@mindoodb/core';
// Logger is created automatically with default level (INFO)
const factory = new BaseMindooTenantFactory(storeFactory, cryptoAdapter);
// All internal logging uses the logger
const tenant = await factory.openTenant(tenantId, adminSigningPublicKey, adminEncryptionPublicKey, currentUser, currentUserPassword, keyBag);For advanced use cases, you can provide a custom logger:
import { MindooLogger, LogLevel } from '@mindoodb/core';
// Create logger with DEBUG level and custom context
const logger = new MindooLogger(
LogLevel.DEBUG,
'MyApplication',
true // Enable sanitization
);
const factory = new BaseMindooTenantFactory(
storeFactory,
cryptoAdapter,
logger
);const logger = new MindooLogger(
LogLevel.DEBUG,
'DevLogger',
false // Disable sanitization - USE WITH CAUTION
);Log messages follow this format:
[LEVEL][Context] Message [additional args...]
Example outputs:
[ERROR][MindooTenantFactory] Failed to create tenant: [REDACTED: Key]
[WARN][Tenant:abc123] Public key not trusted: [REDACTED: Key]
[INFO][Tenant:abc123.BaseMindooDB:my-db] Database opened successfully
[DEBUG][Tenant:abc123] Signing payload
[TRACE][RSAEncryption] Encrypting with RSA key
- Production: Use
INFOorWARNlevel to reduce noise - Development: Use
DEBUGlevel for detailed troubleshooting - Troubleshooting: Temporarily set
TRACElevel to diagnose issues - Never disable sanitization in production: Always keep sanitization enabled
- Use context: Let the hierarchical context help you trace log messages to their source
- Check log level: Ensure your level is set low enough (e.g., DEBUG shows DEBUG, INFO, WARN, ERROR)
- Browser localStorage: Verify
localStorage.getItem('MINDOO_LOG_LEVEL')returns the expected value - Node.js environment: Verify
process.env.MINDOO_LOG_LEVELis set correctly
- Increase log level: Set to
WARNorERRORto reduce verbosity - Production defaults: Use
INFOas the default for production environments
- Verify sanitization is enabled: Check that logger was created with
sanitize: true(default) - Report issues: If sensitive data appears in logs, report it as a security issue
- Custom sanitization: Extend
MindooLoggerto add custom sanitization rules
The logging system is implemented in:
src/core/logging/LogLevel.ts- Log level enum and parsingsrc/core/logging/Logger.ts- Logger interfacesrc/core/logging/MindooLogger.ts- Logger implementationsrc/core/logging/index.ts- Public exports
All MindooDB components use the logger through dependency injection, ensuring consistent logging behavior across the codebase.