Cortex — Horizontally Scalable Long-Term Storage for Prometheus

What it is

Cortex is a CNCF incubating project that extends Prometheus with horizontally scalable, highly available, multi-tenant long-term storage. It accepts Prometheus metrics via remote write, stores them durably, and serves PromQL queries across months or years of data. Cortex lets organizations run Prometheus-as-a-Service without losing data when individual Prometheus instances restart.

It targets platform teams and SRE organizations that run Prometheus at scale and need durable metric storage, multi-tenancy for different teams, and query federation across multiple Prometheus instances.

How it saves time or tokens

Standalone Prometheus stores metrics locally and loses data on restart or disk failure. Cortex adds durable storage with object store backends (S3, GCS, Azure Blob), so metric history persists indefinitely. Multi-tenancy means one Cortex cluster serves multiple teams without running separate Prometheus stacks for each. Horizontal scaling handles growing ingestion rates without re-architecting.

How to use

1. Deploy Cortex components (distributor, ingester, querier, compactor) using Helm charts or Docker Compose.
2. Configure your existing Prometheus instances to remote-write to Cortex's distributor endpoint.
3. Point Grafana or other visualization tools at Cortex's query endpoint for long-term metric queries.

Example

# prometheus.yml - configure remote write to Cortex
remote_write:
  - url: http://cortex-distributor:9009/api/v1/push
    headers:
      X-Scope-OrgID: team-backend

# Query long-term metrics via Cortex
# Grafana datasource: http://cortex-querier:9009/prometheus

Related on TokRepo

• Monitoring tools — Observability and metrics solutions
• DevOps tools — Infrastructure and operations automation

Common pitfalls

• Cortex has many microservice components. Start with single-binary mode for testing, then decompose into microservices for production scaling.
• Object storage costs accumulate with long retention periods. Configure compaction and downsampling to manage storage costs for multi-year retention.
• Multi-tenancy requires setting the X-Scope-OrgID header on all requests. Missing headers cause authentication errors or data routing to a default tenant.