Prometheus

New here? Start with the Quickstart to launch Icelake + Grafana locally and send your first metric in 5 minutes.

Getting started

Icelake exposes a drop-in Prometheus remote write endpoint. Ship your metrics without changing your existing Prometheus setup — just point remote write at Icelake.

1. Configure Prometheus remote write

Add Icelake as a remote write target in your prometheus.yml. Authentication is HTTP Basic auth — username is your client ID, password is your API key (the ilk_… secret):

prometheus.yml

remote_write:
- url: "https://api.icelake.eu/api/v1/prom/push"
  basic_auth:
    username: "your-client-id"
    password: "ilk_your-api-key-here"
  queue_config:
    max_samples_per_send: 5000
    batch_send_deadline: 5s
    max_shards: 10

2. Verify ingestion

Check that metrics are flowing into Icelake:

# Check the health endpoint
curl https://api.icelake.eu/healthz

# Query ingested metrics via the Prometheus-compatible API
curl -u "your-client-id:ilk_your-api-key-here" "https://api.icelake.eu/prom/api/v1/query?query=up"

3. Configure the Grafana datasource

Add Icelake as a Prometheus datasource in Grafana:

Grafana Datasource

# Grafana Datasource Configuration
Name: Icelake Metrics
Type: Prometheus
URL: https://api.icelake.eu/prom
Authentication: Basic auth
User:     your-client-id
Password: ilk_your-api-key-here

What’s supported

Remote write (v1)

Full compatibility with the Prometheus remote write protocol:

Remote write endpoint

# Endpoint
POST /api/v1/prom/push

# Content-Type
application/x-protobuf

# Authentication
Authorization: Basic base64("client_id:api_key")

Query API

Prometheus-compatible query endpoints:

Query Endpoints

# Label names
GET /prom/api/v1/labels

# Instant query
GET /prom/api/v1/query?query=<expr>&time=<timestamp>

# Range query
GET /prom/api/v1/query_range?query=<expr>&start=<start>&end=<end>&step=<step>

# Label values
GET /prom/api/v1/label/<label_name>/values

# Series metadata
GET /prom/api/v1/series?match[]=<selector>

# Metric metadata
GET /prom/api/v1/metadata

Storage layout

Metrics are stored as Parquet files on S3 with time-based partitioning:

S3 Storage Layout

s3://icelake-data/
└── metrics/
  └── tenant=default/
      ├── 2026/02/20/
      │   ├── metrics_001.parquet
      │   ├── metrics_002.parquet
      │   └── compacted_001.parquet
      └── 2026/02/21/
          └── metrics_001.parquet

Advanced configuration

High-throughput ingestion

For high-volume Prometheus setups, tune the queue config:

# prometheus.yml - optimized for high throughput
remote_write:
- url: "https://api.icelake.eu/api/v1/prom/push"
  basic_auth:
    username: "your-client-id"
    password: "ilk_your-api-key-here"
  queue_config:
    max_samples_per_send: 10000
    batch_send_deadline: 3s
    max_shards: 20
    capacity: 50000

API reference

Endpoint	Method	Description
/api/v1/prom/push	POST	Remote write ingestion
/prom/api/v1/labels	GET	All label names
/prom/api/v1/label/<name>/values	GET	Label values
/prom/api/v1/series	GET	Series metadata
/prom/api/v1/query	GET/POST	Instant query
/prom/api/v1/query_range	GET/POST	Range query
/prom/api/v1/metadata	GET	Metric metadata

Best practices

Pro tip: use Prometheus recording rules to pre-aggregate high-cardinality metrics before shipping to Icelake.

• Tune batch_send_deadline to match your latency requirements
• Use tenant-scoped API keys for multi-team environments
• Monitor ingestion rates via the /metrics endpoint
• Configure compaction intervals based on ingestion volume

Related docs

• Quickstart — end-to-end Icelake + Grafana setup in 5 minutes
• Query Interfaces — Grafana, pgwire SQL, REST, and the Loki Query API
• Home Assistant — ship HA entities via this same remote write endpoint