FiloDB Architecture, Installation, and Prometheus Query Support

Why FiloDB Targets Real-Time Operational Data

FiloDB addresses workloads that need recent operational data available for interactive queries without treating the database as a conventional transactional store. Its stated uses include real-time metrics storage, dashboards, distributed tracing such as Zip-style trace data, ad hoc application metric debugging, and real-time event storage. The intended users are therefore teams operating clusters of metric-producing services and needing PromQL-based access to their data.

The project describes itself as distributed, in-memory, multi-schema, and massively scalable. Its normal real-time configuration runs as separate processes that ingest directly from Apache Kafka. Those processes form a cluster through peer-to-peer Akka Cluster technology. Time series are sharded across multiple processes, while distributed querying is part of the database architecture rather than a separate client-side aggregation feature.

This scope has explicit boundaries. The README lists transactional, update-oriented workflows and OLAP or analytics as anti-use cases. A system that depends on multi-row transactions, general-purpose updates, or long analytical scans would therefore be choosing outside FiloDB's documented purpose. FiloDB is designed around append-oriented time series and event data that can be queried soon after ingestion.

FiloDB's Kafka and Akka Cluster Data Flow

The documented ingestion path begins with Apache Kafka. Kafka supplies the event stream consumed by FiloDB processes, while an Akka Cluster forms the peer-to-peer cluster membership used by those processes. This design separates production of the stream from ingestion and query-serving processes, but it also means Kafka is part of the normal operating model rather than an optional integration mentioned in passing.

FiloDB stores data in memory and uses columnar compression, tag-based indexing, and off-heap memory management. Data is described as immediately queryable after ingestion. The README also says that the architecture is intended for dual-datacenter operation, strong recoverability, and operation without a single point of failure. Those are design claims rather than guarantees for every deployment, and the README does not describe the complete replication, recovery, or failover procedure.

The data model supports both Prometheus operational metrics and a traditional multi-column schema. Prometheus queries use PromQL, while the repository also includes Spark support. That combination places FiloDB between a streaming database and a query layer for operational data. It is not presented as a drop-in replacement for every Prometheus deployment, and the README does not enumerate all remote-write, remote-read, or Prometheus server compatibility details.

Installing FiloDB and Preparing Its Kafka Input

FiloDB requires more than a JVM process. The README lists Java 11, SBT, Apache Cassandra 2.x or 3.x, Apache Kafka 0.10.x or later, Rust, and a working GCC or Clang compiler. Apache Spark 2.0 is optional. The repository also includes `filo-cli`, `filodb-dev-start.sh`, and `filodb-dev-stop.sh`, but the README does not provide enough detail to document their complete first-query sequence without guessing.

The documented clone and build commands are:

git clone https://github.com/filodb/FiloDB.git
cd FiloDB

After entering the repository, the README recommends using the last stable released version. Its build instruction is to run `filo-cli` and then run `sbt spark/assembly`. Those are repository-specific commands, although the README does not show the output expected from either step.

The local setup instructions also give this Cassandra test-cluster command:

ccm create v39_single -v 3.9 -n 1 -s

This creates the single-node Cassandra configuration described for testing. Kafka can be installed and started on a Mac with the following commands:

brew install kafka
brew services start zookeeper
brew services start kafka

After Kafka is available, create the four-partition ingestion topic:

kafka-topics --create --bootstrap-server localhost:9092 --replication-factor 1 --partitions 4 --topic timeseries-de

The topic name and partition count are explicit in the README. This prepares the input stream for FiloDB, but the README does not show a complete producer command or a first PromQL query that can be copied without inventing configuration.

Kafka and ZooKeeper Setup Conflicts to Resolve

The installation guide includes a concrete local conflict involving ZooKeeper. Newer ZooKeeper versions can start an admin HTTP server on port `8080`, which the README says conflicts with FiloDB servers. The documented correction is to add this setting to `zoo.cfg`:

# Disable admin server on 8080
admin.enableServer=false

