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.
Refer to Getting Started for Sumo Logic API Authentication, Endpoints, and Security.
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
The APIs return operation failures with a description and error code, including the following 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
Which API endpoint should I use?
To determine which Sumo Logic API endpoint you should use, find the deployment pod referenced in your browser's Sumo Logic service URL.
If you see https://service.us2.sumologic.com, for example, that means you're running on the US2 pod and need to use the API endpoint https://api.us2.sumologic.com/api/. For the service URL https://service.eu.sumologic.com, you'd need to use the API endpoint https://api.eu.sumologic.com/api/, and so on. The only exception is the US1 pod (https://service.sumologic.com), which uses the API endpoint https://api.sumologic.com/api/.
To view all available endpoints, 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 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.