Sumo Logic Metrics APIs
The Metrics Query API lets you execute Metrics queries from third-party scripts and applications so that you can reformat the results as desired.
This API follows Representational State Transfer (REST) patterns and is optimized for ease of use and consistency.
Refer to Getting Started for Authentication and Endpoint information.
Sumo Logic has several deployment types, which vary by geographic location and the date an account is created. Select the documentation link below that corresponds to your deployment. If you're not sure, see How to determine your endpoint.
Before You Begin
You will need:
- An Enterprise account. For more information, see Cloud Flex or Cloud Flex Credits, depending on the Sumo Logic packaging you have.
- An access key/access ID for authentication. Username/password are not supported.
Endpoints for API access
Sumo Logic has deployments that are assigned depending on the geographic location and the date an account is created. For API access, you must manually direct your API client to the correct Sumo Logic API URL.
See Sumo Logic Endpoints for the list of the URLs.
An HTTP 301 Moved error suggests that the wrong endpoint was specified.
Rate limiting
- A rate limit of four API requests per second (240 requests per minute) applies to all API calls from a user.
- A rate limit of 10 concurrent requests to any API endpoint applies to an access key.
If a rate is exceeded, a rate limit exceeded 429 status code is returned.
Errors
Generic errors that apply to all APIs.
| Code | Error | Description |
| 301 | moved | The requested resource SHOULD be accessed through returned URI in Location Header. |
| 401 | unauthorized | Credential could not be verified. |
| 403 | forbidden | This operation is not allowed for your account type. |
| 404 | notfound | Requested resource could not be found. |
| 405 | method.unsupported | Unsupported method for URL. |
| 415 | contenttype.invalid | Invalid content type. |
| 429 | rate.limit.exceeded | The API request rate is higher than 4 request per second. |
| 500 | internal.error | Internal server error. |
| 503 | service.unavailable | Service is currently unavailable. |
API details
Executing a query
To execute a metrics query, send a JSON request to the endpoint.
Method: POST
Example endpoint: https://api.sumologic.com/api/v1/metrics/results
Sumo Logic endpoints like api.sumologic.com are different in deployments outside us1. For example, an API endpoint in Europe would begin api.eu.sumologic.com. A service endpoint in us2 (Western US) would begin service.us2.sumologic.com. For more information, see Sumo Logic Endpoints.
Headers
| Header | Value |
| Content-Type | application/json |
| Accept | application/json |
Query request parameters
| Parameter | Type | Required | Description |
| query | [QueryWithRowId] | Yes | The actual query expressions. |
| startTime | long | Yes | Start of the query time range, in milliseconds since epoch. |
| endTime | long | Yes | End of the query time range, in milliseconds since epoch. |
| requestedDataPoints | int | No | Desired number of data points returned per series. |
| maxDataPoints | Int | No | Upper bound on number of data points returned per series |
| maxTotalDataPoints | Int | No | Upper bound on sum total number of data points returned across all series. |
| desiredQuantizationInSec | Int | No | Desired granularity of temporal quantization (DAVID A TODO LINK), in seconds. Note that this may be overridden by the backend in order to satisfy constraints on the number of data points returned. |
QueryWithRowId object
| Parameter | Type | Required | Description |
| query | String | Yes | The actual metrics search expression. |
| rowId | String | Yes | Name or alias for this “row” of the query. |
Status codes
| Code | Text | Description |
| 200 | Success | The query has been successfully executed. |
| 400 | Bad Request | Generic request error by the client. |
| 415 | Unsupported Media Type | Content-Type wasn't set to application/json. |
Query Result
The result will be a JSON document containing results (or an error) for each query row in the “query” argument.
| Parameter | Type | Description |
| response | [MetricsErrorsOrResults] | Results (or error) for each row-query. |
| queryInfo | MetricsQueryInfo | Information about the original user query. |
MetricsQueryInfo object
| Parameter | Type | Description |
| startTime | long | Start of the query time range, in milliseconds since epoch. |
| endTime | long | End of the query time range, in milliseconds since epoch. |
| desiredQuantizationInSecs | int | Original user-supplied desired granularity of temporal quantization (if supplied). |
| actualQuantizationInSecs | int | Actual granularity of temporal quantization used by the back-end for query. |
MetricsDatapointsError object
(extends MetricsErrorsOrResults)
| Parameter | Type | Description |
| rowId | String | Name or alias for this “row” of the query. |
| messageType | String | Error type. |
| message | String | Error message. |
MetricsDataPointsResult object
(extends MetricsErrorsOrResults)
| Parameter | Type | Description |
| rowId | String | Name or alias for this “row” of the query. |
| results | [MetricsRowResult] | Actual retrieved and computed values for series returned by this row’s query. |
MetricsRowResult
| Parameter | Type | Description |
| metric | MetricDef | Full metric definition for this result. |
| datapoints | MetricsDataPoints | The actual results. |
MetricDef
| Parameter | Type | Description |
| dimensions | [MetricDim] | Identifying dimensions for this metric. |
| algoId | long | Internal identifier for the outlier detection algorithm used in these results. |
MetricDim
| Parameter | Type | Description |
| key | string | Key name for this dimension. |
| value | string | Associated value for this key. |
MetricsDataPoints
| Parameter | Type | Description |
| timestamp | [long] | Timestamps (milliseconds since epoch) for each data point. |
| value | [float] | Actual numerical values for reach data point. |
| outlierParams | Internal parameters for outlier detection. | |
| Max | [float] | Maximum aggregate. |
| Min | [float] | Minimum aggregate. |
| Avg | [float] | Average aggregate. |
| Count | [int] | Count of raw observations |
Example Use
Example use of this API can be seen in this Python script, which queries the API and reformats the results into a pandas time series DataFrame.
To use this script, set the (user, pw) variables and run these commands from an IPython or Jupyter notebook:
df = exampleQuery(user, pw, query)
df.fillna(method='backfill').plot()
plt.show()
You should get a resulting plot like below, and df should contain your data nicely formatted as a time series pandas DataFrame.