The listed Homebrew path is `/opt/homebrew/etc/zookeeper/zoo.cfg`, although the configuration change should be applied to the actual `zoo.cfg` used by the installation. This is an important setup detail because a successful Kafka and ZooKeeper startup does not guarantee that the FiloDB processes can bind their intended ports.

The guide also documents an Apple Silicon packaging error in which `kafka-run-class.sh` looks for Java beneath `/opt/homebrew/@@HOMEBREW_JAVA@@/bin/java`. Its stated workaround is to reinstall Kafka from a Homebrew bottle:

brew bottle --skip-relocation kafka
brew reinstall `ls kafka*bottle*`

These steps address the package's Java path. They do not alter FiloDB itself, but they demonstrate why infrastructure compatibility has to be checked before judging the database setup.

Schema, Tags, Sharding, and Query Cost

FiloDB supports a Prometheus schema for operational metrics as well as a traditional multi-column schema. The Prometheus-oriented design includes tag-based indexing and PromQL support. The README says that data modelling and performance considerations are important, which makes schema choice an adoption issue rather than a detail that can be postponed until after ingestion begins.

Sharding is used to distribute many entities across multiple processes. A correct deployment must therefore account for how series or partitions are assigned and how queries reach the relevant shards. The README does not provide a shard-placement configuration, a recommended series-per-shard threshold, or a worked example of distributed query planning. It would be unsafe to invent defaults for those decisions.

The documented feature set also includes first-class histogram support and FiloDB PromQL extensions. Those features may matter when selecting FiloDB against another metrics backend, but the README does not give their exact syntax. Query semantics, histogram compatibility, and extension behavior should therefore be checked in the query documentation for the selected release.

Grafana, HTTP API, CLI, and Spark Boundaries

The README identifies a Grafana setup, a FiloDB HTTP API, a command-line interface, CLI configuration, and CLI options. It also identifies Spark support as part of the broader project. These interfaces broaden the ways data may be queried or consumed, but the README does not give their endpoints, flags, authentication settings, or complete examples. Those details cannot be filled in responsibly from the documented overview.

The presence of Spark support should not be confused with a recommendation for OLAP. The README explicitly lists OLAP and analytics as anti-use cases while describing Spark support as an additional capability. Spark-related support therefore exists for certain processing paths while FiloDB's primary design remains real-time ingestion and querying.

Likewise, the HTTP API and CLI are documented as query surfaces, but the README does not establish whether every deployment exposes the same interfaces or whether they provide identical query features. An engineer evaluating the project should inspect the API and CLI configuration for the selected release rather than infer parity from their shared presence in the README.

Maintenance Signals, Releases, and Apache-2.0 Obligations

The repository is not archived, and its last push was on 2026-10-13. The release list names `v0.9.17.2` from 2022-11-18, `v0.9.15.3` from 2021-11-04, and `0.9.12.2` from 2021-04-28. The repository has recent commit activity, but the listed releases are not recent. That distinction matters when estimating upgrade work because a new commit does not by itself establish a recent packaged release.

FiloDB is licensed under Apache-2.0. A team distributing a modified build or incorporating it into an internal deployment should review the license file and preserve the permissions and notice conditions that apply to the distributed software. This is a license-compliance check, not a conclusion about suitability or legal responsibility.

Build and dependency maintenance also has a visible cost. The README asks for Java 11, SBT, Cassandra, Kafka, Rust, and a native C compiler, with Spark optional. Native components and several stateful infrastructure services make the operational surface larger than a single binary database. Upgrade planning must account for the dependency versions accepted by the selected FiloDB release, especially because the README names Cassandra 2.x or 3.x and Kafka 0.10.x or later rather than presenting an unconstrained modern dependency matrix.

Editorial conclusion

Engineers operating Prometheus-compatible metric clusters or other high-volume real-time streams should evaluate FiloDB, while transactional database and OLAP users should choose another system. Before adoption, verify the schema and partition design, confirm that the required Kafka, Cassandra, Java 11, SBT, Rust, and native build dependencies fit the deployment environment, and inspect the deployment and upgrade documentation for the intended version.

Frequently asked questions

Official sources

1. filodb/FiloDB on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases