Next, we present the ingestion protocol format and its syntax. Please be aware of the empty spaces that separate the main values.
Elements represented within brackets are optional:
metric[,tag1=value][,tag2=value] value unix_timestamp [aggregation1][,aggregation2][,aggregation_frequency]
Tags are an optional element. These are formatted as key=value with a semicolon between each key-value pair. Statful is agnostic to the tags you use, so you are free to use whatever tag and value you think that makes sense in your scenario. The following non-Unicode characters are also an option:
Value represents the value that must be ingested by Statful. It is accepted as any positive or negative digital character from
Unix Timestamp is a point in time to which your metric (
value) is associated when stored. It must be represented by seconds since EPOCH (i.e., in Unix time).
Aggregation represents the function that Statful must use to aggregate the values received during a specified time interval. This element is optional, but if it is presented, then the
aggregation_frequency field must also be supplied.
Aggregation Frequency represents the time interval in which Statful considers the values received before executing an
aggregation function. This value is expected in positive integers with pre-defined values ranging from 10s to 300s. The full list of supported aggregations and frequencies is available here.
curl request looks as follows:
$ curl “https://api.statful.com/tel/v2.0/metrics" -X PUT -H “M-Api-Token: 23dh4f07-03sb-47f3-80h2-1d4434d6kgtb” -H “Content-Type: text/plain” --data-binary “test.demo.metric,client=curl,env=EU 100 $(date +%s)”
This request is sending to Statful:
- a metric named
- with a value of
- with the tags:
- key: client - value: curl
- key: env - value: EU; and
As mentioned earlier, it is possible to send aggregations in a request. Let’s say you want to send the count of data points per 10 seconds.
We can change the previous request by adding the element:
$ curl “https://api.statful.com/tel/v2.0/metrics" -X PUT -H “M-Api-Token: 23dh4f07-03sb-47f3-80h2-1d4434d6kgtb” -H “Content-Type: text/plain” --data-binary “test.demo.metric,client=curl,env=EU 100 $(date +%s)
Feel free to verify the syntax of your own request at any time in our validator below.