Logging API

Centralized, structured logging with error tracking, metrics collection, and distributed tracing.

What It Does

The Logging API provides a standardized logging solution that enforces purposeful, structured logging across all Foundation services. It integrates Google Cloud Logging, Rollbar error tracking, and OpenTelemetry distributed tracing to provide comprehensive observability. The API enforces a strict philosophy: all logging must be intentional and structured as either errors or metrics, enabling easy graphing, monitoring, and troubleshooting.

Key Capabilities

Capability	Description
Structured Logging	Builder pattern for consistent error and metric logging
Dual Environment Support	Seamless operation in local and Google Cloud environments
Error Tracking	Automatic Rollbar integration for centralized error monitoring
Distributed Tracing	OpenTelemetry support for request tracing across microservices
Metrics Collection	Structured metric logging for graphing and monitoring
Context-Aware Logging	Service, component, endpoint, and method context capture
Cloud Logging Integration	Automatic JSON formatting for Google Cloud Logging
Memory Optimization	Singleton pattern for cloud logging clients
Winston Integration	Dual logger architecture (console + cloud)
Rollbar Error Severity	Configurable severity levels (critical, error, warning, info, debug)

Configuration

Environment Variables

IS_CLOUD - Enable cloud logging mode
SERVICE_CONTEXT - Default service context
PROJECT_ID / GCP_PROJECT / GOOGLE_CLOUD_PROJECT / GCLOUD_PROJECT - GCP project
FIREBASE_CONFIG - Firebase configuration with project ID
_THIS_ENV / ENV - Environment name
COMMIT_SHA - Code version for Rollbar
TELEMETRY_EXPORT_URL - Custom telemetry exporter (e.g., SignOz)

Rollbar Configuration

API Key: Retrieved from secrets service
Environment: Extracted from project ID or env vars
Code Version: From COMMIT_SHA
Capture: Uncaught exceptions and unhandled rejections

OpenTelemetry Configuration

Sampler: AlwaysOnSampler
Exporter: Google Cloud Trace
Auto-instrumentation: Node.js (fs disabled)

Exports

Loggers

E11Logger - Primary NestJS-style logger
LogService - Winston-based service
childLog() - Child logger factory
serviceLogger() - Service logger factory

Builders

ErrorBuilder - Structured error logging
MetricBuilder - Structured metric logging

Services

E11ErrorHandlerService - Error handler orchestrator
RollbarService - Rollbar integration

Utilities

OpenTelemetryTracer - Distributed tracing
reportError() - Error reporting wrapper
createId() - SHA256 hash for error IDs

Constants

LogLevel enum
Service type constants
Severity mappings

Common Use Cases

Application logging: Structured logs for all application events
Error tracking: Centralized error monitoring with Rollbar
Performance metrics: Track API response times, throughput
Business metrics: Revenue, conversions, user activity
Distributed tracing: Track requests across microservices
Audit trails: Structured logs for compliance
Debugging: Context-rich logs for troubleshooting
Monitoring dashboards: Metrics for Grafana/Cloud Monitoring

Roadmap

Multi-Cloud Support

This API currently supports Google Cloud Platform. Future versions will add support for additional cloud providers and container-based deployment options, enabling greater flexibility in infrastructure choices.

What Customers Don’t Have to Build

Structured logging infrastructure
Error tracking integration (Rollbar)
Distributed tracing setup (OpenTelemetry)
Google Cloud Logging integration
Dual logger architecture (console + cloud)
Error builder patterns
Metric builder patterns
Context-aware logging
Memory-optimized cloud clients
Environment detection logic
Severity level mapping
Winston configuration
Error handler orchestration
Child logger factories
Singleton patterns for logging
Error ID generation
Cloud transport configuration
Telemetry exporter setup