Skip to main content

Ingesting Metrics To CtrlB via JSON API

This document provides instructions for ingesting metrics directly into CtrlB using JSON-based HTTP APIs. This method is suitable for custom integrations, lightweight systems, or environments without Prometheus or OpenTelemetry.

Protocol Specifications​

  • Ingestion Protocol: HTTP JSON
  • Endpoint URL: http(s)://<INSTANCE_HOST>/api/<ORG_ID>/ingest/metrics/_json
  • Payload Format: JSON Array
  • Authentication Method: HTTP Basic Authentication via Authorization header
  • Content-Type: application/json

Payload Requirements​

  • Payload must be a JSON array
  • Each element represents a metric object
  • Each record must include the following required fields:
    • __name__: metric name (record is dropped if missing)
    • value: must be a finite numeric value (record is dropped if missing or non-numeric)

Timestamp handling:

  • Field must be named exactly _timestamp
  • If _timestamp is omitted, server uses ingestion time
  • Accepted formats: seconds, milliseconds, microseconds, or nanoseconds (auto-detected by magnitude)

Example Payload​

[
  {
    "__name__": "cpu_usage",
    "value": 72,
    "_timestamp": 1710000000000
  },
  {
    "__name__": "memory_usage",
    "value": 64,
    "_timestamp": 1710000001000
  }
]

Example Request​

curl -X POST http://<INSTANCE_HOST>/api/<ORG_ID>/ingest/metrics/_json \
  -H "Authorization: Basic <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '[{"metric_name":"cpu","value":50}]'

Implementation Notes​

CtrlB:

  • Parses JSON array
  • Validates structure
  • Processes metrics using JSON handler
  • Single object is not allowed -- must be wrapped in array

Validation Procedures​

Test Data Submission​

Send a sample request using curl or Postman.

Verification Process​

  • Access CtrlB dashboard
  • Filter metrics within recent time window
  • Validate metric values and timestamps

Troubleshooting Guide​

Payload Errors​

HTTP 400 Bad Request

  • Ensure payload is a JSON array
  • Validate JSON syntax

Authentication Errors​

HTTP 401 Unauthorized

  • Verify Authorization header format

Endpoint Errors​

HTTP 404

Confirm endpoint:

/api/<ORG_ID>/ingest/metrics/_json

Data Issues​

  • Missing fields -> metrics may not be processed
  • Invalid timestamps -> incorrect visualization

Performance Considerations​

  • Batch multiple metrics in one request
  • Avoid very large payloads
  • Implement retry logic for failures