How cloudflare/foundations works
Project Type and Purpose
• This is an open-source, modular Rust library (“Foundations”) for production-grade systems, providing logging, distributed tracing, metrics, memory profiling, seccomp-based sandboxing, configuration management, and a CLI helper.
• It consists of two main crates:
• foundations-macros: procedural macros to instrument user code (metrics, telemetry, settings helpers)
• foundations: core library implementing telemetry pipelines, security, configuration, CLI, etc.
High-Level Components
a. Application Layer (example or user service)
b. Macro Layer (foundations-macros)
c. Core Library Layer (foundations)
– Telemetry sub-system (logging, metrics, tracing, memory profiling)
– Security sub-system (seccomp syscall sandboxing)
– Configuration sub-system (YAML/CLI settings loader with docs)
– CLI helper
– Telemetry server (OTLP gRPC endpoint)
d. External Systems & Runtimes
– Logging sinks (files, stdout, dedicated backends)
– Metrics backends (Prometheus, StatsD, etc.)
– Tracing collectors (Jaeger, OTLP-gRPC)
– jemalloc allocator
– OS seccomp
Relationships and Data Flows
• Application code invokes macros (from foundations-macros) to declare metrics, tracing spans, config options.
• Macro expansion generates calls into the foundations core API.
• At runtime, the core API routes:
– Logs → log filters → log sinks (console, files, remote)
– Metrics → counters/gauges → push or pull exporters
– Traces → span builder → OTLP/Jaeger exporters
– Memory profiler → jemalloc hooks → profiling data
– Security: on startup, seccomp profiles loaded → kernel enforces syscall filters
– Configuration: CLI parser loads YAML → populates typed settings structs
• Telemetry server module can host an OTLP-gRPC endpoint to receive spans/metrics from remote services.
Architectural Patterns & Principles
– Layered design: macros → API surface → implementation modules → external integrations
– Separation of concerns: each sub-system (logging, metrics, tracing, security, config) lives in its own module hierarchy
– Extensibility: procedural macros generate hooks without user boilerplate; exporter backends pluggable via traits
– Runtime safety: seccomp sandboxing enforces least privilege
Detailed Capturing
• “(1) Macro invocations generate instrumentation calls.”
• Settings loader flow: CLI args + YAML → Settings struct → passed to other sub-systems.
• “Telemetry Server” as an optional HTTP/gRPC endpoint sidecar.