Enhanced logging for Grafana observability (Issue #11)

[irjudson]

Summary

Implements comprehensive logging infrastructure for Grafana monitoring (Issue #11).

Changes

• Added 77 logger calls across 6 core files to enable Grafana observability
• Evaluated singleton pattern in globals.js (confirmed appropriate for current architecture)
• Maintained test coverage (all 91 tests passing with logger mocks)
• Logging coverage increased from 74% (202 calls) to 95% (279 calls)

Files Modified

Source Files (77 new logger calls)

• src/schema-manager.js - 21 calls (table creation, schema migration, BigQuery introspection)
• src/config-loader.js - 16 calls (config loading, validation, normalization)
• src/type-converter.js - 20 calls (value conversion, edge cases, batch processing)
• src/query-builder.js - 10 calls (SQL query construction, column formatting)
• src/type-mapper.js - 7 calls (type mapping decisions, unsupported types)
• src/globals.js - 3 calls (key-value state management)

Test Files (logger mocks added)

• test/config-loader.test.js
• test/schema-manager.test.js
• test/type-converter.test.js
• test/type-mapper.test.js
• test/query-builder.test.js

Research Documentation

• GLOBALS_LOGGING_RESEARCH.md - Comprehensive analysis of globals system and singleton pattern
• LOGGING_ANALYSIS_BY_FILE.md - File-by-file logging coverage breakdown

Logging Format

All logging follows HarperDB conventions for Grafana integration:

logger.info('[ClassName.methodName] Operation description with context');
logger.debug('[ClassName.methodName] Detailed tracing with ${variables}');
logger.warn('[ClassName.methodName] Edge case or fallback behavior');
logger.error('[ClassName.methodName] Failure with ${error.message}');

Singleton Pattern Evaluation

Decision: Keep singleton pattern in globals.js

Rationale:

• HarperDB uses distributed multi-node architecture (not multi-threaded)
• Each node gets its own process with isolated plugin instance
• Singleton provides shared state across modules within single instance
• Avoids circular dependencies between components
• No threading concerns in current architecture

Test Coverage

• All 91 tests passing
• Added logger mocks to 5 test files (Node.js doesn't have HarperDB globals)
• Verified no regression in functionality

Grafana Integration

The structured logging format enables:

• Query patterns like {module="SchemaManager", operation="ensureTable"}
• Dashboard panels tracking table operations, type conversions, config loading
• Alert rules for error rates, unsupported types, migration events

Future Work (Optional)

• Phase 2: Migrate synthesizer console.log to dual logger/console (test utilities)
• Phase 3: Build Grafana dashboards and alert configurations