Want to send metrics to Better Stack?
Create a new Prometheus source and start using this API.
This endpoint allows you to send a single metric or a list of metrics. The events can be encoded in JSON or preferably in a more efficient MessagePack.
You can use these metrics to build Dashboards using the built-in metrics value
, rate
, series_id
, and tags
. Please note that not all sources support sending metrics.
Create a new Prometheus source and start using this API.
Headers
Either application/json, application/msgpack, or application/x-ndjson
Bearer $SOURCE_TOKEN
Body parameters
An array of metrics encoded in JSON or MessagePack, or newline-delimited JSONs of metrics
A single metric encoded in JSON or MessagePack
The metric was, or the metrics were successfully logged.
You provided an invalid source token, or the source doesn't allow metrics ingestion.
Response body
Unauthorized
The body is not a valid JSON or MessagePack.
Response body
Couldn't parse JSON content.
The body is too large (over 20 MiB).
Response body
payload reached size limit
Send a single metric using cURL:
curl -X POST https://in.logs.betterstack.com/metrics \
-H "Authorization: Bearer $SOURCE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"test_metric","gauge":{"value":123}}'
curl -X POST https://in.logs.betterstack.com/metrics \
-H "Authorization: Bearer $SOURCE_TOKEN" \
-H "Content-Type: application/x-ndjson" \
-d '{"name":"test_metric","gauge":{"value":123}}'
# Python is required to prepare the binary data in this example
python3 -c 'import msgpack; \
print(msgpack.packb( \
{"name":"test_metric","gauge":{"value":123}} \
).hex())' \
| xxd -r -p \
| curl -X POST https://in.logs.betterstack.com/metrics \
-H "Authorization: Bearer $SOURCE_TOKEN" \
-H "Content-Type: application/msgpack" \
--data-binary @-
Send multiple metrics using cURL:
curl -X POST https://in.logs.betterstack.com/metrics \
-H "Authorization: Bearer $SOURCE_TOKEN" \
-H "Content-Type: application/json" \
-d '[{"name":"metric_a","gauge":{"value":3.14}},{"name":"metric_b","counter":{"value":42}}]'
curl -X POST https://in.logs.betterstack.com/metrics \
-H "Authorization: Bearer $SOURCE_TOKEN" \
-H "Content-Type: application/x-ndjson" \
-d $'{"name":"metric_a","gauge":{"value":3.14}}\n{"name":"metric_b","counter":{"value":42}}'
# Python is required to prepare the binary data
python3 -c 'import msgpack; \
print(msgpack.packb( \
[{"name":"metric_a","gauge":{"value":3.14}},{"name":"metric_b","counter":{"value":42}}] \
).hex())' \
| xxd -r -p \
| curl -X POST https://in.logs.betterstack.com/metrics \
-H "Authorization: Bearer $SOURCE_TOKEN" \
-H "Content-Type: application/msgpack" \
--data-binary @-
By default, the time of the metric will be the time of receiving it. You can override this by including a field dt
containing the event time either as:
1672490759
, 1672490759123
, 1672490759123456000
2022-12-31T13:45:59.123456Z
, 2022-12-31 13:45:59.123456+02:00
Alternatively, you can use ISO 8601, as it will most likely use a format compatible with RFC 3339. In MessagePack, you can also use the timestamp extension type.
In case the timestamp can't be parsed, we save it as a string, but revert to using the reception time as the event time.
Events can be send with a time that is up to 15 minutes in the past.
curl -X POST https://in.logs.betterstack.com \
-H "Authorization: Bearer $SOURCE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"test_metric","gauge":{"value":123},"dt":"2023-08-09 07:03:30+00:00"}'
A gauge represents a single numerical value that can go up or down. Common use cases include tracking temperature, current memory usage, or system load. Gauges reflect the current state or level at the time of reporting. For example, memory usage might fluctuate, and each time you send a gauge, you're reporting the latest value.
Example:
{
"name": "cpu_temperature",
"gauge": {
"value": 63.5
}
}
A counter is a metric type used for tracking monotonically increasing values, like the number of requests served or errors encountered. Unlike gauges, counters only increase or reset to zero, they never decrease. They're ideal for counting discrete events over time.
{
"name": "requests_count",
"counter": {
"value": 42
}
}
You can use any string labels in the tags
field of your metric to provide metadata for grouping and filtering of your data.
{
"name": "cpu_temperature",
"gauge": {
"value": 63.5
},
"tags": {
"host": "server_1",
"region": "us-east",
"environment": "production"
}
}
Tags have direct impact on how do we bill for metrics. It's recommended to avoid unique or high-cardinality values that aren't necessary for your dashboards, such as process IDs, request IDs, ...
Many unique tag values can dramatically increase the number of metric series.
The HTTP REST API is limited to 500 requests per minute from a single IP.
The maximum allowed size of a single request is 20 MiB.