Writing Raw Data
In contrast to the other submission APIs (numeric, text, histogram), which accept specifically-typed data, the raw API accepts direct input of measurement data at arbitrary frequencies. It stores every measurement as it was received, for a configurable amount of time, before aging it out to a rollup format.
Metric records are in one of several formats, and are accepted as either tab-separated values or as FlatBuffer messages.
Metric Record Formats
Raw metric records may be submitted in one of several formats, depending on the type of metric data contained within.
PUT | POST
TSV Numeric Or Text Metric Format
Individual numeric or text metrics submitted to the raw endpoint as lines of
ASCII characters use the following format, referred to as an
M TIMESTAMP UUID NAME TYPE VALUE
Components are separated by TAB characters. Multiple records may be sent in the
same operation, separated by newline (
M: Denotes an
TIMESTAMP: An epoch timestamp recording the time of the observation, with milliseconds. In terms of format, it is
1516820826.120. While this might look like a float, it is, in fact, a strict textual format that requires exactly three digits after the decimal point. These must always be included, even if they are
UUID: An identifier of the account and check to which this metric
- belongs. Despite its name, this identifier must be in the form:
TARGETis conventionally the IP address of the check target, but may be any meaningful string identifying the subject of the check.
MODULEis conventionally the name of the Reconnoiter check module.
CIRCONUS_NAMEis what determines both the account and check to which this metric belongs. It has the form
ACCOUNT-IDis the most significant, as this is how metric data is partitioned within IRONdb.
lower-cased-uuidis the check UUID, lower-cased.
NAME: The name of this metric. The conventional format for hierarchical naming is "name`subname`subsubname`etc."
TYPE: The type of data that the
VALUE: The value observed.
VALUEis always a string or
Numeric measurements which collide on TIMESTAMP/UUID/NAME will store the largest absolute value for that time period, by default. This behavior is configurable.
M 1512691226.137 example.com`http`c_123_987654::http`1b988fd7-d1e1-48ec-848e-55709511d43f duration I 1
This is a metric,
duration, on account
123, for the HTTP check
1b988fd7-d1e1-48ec-848e-55709511d43f with a TYPE of uint32 (
I) and a VALUE
TSV Histogram Metric Format
Histogram submission is similar to
M records above, but instead of a
single-value payload, a base64-encoded serialization of the histogram structure
is used. This is referred to as an
H1 record. As with
M records, the
components are tab-separated.
H1 TIMESTAMP UUID NAME HISTOGRAM
TIMESTAMP: Same as with
UUID: Same as with
NAME: Same as with
HISTOGRAM: A base64-encoded, serialized histogram. See the
hist_serialize()function in libcircllhist, the reference implementation of histograms in Circonus.
H1 1512691200.000 example.com`ping_icmp`c_123_45678::ping_icmp`c50361d8-7565-4f04-8128-3cd2613dbc82 maximum AAFQ/gAB
This is a histogram of values for the metric
maximum, on an ICMP check for
A FlatBuffer metric payload is submitted as a
MetricList as specified in the
When submitting FlatBuffer-encoded metrics, a client must set the HTTP header
application/x-circonus-metric-list-flatbuffer and set the
X-Snowth-Datapoints to the number of data points within the raw