Skip to content

Search API

Jump to bottom
kumoroku edited this page Feb 2, 2013 · 8 revisions

Search API

This document describes the API exposed by the Sumo Logic service. It can be used to access resources and log data within the service by third party scripts and applications. The API follows REST (representational state transfer) patterns and is optimized for ease of use and consistency.

Calling the API

Authentication

Any request made to the Sumo Logic API needs to include an HTTP Basic Authentication header (see RFC 2617) generated from a users email and password. All modern browsers, as well as command line tools like curl and wget support basic authentication. This is secure, since all communication with the Sumo Logic service happens over SSL/HTTPS.

Endpoints and versioning

The base URL for all Sumo Logic API calls is https://api.sumologic.com/api/{version}, where {version} is the version of the API. The API documented here is version v1, consequently, the base URL is:

https://api.sumologic.com/api/v1/

Data formats

Resources are accepted and returned in JSON (JavaScript Object Notation) format by default. Support for other formats may be added in future versions.

Errors

Upon error, the API responds with an HTTP response and a JSON document with further details on the error. Here are some common HTTP responses:

Code Description
400 Bad Request The request was malformed.
401 Unauthorized The authentication did not succeed.
403 Forbidden No permission to access the requested resource.
404 Not Found A requested resource could not be found.
500 Server Error There was an error executing the request.
503 Service Unavailable The service is currently unavailable/in maintenance.

Error Response Example

All error responses return a JSON document with further details on the error:

{
   "status":401,
   "id": "AJ4DH-85NDL-8HYE2",
   "code":"auth.failed",
   "message":"The authentication has failed."
}

In the example above:

  • status is identical to the HTTP response code
  • id uniquely identifies the occurrence of the error
  • code is a machine readable error code intended to distinguish between errors
  • message is a human readable error message for display to end user

Error Response Codes

These are some of the error codes you might encounter:

Code Description
auth.failed Login has failed.
internal.error Internal server error.
unauthorized Email and password could not be verified.
service.unavailable Service is currently unavailable.
no.fields The list of search fields was specified, but empty.
invalid.timestamp.to The 'to' field contains an invalid time.
invalid.timestamp.from The 'from' field contains an invalid time.
to.smaller.than.from The 'from' time cannot be larger than the 'to' time.
invalid.limit The 'limit' field is not a valid number.
limit.too.small The 'limit' field is too small.
limit.too.big The 'limit' field is bigger than the maximum.
order.unknown The 'order' can only be 'asc' or 'desc'.
unknown.timezone The 'tz' value is not a known time zone.
empty.timezone The 'tz' cannot be blank.
no.query No 'q' parameter was provided.
timed.out Search has timed out. Please retry.
cancelled Search was cancelled. Please retry.
errors The search has produced errors.
no.counts The search did not return counts.
parse.error Unable to parse query.
message.retrieval.error Error retrieving messages.
aggregates.unsupported Aggregated results cannot be rendered in the selected output type.
raw.unsupported Raw results cannot be rendered in the selected output type.
output.closed Output is closed.
unknown.format Requested format is unknown.

Calling the API from Java

We have an open source implementation of a Java Client for our API, which is also available on mvncentral.

It is published here: https://github.com/SumoLogic/sumo-java-client

API Operations Reference

This section defines the functions and endpoints for the API.

Search

Executes a search on log data in the Sumo Logic service. The search query is formed as a standard HTTP query string, and is appended to the endpoint URL.

About time parameters: If you do not enter any time parameters, Sumo Logic executes the query with the default time range, which is the last 15 minutes before now. "Now" is, of course, whenever you run the query.

Parameter Required Default Description
q yes – The full search query to be executed.
from no -15m ISO 8601 date of the time range to start search in. Can also be milliseconds since epoch.
to no now ISO 8601 date of the time range to end search in. Can also be milliseconds since epoch.
tz no UTC Time zone used for absolute times/dates in from and to and time stamps in results.
format no json The desired result format. Supported: 'json' and 'text'. Text is not supported for aggregation queries.

Request example

If you need a quick method for escaping characters in your search query string, you can use this tool.

curl -u [email protected]:VeryTopSecret123 "https://api.sumologic.com/api/v1/logs/search?q=error&from=2012-04-04T13:01:02&to=2012-04-04T15:01:02"

Result example in JSON

Timestamps are in ISO8601 format.

[
{
    "_sourcecategory" : "collector_metrics_reporter",
    "_raw" : "2012-04-25 16:02:03,269 [metrics-log-reporter] INFO  com.sumologic.util.scala.MetricsReporter - com.sumologic.util.log.Log.error  (calls/m) count=1, fifteenMinuteRate=0.00, fiveMinuteRate=0.00, oneMinuteRate=0.00, meanRate=0.00",
    "_sourcehost" : "nite-config-1",
    "_receipttime" : 1335394925520,
    "_sourcename" : "/usr/sumo/collector-17.0-299/logs/metrics-reporter.log",
    "_messagetime" : 1335394923269
  },
  {
    "_sourcecategory" : "config_metrics_reporter",
    "_raw" : "2012-04-25 16:02:01,675 -0700 INFO  [hostId=nite-config-1] [module=config] [logger=util.scala.MetricsReporter] [thread=metrics-log-reporter] com.sumologic.util.log.Log.error  (calls/m) count=1, fifteenMinuteRate=0.00, fiveMinuteRate=0.00, oneMinuteRate=0.00, meanRate=0.00",
    "_sourcehost" : "nite-config-1",
    "_receipttime" : 1335394922523,
    "_sourcename" : "/usr/sumo/config-17.0-786/logs/metrics-reporter.log",
    "_messagetime" : 1335394921675
  },
  {
    "_sourcecategory" : "search",
    "_raw" : "2012-04-25 16:02:01,224 -0700 INFO  [hostId=nite-ftsearch-1] [module=SEARCH] [logger=scala.search.SearchQueryHandler] [thread=MTP-SearchQueryHandler-18] [auth=User:[email protected]:000000000000106D:0000000000001055:false] [session=1ED0366263EAEB94] [customer=0000000000001055] [call=InboundSearchProtocol.startSearch] [session_path=2C3BF127361E38A3] Started search with sessionId: 1ED0366263EAEB94, customerId: 4181, query: (error OR fail*) AND exception",
    "_sourcehost" : "nite-ftsearch-1",
    "_receipttime" : 1335394922043,
    "_sourcename" : "/usr/sumo/search-17.0-853/logs/search.log",
    "_messagetime" : 1335394921224
  },
  {
    "_sourcecategory" : "stream",
    "_raw" : "2012-04-25 16:02:01,218 -0700 INFO  [hostId=nite-ftsearch-1] [module=STREAM] [logger=stream.scala.delegates.SearchDelegate] [thread=flush-2C3BF127361E38A3] [auth=User:[email protected]:000000000000106D:0000000000001055:false] [call=InboundStreamProtocol.executeQuery] Calling search module with sessionId=1ED0366263EAEB94, customerId=4181, query=(error OR fail*) AND exception, timeRange=1335394020000 - 1335394920000",
    "_sourcehost" : "nite-ftsearch-1",
    "_receipttime" : 1335394922041,
    "_sourcename" : "/usr/sumo/stream-17.0-927/logs/stream.log",
    "_messagetime" : 1335394921218
  }
]
Clone this wiki locally