Metrics quickstart

By the end of this guide you’ll have sent a counter and a gauge from your laptop, queried them via the API, and seen them on a dashboard chart.

1. Send a metric

curl -X POST https://metrics.siteqwality.com/v1/ingest \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      {
        "type": "counter",
        "name": "demo.requests",
        "value": 1,
        "tags": { "endpoint": "/checkout", "status_class": "2xx" }
      },
      {
        "type": "gauge",
        "name": "demo.queue_depth",
        "value": 42,
        "tags": { "queue": "orders" }
      }
    ]
  }'

A 202 Accepted means the metrics were queued. Datapoints land in ClickHouse within ~10 seconds.

Tip

The ingest endpoint accepts up to 1000 metrics per request. Batch where you can — fewer requests = lower API gateway costs and faster ingestion.

2. Send some more so we have a series

A single point isn’t a chart. Loop:

for i in {1..30}; do
  VALUE=$((RANDOM % 100))
  curl -X POST https://metrics.siteqwality.com/v1/ingest \
    -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{ \"metrics\": [{
      \"type\": \"gauge\",
      \"name\": \"demo.queue_depth\",
      \"value\": $VALUE,
      \"tags\": { \"queue\": \"orders\" }
    }] }" > /dev/null
  sleep 5
done

This gives you 30 points over 2.5 minutes — enough to render a chart.

3. Query the metric

Dashboard

Metrics → Explorer, type demo.queue_depth in the metric name, leave defaults. The chart renders.

API

START=$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ)
END=$(date -u +%Y-%m-%dT%H:%M:%SZ)

curl -G https://api.siteqwality.com/metrics/query \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  --data-urlencode "metric_name=demo.queue_depth" \
  --data-urlencode "aggregation=avg" \
  --data-urlencode "start_time=$START" \
  --data-urlencode "end_time=$END" \
  --data-urlencode "resolution=1m"

Response includes series[] with points[] of {timestamp, value}.

4. Add it to a dashboard

Dashboard

1. Dashboards → New dashboard. Name it Demo.

2. Add widget → Timeseries. Pick the metric demo.queue_depth. Aggregation avg. Layout to taste.

3. Save.

API

See Dashboards quickstart for the wire-level shape.

5. Wire your real app

Most languages have a Prometheus client that can convert to SiteQwality’s format trivially. The shape closely mirrors OpenTelemetry / Prometheus.

For ad-hoc instrumentation:

import os, time, requests

API = "https://metrics.siteqwality.com/v1/ingest"
KEY = os.environ["SITEQWALITY_API_KEY"]

def send_counter(name, value=1, tags=None):
    requests.post(API, json={
        "metrics": [{
            "type": "counter",
            "name": name,
            "value": value,
            "tags": tags or {},
        }]
    }, headers={"Authorization": f"Bearer {KEY}"}, timeout=5)

# In your code
send_counter("orders.created", tags={"region": "us-east-1"})

For production, batch + flush periodically rather than one-request-per-metric.

What’s next

Metrics reference Endpoint, query syntax, naming rules.

Logs The next pillar.

Dashboards Compose metrics into shared views.