Support API

Stats API

Stats API

The Loggly Stats API is a RESTful API that allows Loggly Enterprise tier customers to query historical statistics (such as sum, average, percentiles, etc.) of the events. The Stats API provides an advanced querying interface that allows fine grained time period and searching control. This document provides a basic overview of the Stats API and documents all available stats endpoints.

Stats Endpoints

The base endpoint for the Stats API is https://SUBDOMAIN.loggly.com/apiv2/stats/STAT_TYPE/FIELD?PARAMS

Replace the variable:

  • SUBDOMAIN: Replace with your Loggly subdomain.
  • STAT_TYPE: Replace with one from the table below.
  • FIELD: Replace with an indexed field name (only numeric fields are allowed).
  • PARAMS: Optional parameters (search query), f.e. q=error&from=-1h.

All URLs are relative to that endpoint.

All stats calls work of the field name being supplied.

The supported statistics endpoints are the following.

Endpoint Description
avg Average of all values of the field during the time frame specified in the query.
sum
Sum of all values of a field during the time frame specified in the query.
min
Minimum value out of all values of the field during the time frame specified in the query.
max
Maximum value out of all values of the field during the time frame specified in the query.
percentiles The value below which a given percentage of events falls. Returned percentiles are 1, 5, 25, 50, 75, 95, 99%.
value_count Count of the events during the time frame specified in the query.
cardinality Calculates an approximate count of distinct values of the field.
stats View basic Stats – avg, sum, min, max, count.
all or
extended
In addition to the basic stats (avg, sum, min, max, count), extended/all stats will also provide variance, std_deviation and sum_of_squares.

Authentication

To authenticate, use the “Authorization” key in the HTTP header with the value of the word “bearer” followed by your Loggly search token (see the Token Based API Authentication). Alternatively you can use your username and password. The following are examples using the command-line tool cURL:
curl -H "Authorization: bearer SEARCH_TOKEN" https://SUBDOMAIN.loggly.com/apiv2/stats/all/json.lineno?q=*&from=-1h&until=now
curl -u "username:password" https://SUBDOMAIN.loggly.com/apiv2/stats/sum/json.cid?q=*&from=-1d

Stat API Usage Example

If you want to see “all” stats for “json.OpcodeValue” during the last hour, you could run the command below from your terminal window. In this example, you would use the “all” endpoint followed by the field in question:

curl --user 'username:password' -XGET 'https://SUBDOMAIN.loggly.com/apiv2/stats/all/json.OpcodeValue?q=*&from=-1h'

Response:

{
  "field": "json.OpcodeValue",
  "stats": {
    "count": 35948,
    "min": 0.0,
    "sum_of_squares": 2.0,
    "max": 1.0,
    "sum": 2.0,
    "std_deviation": 0.007458741394738288,
    "variance": 5.563282319358245e-05,
    "avg": 5.563591854901524e-05
  }
}

Similarly, if you want to see the sum of all values for the same field, then replace “all” with “sum” as shown below:

curl --user 'username:password' -XGET 'https://SUBDOMAIN.loggly.com/apiv2/stats/sum/json.OpcodeValue?q=*&from=-1h'

Response:

{
  "field": "json.OpcodeValue",
  "stats": {
    "sum": 2.0
  }
}
Stats Endpoint Parameters
q optional query string, check out the Search Query help
from optional Start time for the search. Defaults to “-24h”.
(See valid time parameters.)
until optional End time for the search. Defaults to “now”.
(See valid time parameters.)

Response Format

To make it easier to understand how a query is being processed we use a specific JSON response format. Here is an example:

{
"field": "json.lineno",
"stats": {
"count": 1,
"min": 267.0,
"sum_of_squares": 71289.0,
"max": 267.0,
"sum": 267.0,
"std_deviation": 0.0,
"variance": 0.0,
"avg": 267.0
}
}
  
Thanks for the feedback! We'll use it to improve our support documentation.