BanyanDB

First Occurrence Data Collection (FODC) is an observability and diagnostics subsystem for BanyanDB. It is designed to ensure stable DB node operation and provide structured data for capacity planning, performance analysis, and troubleshooting.

FODC provides four main categories of data:

1. Metric collection and short-term caching (small time window).
2. Node topology and status, including runtime parameters and role states.
3. Node configuration collection.
4. On-demand performance profiling and memory snapshots.

BanyanDB provides observability through three primary channels to monitor performance, behavior, and system health:

• Logging: Configurable log levels, per-module granularity, and slow-query logging.
• Metrics: A comprehensive catalog including statistics, resource usage, storage, trace plugins, inverted index, and internal queue metrics, queryable via PromQL.
• Profiling: Access to pprof endpoints for deep performance analysis.
• Query Tracing: Per-query execution traces to identify bottlenecks.

For monitoring, BanyanDB follows two canonical methodologies:

1. RED (Rate, Errors, Duration) for request paths (write and query paths).
2. USE (Utilization, Saturation, Errors) for system resources.

BydbQL is a unified, SQL-like query language designed to interact with all BanyanDB data models. It abstracts underlying protobuf-based APIs, providing a consistent interface for querying different types of data.

BydbQL supports the following primary data models:

• Streams: Raw, time-series elements (e.g., logs, traces).
• Measures: Aggregated numerical time-series data (metrics).
• Properties: Metadata and key-value information.
• Traces: Distributed tracing data containing spans.
• Top-N: A specialized syntax for optimized Top-N queries against measures.

BanyanDB is researching a transition from using external libraries (Bluge and ICE) to a custom, lightweight, native inverted index implementation. This native engine is intended to power several core BanyanDB components:

• Segment-level series index: Shared by time-series engines.
• Stream element index.
• Property storage and search.
• index-mode Measure storage and search.
• Maintenance workflows: Migration, repair, dump, snapshot, and external-segment workflows.

The goal is to create a minimal, maintainable engine that preserves existing BanyanDB behaviors and ensures on-disk interoperability with existing data formats.

The BanyanDB protocol is defined using Protocol Buffers (protobuf) and is organized into several functional domains. This documentation provides a reference for the various service definitions, request/response structures, and data models used to interact with BanyanDB.

Key functional areas include:

• Trace: Handling trace and span data.
• Measure: Managing metric/measure data points and aggregations.
• Stream: Handling stream-based data elements.
• Property: Managing system properties and cluster state via gossip and repair services.
• Schema: Managing entity, measure, stream, and trace schemas.
• Database: Managing cluster state, nodes, and shards.
• ByDBQL: Executing queries via the BydbQL language.
• FODC: Providing diagnostics, lifecycle info, and pressure profiles for cluster health.

First Occurrence Data Collection (FODC) is a foundational component for BanyanDB deployments, providing:

• Unified, structured observability: Collects metrics, topology, and configuration for BanyanDB clusters.
• Prometheus integration: Provides Prometheus-friendly interfaces for ecosystem integration.
• On-demand deep diagnostics: Orchestrates profiling and memory snapshots centrally while executing them locally.
• Lightweight architecture: Uses a Proxy + Agent model designed to respect resource constraints.

A Block is the minimal unit of storage in the TSDB. It contains several rows of data and is spread across multiple columnar files. Blocks are globally ordered by (seriesID, minTimestamp).

Block Constraints and Behavior:

• Grouping: In Measure, all rows in a block share the same seriesID. In Trace, the grouping key is the trace id.
• Sizing:
  • Measure: Bounded by 2 MiB uncompressed data OR 8192 rows.
  • Stream: Bounded by data volume only.
  • Trace: Bounded by 2 MiB opaque span volume.
• Deduplication: In Measure, timestamps.bin stores a version next to each timestamp. If multiple rows share a timestamp, only the one with the highest version is returned.
• Indexing: meta.bin contains primaryBlockMetadata records (40 bytes) that provide offsets and sizes for the block's data in primary.bin and the columnar files.