Why a single database for observability
Metrics, logs and traces describe the same incident from three angles. When they live in three tools, you jump between tabs copying timestamps, and the question "which slow requests came before these errors?" takes three queries in three languages.
GreptimeDB stores them all in tables, in a columnar engine designed for time series. Metrics received from Prometheus stay queryable in PromQL, and everything — metrics, logs and traces — can also be queried in SQL, with joins and aggregates. Grafana sees it as an ordinary Prometheus data source.
What GreptimeDB brings
- Three signals, one engine — metrics, logs and traces in tables of the same columnar store.
- SQL and PromQL — joins, windows and aggregates in SQL; your PromQL queries work as they are.
- Prometheus-compatible —
remote_writetarget, Prometheus query API, Grafana data source with no plugin. - Native OpenTelemetry — OTLP/HTTP ingestion of metrics, logs and traces.
- Other protocols — Loki push API, InfluxDB line protocol, SQL API over HTTP.
- Built-in dashboard — SQL and PromQL editor, table exploration, charts of the results.
GreptimeDB versus a Prometheus, Loki and Tempo stack
Scroll the table
| GreptimeDB | Prometheus + Loki + Tempo | |
|---|---|---|
| Services to run | A single container | Three services, three configurations |
| Query languages | SQL and PromQL | PromQL, LogQL and TraceQL |
| Cross logs and metrics | One SQL query | Several queries, by hand |
| Ingestion | remote_write, OTLP, Loki, InfluxDB, SQL | One protocol per service |
| Grafana | Prometheus data source | One data source per service |
| Retention | Per database or per table, in SQL | One setting per service |
Prerequisites
An Ubuntu 24.04 VPS with 2 GB of RAM is enough to start; plan 4 GB and more disk if you centralise many services, since logs and traces take far more space than metrics. You need Docker with the Compose plugin, and a domain name pointing to the VPS, with nginx and an HTTPS certificate: your servers will send their data to it and Grafana will query it.
Install GreptimeDB with Docker Compose
Prepare the directory and the password
Create the application directory and a
.envfile holding theadminuser's password.mkdir -p /opt/greptimedb && cd /opt/greptimedb echo "ADMIN_PASSWORD=$(openssl rand -hex 16)" > .env chmod 600 .envWrite the docker-compose.yml
The port is only published on the loopback interface: only nginx reaches it. The
--user-provideroption declares theadminuser and protects the whole HTTP API. TheGREPTIMEDB_STANDALONE__ENABLE_TELEMETRYvariable turns off the anonymous usage report sent to the vendor.services: greptimedb: image: greptime/greptimedb:v1.3.0 restart: unless-stopped ports: - "127.0.0.1:4000:4000" environment: GREPTIMEDB_STANDALONE__ENABLE_TELEMETRY: "false" command: - standalone - start - --http-addr=0.0.0.0:4000 - --data-home=/greptimedb_data - --user-provider=static_user_provider:cmd:admin=${ADMIN_PASSWORD} volumes: - greptimedb-data:/greptimedb_data volumes: greptimedb-data: {}Start and check
Startup takes a few seconds.
/healthanswers without authentication; the SQL API returns 401 without credentials.docker compose up -d curl -fsS http://127.0.0.1:4000/health curl -u admin:YOUR_PASSWORD http://127.0.0.1:4000/v1/sql -d 'sql=SHOW TABLES'Publish over HTTPS with nginx
In your domain's vhost (certificate obtained with certbot), proxy to the local port. Raise
client_max_body_size:remote_writeand OTLP batches quickly exceed the default limit.location / { proxy_pass http://127.0.0.1:4000; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; client_max_body_size 32m; }
Without --user-provider, the database is open to all
Without a user provider, GreptimeDB accepts any request: anyone who knows the address can read your logs and write, alter or drop tables in SQL. Keep authentication on, and never publish port 4000 directly on the public IP: always go through the HTTPS reverse proxy. GreptimeDB's gRPC, MySQL and PostgreSQL ports do not need to be published either.
Send Prometheus metrics
In each server's prometheus.yml, add a remote_write block pointing to GreptimeDB. The db parameter names the destination database; public exists from the first start.
remote_write:
- url: https://greptime.example.ma/v1/prometheus/write?db=public
basic_auth:
username: admin
password: YOUR_PASSWORDReload Prometheus: each metric becomes a table, visible with SHOW TABLES; in the dashboard.
Send logs and traces over OpenTelemetry
In the OpenTelemetry Collector (or directly in your application's SDK), declare an OTLP/HTTP exporter pointing to GreptimeDB. The Authorization header carries admin:password Base64-encoded, and traces also require the X-Greptime-Pipeline-Name: greptime_trace_v1 header. Declare two exporters, then: set on logs, that header gets them rejected.
exporters:
otlphttp/greptime:
endpoint: https://greptime.example.ma/v1/otlp
headers:
Authorization: "Basic BASE64_ADMIN_PASSWORD"
otlphttp/greptime-traces:
endpoint: https://greptime.example.ma/v1/otlp
headers:
Authorization: "Basic BASE64_ADMIN_PASSWORD"
X-Greptime-Pipeline-Name: greptime_trace_v1
service:
pipelines:
logs:
exporters: [otlphttp/greptime]
metrics:
exporters: [otlphttp/greptime]
traces:
exporters: [otlphttp/greptime-traces]Metrics arrive on /v1/otlp/v1/metrics, logs on /v1/otlp/v1/logs and traces on /v1/otlp/v1/traces: the collector adds these suffixes itself. If you already ship logs to Loki, Promtail and Grafana Alloy can target /v1/loki/api/v1/push.
Query GreptimeDB from Grafana
In Grafana, add a Prometheus-type data source with the URL https://your-domain/v1/prometheus, enable basic authentication and enter the admin user and its password. Your PromQL dashboards work unchanged.
For logs and traces, write your queries in SQL in the built-in dashboard (https://your-domain/dashboard/), where credentials go in the connection settings. A query such as SELECT * FROM opentelemetry_logs ORDER BY timestamp DESC LIMIT 50; shows the latest logs received.
Retention, disk and backups
Out of the box, GreptimeDB deletes nothing. Retention is set in SQL, for a whole database or per table (ttl option at creation). The COPY DATABASE command exports a database in Parquet format into the data volume, under /greptimedb_data/copy/:
ALTER DATABASE public SET 'ttl'='90d';
COPY DATABASE public TO 'backup/' WITH (FORMAT='parquet');Then copy that folder off the VPS, or back up the whole greptimedb-data Docker volume with the container stopped. Watch disk space: it is almost always the size of the logs that decides.
Update GreptimeDB
Read the release notes first: a major upgrade may require a migration step. Change the image tag in docker-compose.yml, then:
cd /opt/greptimedb
docker compose pull && docker compose up -d
docker compose logs --tail 20The volume's data is kept. Run a COPY DATABASE just before a major upgrade: it is your way back.
One-click install from the ServOrbit Marketplace
The ServOrbit Marketplace installs GreptimeDB on your VPS without a command line: it deploys the official container, generates the admin user's password, enables authentication on the whole HTTP API, turns off the anonymous usage report and publishes the dashboard over HTTPS on a subdomain of your domain or on the VPS's free subdomain (greptimedb.{dns_slug}.servorbit-dns.com). The password appears in your client area; all that is left is to connect Prometheus, OpenTelemetry and Grafana.
