Skip to main content

​
Custom Metrics

Record and query custom application metrics.

​
Record Metric

POST /api/v1/metrics

​
Request

curl https://pulse.brainzlab.ai/api/v1/metrics \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "queue_size",
    "value": 42,
    "type": "gauge",
    "tags": {
      "queue": "default"
    }
  }'

​
Parameters

FieldTypeRequiredDescription
namestringYesMetric name
valuenumberYesMetric value
typestringNoType: gauge, counter, histogram (default: gauge)
tagsobjectNoKey-value tags for filtering
timestampstringNoISO8601 timestamp (default: now)

​
Response

{
  "data": {
    "id": "metric_abc123",
    "name": "queue_size",
    "value": 42,
    "type": "gauge",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

​
Metric Types

​
Gauge

A point-in-time value that can go up or down: 
{
  "name": "active_users",
  "value": 150,
  "type": "gauge"
}
Use for: queue sizes, active connections, memory usage, temperature.

​
Counter

A cumulative value that only increases: 
{
  "name": "orders_created",
  "value": 1,
  "type": "counter"
}
Use for: request counts, error counts, events processed.

​
Histogram

A distribution of values: 
{
  "name": "response_time",
  "value": 245,
  "type": "histogram"
}
Use for: latencies, sizes, durations.

​
Bulk Record

Send multiple metrics in one request: 
POST /api/v1/metrics/batch

​
Request

curl https://pulse.brainzlab.ai/api/v1/metrics/batch \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      {
        "name": "queue_size",
        "value": 42,
        "type": "gauge",
        "tags": { "queue": "default" }
      },
      {
        "name": "queue_size",
        "value": 15,
        "type": "gauge",
        "tags": { "queue": "priority" }
      },
      {
        "name": "jobs_processed",
        "value": 100,
        "type": "counter"
      }
    ]
  }'

​
Response

{
  "data": {
    "accepted": 3,
    "rejected": 0
  }
}

​
List Metrics

Get available metrics: 
GET /api/v1/metrics

​
Response

{
  "data": [
    {
      "name": "queue_size",
      "type": "gauge",
      "description": null,
      "tags": ["queue"],
      "last_value": 42,
      "last_seen_at": "2024-01-15T10:30:00Z"
    },
    {
      "name": "orders_created",
      "type": "counter",
      "description": null,
      "tags": [],
      "total": 15420,
      "last_seen_at": "2024-01-15T10:30:00Z"
    }
  ]
}

​
Query Metric Stats

Get statistics for a specific metric: 
GET /api/v1/metrics/:name/stats

​
Query Parameters

ParameterTypeDescription
sincestringTime range: 1h, 24h, 7d
intervalstringGroup by: minute, hour, day
tagsstringFilter by tags (JSON encoded)

​
Example Request

curl "https://pulse.brainzlab.ai/api/v1/metrics/queue_size/stats?since=24h&interval=hour" \
  -H "Authorization: Bearer sk_live_xxx"

​
Response (Gauge)

{
  "data": {
    "name": "queue_size",
    "type": "gauge",
    "since": "24h",
    "stats": {
      "current": 42,
      "min": 5,
      "max": 150,
      "avg": 45.5
    },
    "series": [
      { "timestamp": "2024-01-14T11:00:00Z", "value": 35 },
      { "timestamp": "2024-01-14T12:00:00Z", "value": 42 },
      { "timestamp": "2024-01-14T13:00:00Z", "value": 50 }
    ]
  }
}

​
Response (Counter)

{
  "data": {
    "name": "orders_created",
    "type": "counter",
    "since": "24h",
    "stats": {
      "total": 1542,
      "rate_per_minute": 1.07
    },
    "series": [
      { "timestamp": "2024-01-14T11:00:00Z", "count": 65 },
      { "timestamp": "2024-01-14T12:00:00Z", "count": 72 },
      { "timestamp": "2024-01-14T13:00:00Z", "count": 58 }
    ]
  }
}

​
Response (Histogram)

{
  "data": {
    "name": "response_time",
    "type": "histogram",
    "since": "24h",
    "stats": {
      "count": 15420,
      "min": 5,
      "max": 2500,
      "avg": 125,
      "p50": 85,
      "p95": 350,
      "p99": 750
    },
    "buckets": [
      { "le": 50, "count": 5200 },
      { "le": 100, "count": 8500 },
      { "le": 250, "count": 12000 },
      { "le": 500, "count": 14500 },
      { "le": 1000, "count": 15200 },
      { "le": "+Inf", "count": 15420 }
    ]
  }
}

​
Tags

Use tags to segment metrics: 
{
  "name": "response_time",
  "value": 150,
  "type": "histogram",
  "tags": {
    "endpoint": "/api/users",
    "method": "GET",
    "environment": "production"
  }
}
Query by tag: 
GET /api/v1/metrics/response_time/stats?tags={"endpoint":"/api/users"}

​
Rate Limits

  • Single metric: Standard rate limit
  • Batch: 10 requests/minute, up to 1000 metrics per request

​
Errors

CodeDescription
invalid_typeType must be gauge/counter/histogram
invalid_valueValue must be a number
name_too_longName exceeds 255 characters
too_many_tagsMore than 10 tags provided
batch_too_largeBatch exceeds 1000 metrics