* feat(mito2): add lossless multi-region compaction executor Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * refactor(mito2): use bounded workers for multi-region compaction Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * fix(mito2): materialize compaction routing fragments on demand Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * fix(index): clean up Tantivy resources on cancellation Keep temporary directories alive through initialization and in-flight writer finalization. Release writers and remove directories on the shared blocking runtime, and retain the finishing task so abort can join it safely. Cover creator lifecycle cleanup and multi-region cancellation and sibling failure after Tantivy initialization. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * refactor(mito2): stream single-window multi-region compaction Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * test(mito2): read published multi-region outputs with real metadata Multi-region output metadata was only inspected field by field; every successful read cleared the sequence bound and forced the preserve marker, so partition filtering and sequence override were never exercised with the metadata a caller publishes. Read each output again with the returned FileMeta and the target metadata, and require the same row count and the same reader-visible sequences. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * test(mito2): cover multi-region routing mask rejection The exclusive-routing guards were unreachable: every fixture used a partition rule whose masks happened to be disjoint and correctly sized. An unchecked caller-supplied rule can still violate both invariants, and a violation would route one physical row to several target regions. Cover both guards: overlapping predicates from a real rule with check_exprs=false, and an over-short mask from a minimal rule implementation. Both must fail before any output is protected. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * test(mito2): cover JSON2 rewrite through multi-region compaction The multi-region executor wires the shared JSON2 rewrite plan by column id and target layout, but no fixture carried a JSON2 column, so neither the per-target mapping nor the materialized values were exercised. Write a source SST with a narrower JSON2 layout (one key stays in the remainder), compact it into a wider target layout, and read the output back: require the target physical layout and the original key values. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * test(mito2): cover every validate_plan rejection Plan validation is the boundary that keeps malformed inputs away from the routing and writer stages, but only the happy path was exercised. Mutate a valid plan for each rejection (budgets, control state, empty targets, window alignment/overflow, source ownership, duplicates, missing inputs, mismatched schemas) and require the specific reason under a timeout, with no protected outputs. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * test(mito2): assert multi-region output bytes and retained groups output_bytes had no positive assertion, and the peak check was an upper bound that also holds when the peak is never recorded. Require the reported bytes to equal the sum of the produced files and the peak equal-key group storage to be non-zero. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * test(index): cover retained Tantivy finalization on abort and drop Cancellation was only exercised after finish_writer returned, so the retained finalization handle and the directory lease it holds were never tested. Simulate a commit that is still running, then require abort to join it before removing the directory and creator drop to clean up after the lease is released. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * refactor(mito2): share sequence provenance helpers on FileMeta The multi-region writer duplicated the trust predicate and maximum-bound fold that read paths and DefaultSstMerger already rely on, so the two could disagree about whether a file's row sequences are trustworthy. Move both rules onto FileMeta, delegate from FileHandle, and reuse them from the multi-region writer and the compactor. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * docs(mito2): document the guarded SST write path write_sst_with_guard is the enterprise seam whose behaviour is not visible from its signature, and the comment above the non-cache arm still claimed the cache was unconditionally disabled. Describe the bypass, the single upload stream and the pre-create guard, and correct the stale comment. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * docs(mito2): document multi-region plan budget fields The public plan left max_output_file_size and window_seconds without units or semantics, and memory_limit without the multipart-minimum floor implied by admission. State all three so callers cannot budget against the wrong unit. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * docs(mito2): explain the multi-region row-group cap Capping output row groups at 1024 rows diverged from ordinary compaction without saying why. Record that the cap bounds the encoder working set that each resident target admits, and keep the behaviour unchanged. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * style(mito2): separate new error variants consistently Every other variant in the enum is separated by a blank line; the new enterprise variants were glued to their neighbours. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * docs(mito2): quote the new module identifier in the module map Every other row of the module map starts with a backticked identifier; the multi-region row did not. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * test(mito2): prefix multi-region tests with test_ Every other test under compaction/ is named test_*, so name-filtered runs and IDE grouping silently skipped this module. Rename only the test functions; assertions are unchanged. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * style(mito2): wrap the multi-region scan stream bodies rustfmt does not reflow async_stream macro bodies, so the shared scan kept statements far past the column limit. Split them into one statement per line; behaviour is unchanged. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * test(mito2): make the table-stage folding cases independent Both parametrized cases used identical options and differed only by merge_mode, which the table stage never reads, so the second case re-ran the first. Keep the ignored-merge-mode case and spend the second on preserve_row_sequence, asserting the per-file marker as well as the row count. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * test(mito2): fix partition mask test name Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * style(mito2): wrap multi-region worker macro bodies Wrap receive and accounting expressions and expand the scan completion arm without changing worker behavior. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * docs(mito2): document multi-region output levels Document that returned files default to L1 and callers must adjust metadata before publication when another level is intended. Distinguish this convention from changing existing persisted levels. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * fix(mito2): identify invalid multi-region plan fields Report each invalid source or execution limit separately while preserving validation order and thresholds. Update rejection cases and cover negative window widths. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> * test(mito2): consolidate multi-region compaction regressions Share SST fixtures and complete-row oracles while preserving non-append, JSON2, sequence, and cancellation coverage. Drive Tantivy finalization tests through the real finish path. Signed-off-by: Lei, HUANG <ratuthomm@gmail.com> --------- Signed-off-by: Lei, HUANG <ratuthomm@gmail.com>
Metrics, logs, and traces.
One engine, on your infrastructure.
A columnar database for metrics, logs, and traces on object storage. Apache-2.0 licensed core.
User Guide · API Docs · Roadmap 2026 · Slack
stable for production · canary includes pre-releases · nightly is a weekly snapshot of main
Introduction
GreptimeDB is an open-source observability database. Metrics, logs, and traces run on one columnar engine over object storage and share one table model: tags, timestamp, and fields. When signals carry common identifiers such as service, host, or trace ID, you can correlate them in SQL without moving data between databases.
Ingest through OpenTelemetry, Prometheus Remote Write, Loki Push, or Elasticsearch Bulk. Use SQL across observability data and PromQL for metrics. Migrate ingestion one signal at a time without rebuilding your collectors.
One Query Across Signals
OpenTelemetry ingestion writes spans to opentelemetry_traces and log records to
opentelemetry_logs. Both tables carry trace_id, so correlating them is a join:
-- The slowest failed spans in the last hour,
-- with the log lines emitted inside those same traces.
SELECT
t.service_name,
t.span_name,
t.duration_nano / 1000000 AS duration_ms,
l.timestamp AS log_time,
l.severity_text,
l.body
FROM opentelemetry_traces t
JOIN opentelemetry_logs l ON l.trace_id = t.trace_id
WHERE t.timestamp > now() - INTERVAL '1' HOUR
AND t.span_status_code = 'STATUS_CODE_ERROR'
ORDER BY t.duration_nano DESC
LIMIT 20;
Metrics join the same way, on any tag the tables share, such as service,
host, or pod.
Why You Might Use It
- You run Prometheus plus Loki or Elasticsearch and want one backend instead of three
- You have outgrown Prometheus on cardinality or retention and don't want the Thanos/Mimir operational surface
- You are hitting Loki's query performance limits as log volume grows
- You need long retention on object storage without a separate analytics stack
- You want to query telemetry with SQL, not only a domain query language
- You are storing GenAI or agent telemetry (OTel GenAI conventions) alongside infrastructure signals
Learn more in Why GreptimeDB.
What's Supported
| Ingest | OpenTelemetry (OTLP), Prometheus Remote Write, Loki Push, Elasticsearch Bulk, InfluxDB line protocol, gRPC |
| Query | SQL, PromQL, Jaeger-compatible trace queries, MySQL and PostgreSQL wire protocols |
| Storage | S3, GCS, Azure Blob and S3-compatible endpoints as primary storage, with memory and local-disk caches |
| Built in | Retention policies, downsampling, continuous aggregation, explicit table partitioning, and inverted / skipping / fulltext indexes |
Compute and storage are disaggregated: object storage holds the data, while memory and local-disk caches keep recent and frequently queried data close to compute.
Benchmarks
- Agent RCA Bench: LLM agents doing root cause analysis over GreptimeDB versus Prometheus + Loki + Tempo. 40% fewer wrong diagnoses, 48% fewer input tokens, 45% lower cost (write-up)
- GreptimeDB tops JSONBench's billion-record cold run test
- TSBS Benchmark
- More benchmark reports
Compatibility and Migration
Compatibility is per protocol, and query-side coverage is narrower than ingestion.
| Compatible | Not compatible | |
|---|---|---|
| Prometheus | Remote Write ingestion; PromQL queries | Gaps are listed in PromQL compatibility |
| Loki | Push ingestion; dual-write through Grafana Alloy makes the cutover gradual | LogQL and the rest of the Loki query API |
| Elasticsearch | _bulk ingestion in the open-source core; QueryDSL partially, in Enterprise |
Most other Elasticsearch APIs |
Limitations and Edition Boundary
Cluster deployment, object storage, the Flow engine, and every ingestion protocol listed above are in the Apache-2.0 build. Repartitioning, region migration, and index creation are manual operations there.
Read replicas, workload isolation, and automated repartitioning are GreptimeDB Enterprise features, along with enterprise security and governance. The Enterprise overview has the current list, and pricing has the edition comparison.
Architecture
GreptimeDB can run in two modes:
- Standalone — single binary for development and small deployments.
- Distributed — four components, each independently scalable:
- Frontend — protocol entry (OTel, Prometheus, MySQL/PostgreSQL, gRPC, ingestion APIs for Elasticsearch/InfluxDB/Loki) and the distributed query engine. Stateless, scales horizontally.
- Datanode — region engine with WAL, memtable, SST, cache, compaction, and indexes. Persists data to object storage. Elastic.
- Metasrv — metadata, routing, repartitioning, and security. Backed by a pluggable KV layer (etcd or RDS).
- Flownode (optional) — continuous flow computation (streaming and materialized views).
For deeper coverage, see the architecture doc or DeepWiki.
Try GreptimeDB
For AI agents — paste this prompt into your agent:
Read https://docs.greptime.com/SKILL.md and follow the instructions
to deploy, configure, ingest, and query GreptimeDB.
docker run -p 127.0.0.1:4000-4003:4000-4003 \
-v "$(pwd)/greptimedb_data:/greptimedb_data" \
--name greptime --rm \
greptime/greptimedb:latest standalone start \
--http-addr 0.0.0.0:4000 \
--grpc-bind-addr 0.0.0.0:4001 \
--mysql-addr 0.0.0.0:4002 \
--postgres-addr 0.0.0.0:4003
Dashboard: http://localhost:4000/dashboard
Read more in the full Install Guide.
Troubleshooting:
- Cannot connect to the database? Ensure that ports
4000,4001,4002, and4003are not blocked by a firewall or used by other services. - Failed to start? Check the container logs with
docker logs greptimefor further details.
Getting Started
Build From Source
Prerequisites:
- Rust toolchain — stable, pinned by
rust-toolchain.toml - Protobuf compiler (>= 3.15)
- C/C++ building essentials:
gcc/g++/autoconfand the glibc dev package (libc6-devon Ubuntu,glibc-develon Fedora) - Python toolchain (optional, only for some test scripts)
Build and run:
make # build greptime binary
cargo run -- standalone start # start in standalone mode
Common dev commands:
make fmt # format Rust code
make clippy # lint (fails on warnings)
make test # unit + integration tests (uses cargo-nextest)
make sqlness-test # SQL regression tests
See the Contribution Guidelines for the full developer workflow.
Tools & Extensions
- Kubernetes: GreptimeDB Operator
- Helm Charts: Greptime Helm Charts
- Dashboard: Web UI
- gRPC Ingester: Go, Java, C++, Erlang, Rust, .NET, TypeScript
- Grafana Data Source: GreptimeDB Grafana data source plugin
- Grafana Dashboard: Official Dashboard for monitoring
Project Status
GreptimeDB is generally available, with stable APIs and regular releases. It runs in production at scale — OceanBase Cloud operates 80+ GreptimeDB clusters managing 300 TB of logs, cutting log storage cost by 60%+ after migrating from Grafana Loki. See more in case studies.
Release lines and support windows are in the version reference. For where the project is going, read the v1.0 highlights, the 2026 roadmap, and what we mean by an observability database.
Community
We invite you to engage and contribute!
If GreptimeDB is useful to you, please star the repo.
License
GreptimeDB is an open-core project. Its core is licensed under the Apache License 2.0.
A small set of peripheral, enterprise-only features are gated behind the
enterprise Cargo feature (not built by default) and are governed by the
separate GreptimeDB Enterprise License. Source files under
that license carry an explicit Enterprise License header.
Commercial Support
Scaling observability on your infrastructure? GreptimeDB Enterprise adds the operational, security, and support layer for production deployments. Contact us for details.
Contributing
- Read our Contribution Guidelines.
- Explore Internal Concepts and DeepWiki.
- Pick up a good first issue and join the #contributors Slack channel.
Acknowledgement
Special thanks to all contributors! See AUTHOR.md.
- Uses Apache Arrow™ (memory model)
- Apache Parquet™ (file storage)
- Apache DataFusion™ (query engine)
- Apache OpenDAL™ (data access abstraction)
All trademarks, logos, and brand names referenced in this README and in the Overview diagram are the property of their respective owners. Their use is for identification purposes only and does not imply endorsement or affiliation.
