api.rst

Go Metrics HTTP API

Contents

• response-format-overview
• metric-types
• api-authentication

• api-methods

  • :http:get:/api/metrics/

Response Format Overview

Successful responses to GET requests will contain the requested data in json format.

Example response (success response):

http

HTTP/1.1 200 OK { ... }

Errors are returned with the relevant HTTP error code and a json object containing status_code, the HTTP status code, and reason, the reason for the error.

Example response (error response):

http

HTTP/1.1 400 Bad Request { "status_code": 400, "reason": "Bad Request" }

Metric Types

Account Metrics

Account metrics are metrics relevant to a particular account, but not necessarily relevant to a particular conversation in the account. All metrics published via Vumi Go javascript sandbox applications are account metrics. Account metric names take the form stores.<store_name>.<metric_name>.<agg_method>:

• store_name: the namespace used for publishing the metrics (e.g. default). For javascript sandbox applications, the store name matches the configured name for the app in the conversation config unless configured otherwise.
• metric_name: the name of the metric (e.g. questions_completed).
• agg_method: the aggregation method used to publish metric values (e.g. last).

Conversation Metrics

Conversation metrics are metrics relevant only to a particular conversation, for example, the total messages sent in the conversation. Conversation metric names take the form conversations.<conv_id>.<metric_name>.<agg_method>:

• conv_id: the UUID for the conversation.
• metric_name: the name of the metric (e.g. messages_sent).
• agg_method: the aggregation method used to publish metric values (e.g. last).

At the time of writing, conversation metrics are only fired by internal Vumi Go processes.

Null Handling

The value of each datapoint returned from graphite will often be null. This case happens when there is no value relevant to that particular time. The api provides several ways of handling these null values:

• zeroize: Turns each null into a 0.
• omit: Returns the datapoints with null values omitted.
• keep: Keeps the null values around.

See :http:get:/api/metrics/'s nulls query parameter to see how this handling can be configured when querying the api for metrics.

API Authentication

Authentication is done using an OAuth bearer token.

Example request:

http

GET /api/metrics/ HTTP/1.1 Host: example.com Authorization: Bearer auth-token

Example response (success):

http

HTTP/1.1 200 OK

Example response (failure):

http

HTTP/1.1 403 Forbidden

Example response (no authorization header):

http

HTTP/1.1 401 Unauthorized

API Methods