Gauge Quick Start Guide

Getting Started

Send metrics with a single curl command.

curl -X POST "https://gauge.firchy.com/v1/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  -d '{"key":"cpu_usage","value":12,"timestamp":'$(date +%s)'}'

Parameters

YOUR_API_KEY: Available in your dashboard
key: Name of the metric (e.g., cpu_usage, memory_usage)
value: Numeric value
timestamp: Unix timestamp (seconds or milliseconds) or ISO 8601 format

Using Tags

Tags let you categorize metrics by host, environment, or other dimensions.

curl -X POST "https://gauge.firchy.com/v1/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  -d '{"key":"cpu_usage","value":12,"timestamp":'$(date +%s)',"tags":{"host":"node1"}}'

Example Tags

"tags": {"host": "node1"}
"tags": {"service": "api", "region": "us-west"}
"tags": {"env": "production", "version": "v2.1"}

Sending Multiple Metrics

You can send multiple metrics in a single request using NDJSON (newline-delimited JSON).

NOW=$(date +%s)

curl -X POST "https://gauge.firchy.com/v1/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  -d '{"key":"cpu_usage","value":42,"timestamp":'$NOW'}
{"key":"memory_usage","value":78,"timestamp":'$NOW'}
{"key":"disk_usage","value":65,"timestamp":'$NOW'}'

Important: Avoid Random Values in Tags

Tags group time series data together. Using random values like user IDs, request IDs, or UUIDs prevents rollup aggregation, which wastes storage rows.

Bad Example

"tags": {"request_id": "uuid-12345"}
"tags": {"user_id": "user-67890"}

Good Example

"tags": {"host": "server-01"}
"tags": {"region": "us-west"}
"tags": {"env": "production"}

Automatic Rollups

Metrics are automatically aggregated for efficient long-term storage.

Rollup Schedule

1-minute intervals: Raw data aggregated into 1-minute summaries
15-minute intervals: 1-minute data aggregated into 15-minute summaries

Metrics with identical tags are grouped together during rollups, enabling fast queries.