Crate foundations

Foundations is a modular Rust library, designed to help scale programs for distributed, production-grade systems. It enables engineers to concentrate on the core business logic of their services, rather than the intricacies of production operation setups.

If you need any of those:

• logging
• distributed tracing
• metrics
• memory profiling and jemalloc allocator
• security features, such as seccomp-based syscall sandboxing
• service configuration with documentation
• CLI helper that takes care of the configuration loading

then Foundations is a tool of choice for you.

Check out examples for an example of how all these components can be used together.

Features

Foundations can take of all aspects of service bootstrapping, but also can be used as a component library in a modular fashion by enabling or disabling Cargo features:

• default: All features are enabled by default.
• platform-common-default: The same as default, but excludes platform-specific features, such as security.
• server-client-common-default: A subset of features that can be used both on server and client sides. Useful for libraries that can be used either way.
• settings: Enables serializable documented settings functionality.
• telemetry: Enables all the telemetry-related features (metrics, logging, tracing, telemetry-server).
• telemetry-server: Enables the telemetry server.
• client-telemetry: Enables a subset of telemetry features suitable for usage in clients (e.g. on mobile devices).
• metrics: Enables metrics functionality.
• logging: Enables logging functionality.
• tracing: Enables distributed tracing functionality.
• testing: Enables testing-related functionality.
• security: Enables security features. Available only on Linux (x86_64, aarch64).
• jemalloc: Enables jemalloc memory allocator which is known to perform much better than system allocators for long living service.
• memory-profiling: Enables memory profiling functionality and telemetry. Implicity enables jemalloc feature.
• cli: Enables command line interface (CLI) functionality. Implicitly enabled settings feature.

Unstable Features

Foundations has unstable features which are gated behind --cfg foundations_unstable:

• tokio-runtime-metrics: Enables runtime metrics for Tokio runtimes. Implicitly enables the metrics feature. Also requires tokio_unstable.

To enable these, you must add --cfg foundations_unstable to your RUSTFLAGS environment variable.

Modules

• clicli
  Command line interface-related functionality.
• securitysecurity and Linux and (x86-64 or AArch64)
  Security-related features.
• settingssettings
  Serializable service settings with documentation.
• telemetrylogging or metrics or telemetry or tracing
  Foundations provides telemetry functionality for:

Macros

• service_info
  Creates ServiceInfo from the information in Cargo.toml manifest of the service.

Structs

• ServiceInfo
  Basic service information.

Statics

• JEMALLOC_MEMORY_ALLOCATORjemalloc
  Global memory allocator backed by jemalloc.

Type Aliases

• BootstrapError
  Error that can be returned on a service initialisation.
• BootstrapResult
  Result that has BootstrapError as an error variant.
• Error
  A generic operational (post-initialization) error without backtraces.
• Result
  Operational (post-initialization) result that has Error as an error variant.