HTTP API

One way to get metrics into Anomify is to send them via POST request to an endpoint on a dedicated host on our platform where they will be ingested and anomaly analysis will start automatically. Follow the steps below.

Where to POST Metrics

/flux is responsible for receiving metric data via HTTP POST requests. It's available via the metric_data_post endpoint on your Anomify host. You'll need to authenticate requests using a key. You'll find your Anomify host and API key in the Integrations section of the settings pages along with some code examples.

/flux will accept time-series data from any source in real time, as long as it is sent in chronological order and at regular intervals. Timestamps must be valid (not in the future). Use a reliable time source to ensure accurate timestamps. Analysis will start after 100 datapoints have been sent.

How to POST metrics

Try to send no more than 500 metrics per post the maximum payload size is 1024K. Here is an example of the data a multiple-metrics POST requires and an example POST request for 2 metrics.

{
    "key": "<ANOMIFY_API_KEY | str>",
    "metrics": [
        {
            "metric": "test.nginx-1.cpu.user",
            "timestamp": <SAMPLE_TIMESTAMP | int>,
            "value": 1.0
        },
        {
            "metric": "test.nginx-2.cpu.user",
            "timestamp": <SAMPLE_TIMESTAMP | int>,
            "value": 2.2
        }
    ]
}

POSTing the example data using curl:

SAMPLE_TIMESTAMP=$(date +%s)
curl -v -d '{"key":"<ANOMIFY_API_KEY>","metrics":[{"metric":"test.nginx-1.cpu.user","timestamp":'$SAMPLE_TIMESTAMP',"value":1.0},{"metric":"test.nginx-2.cpu.user","timestamp":'$SAMPLE_TIMESTAMP',"value":2.2}]}' -H "Content-Type: application/json" -X POST https://<YOUR_ANOMIFY_HOST>/flux/metric_data_post

Responses to handle

A successful POST results in a HTTP status code of 204.

HTTP status code 207

When using an account with a metric quota, if you POST more metrics than your quota allows, we will accept known metrics and reject new metrics that are over your quota limit. So ensure you handle 207 status codes.

The 207 response will return a content-type: application/json body with details of which metrics were accepted and processed and which metrics were rejected as they are over the quota, for example:

{
    "code": 207,
    "data": [
        {"metric": "server-1.unknown.metric", "status": 400},
        {"metric": "server-1.some-other-unknown.metric", "status": 400},
        {"metric": "server-1.known.metric", "status": 204},
        {"metric": "server-1.some-other-known.metric", "status": 204}
    ],
    "error": "over quota - this account is allowed x metrics and an additional y new metrics were posted that have been rejected",
    "message": "2 metrics were processed and 2 metrics were rejected",
    "rejected metrics": ["server-1.unknown.metric", "server-1.some-other-unknown.metric"],
    "rejected metrics count": 2,
    "processed metrics": ["server-1.known.metric", "server-1.some-other-known.metric"],
    "processed metrics count": 2,
    "submitted metrics count": 4
}

The status code of each metric submitted is available in the data key array. Please ensure you handle 207 responses appropriately.

HTTP Status Code Error Messages

If any metric or POST variables in the POST requests are invalid the entire POST will be rejected with a HTTP status code 400 or 401. A reason will be returned in the json payload.

{"code": 400, "message": "invalid json data"}

Possible messages in the json payload when a 400 is returned:

    invalid json data
    no POST data received
    no key passed
    no metric data passed
    invalid metrics element
    invalid metric - <passed_metric_name>
    invalid metric - <passed_metric_name> - invalid characters in name
    invalid metric - <passed_metric_name> - longer than 255 characters
    invalid metric - <passed_metric_name> - name too long
    invalid metric
    invalid timestamp - <passed_timestamp>
    invalid timestamp - <passed_timestamp> - timestamp is not an int
    invalid timestamp - <passed_timestamp> - timestamp is not a valid current unix timestamp
    invalid timestamp - <passed_timestamp> - timestamp is too old, older than X seconds
    invalid timestamp - <passed_timestamp> - timestamp is more than 1 minute in the future
    invalid timestamp
    invalid value - <passed_value>
    invalid value
    no value parameter present
    invalid value data passed
    Invalid parameter received - <parameter>

HTTP Status code 413 means that the payload is too large, do not resend.

Testing your ingestion configuration

To test your configuration you can add x-test-only as a header on HTTP requests to Anomify. Metrics sent this way won't be analysed by Anomify but will appear as a list in the Metric Ingestion Test Page in settings. Once you're happy that you are sending the correct metrics, remove the x-test-only header and analysis will start after 100 datapoints have been sent. An example of including the x-test-only header can be seen below:

SAMPLE_TIMESTAMP=$(date +%s)
curl -v -d '{"key":"<ANOMIFY_API_KEY>","metrics":[{"metric":"test.nginx-1.cpu.user","timestamp":'$SAMPLE_TIMESTAMP',"value":1.0},{"metric":"test.nginx-2.cpu.user","timestamp":'$SAMPLE_TIMESTAMP',"value":2.2}]}' -H "Content-Type: application/json" -H "x-test-only:true" -X POST https://ingress-stage.anomify.ai/flux/metric_data_post