How To Webinar - Sumo Logic API

Sumo Logic Confidential

Sumo Logic APIWelcome.

You are currently in listen-only mode.

To give everyone a chance to successfully connect, we’ll start at

10:05 AM Pacific.

How-To Webinar

Frank Reno, Customer SuccessMarch 2016


Available APIs

Performing Searches

Managing Collectors

Interacting with Dashboards (Beta)


General API Details

• Authentication– Initial request MUST include a HTTP Basic Authentication header using a

username/password or access id/access key

– API Authentications are limited to 15 calls per minute

– Multiple requests should use cookies• The initial request will return a cookie containing two attributes: JSESSIONID and

AWSELB. These can be included in subsequent requests to reduce the number of authentication calls.


• API requests are limited to 4 calls per second• Data Formats

– All data is sent and received in JSON• API URL

– Depends on your service region:

General API Details

Service URL API URLhttps://service.sumologic.com https://api.sumologic.com/api/v1/https://service.us2.sumologic.com https://api.us2.sumologic.com/api/v1/

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

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

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


• Errors– Errors are returned with an HTTP status code and JSON document.

– General Error Codes• auth.failed – The authentication has failed• internal.error – Internal server error• unauthorized – Incorrect username/password• service.unavailable – The service is unavailable

General API Details


• Ideal for fast, non-trivial queries

• Synchronous

• Limitations– Search must complete within 1 minute or it will timeout– A max of about 100K results will be returned. If you need more results, you will

need to execute subsequent requests with smaller time rages or use the Search Job API.

Search API


• Endpoint: /logs/search• Method: GET

*Time range values can be specified in ISO 8601 format or epoch milliseconds.

• https://api.sumologic.com/api/v1/logs/search?q=error&from=2012-04-04T13:01:02&to=2012-04-04T15:01:02

Search API

Parameter Required Default Description

q Yes N/A The full search query to be executed.

from No -15m Start of the time range.

to No Now End of the time range.

tz No Etc/UTC Time Zone format in TX format

format No json The desired result format. Supported: json and text.


• Sample JSON Response Document

Search API


Note:• This API may be deprecated in the future, in favor of the Search Job API. • Use the Search Job API where you can.

Search API


• Models the asynchronous behavior of a search in the Sumo Logic backend– Creating a search job returns immediately with the ID for the search job. The ID

can then be used to interact with the search job.

• Provides histogram bucket information

• Asynchronous

• Limitations – The Search Job API does not have the limitations that the Search API has.

Search Job API


• Endpoint: /search/jobs• Method: POST• Headers

– Content-Type - application/json– Accept - application/json

*Time range values can be specified in ISO 8601 format or epoch milliseconds.

Search Job API - Creating a Search Job

Parameter Type Required Description

query String Yes The full search query to be executed.

from String Yes Start of the time range

to String Yes End of the time range

timezone String Yes Time Zone format in TX format


• Status Codes

• Response Headers



Status Code Text Description202 Accepted The search job has been successfully created.

415 Unsupported Media Type Content-Type wasn't set to application/json.

400 Bad Request Generic request error by the client.

Header ValueLocation https://api.sumologic.com/api/v1/search/jobs/SEARCH_JOB_ID


• Common Error Reasons– Query is not specified– Query is invalid– From/to parameters are not specified– To is before from time– From/to values invalid format– Time zone parameter missing

• If any of the above occur, the response body will contain additional information.

• Don’t forget to properly escape your query



• Endpoint: /search/jobs/SEARCH_JOB_ID

• Method: GET

Search Job API - Checking the status of a Search Job

Sumo Logic Confidential14

Parameter Type Required DescriptionSEARCH_JOB_ID String Yes The ID of the search job.



• Possible States


State DescriptionNOT STARTED Search job has not been started yet.

GATHERING RESULTS Search job is still gathering more results, however results might already be available.

DONE GATHERING RESULTS Search job is done gathering results; the entire specified time range has been covered.

CANCELLED The search job has been cancelled.


• messageCount – The count of raw log messages

• recordCount– The count of aggregates

• If your search does not contain any aggregation operators, only the messageCount is returned.

• pendingErrors, pendingWarnings and histogramBuckets ARE NOT cumulative– Each request will return the information found since the last request. The client will

need to store these if they must be remembered.



• Endpoint: /search/jobs/SEARCH_JOB_ID/messages?offset=OFFSET&limit=LIMIT

• Method: GET

*The maximum value for limit is 10,000 messages

Search Job API - Paging thru messages

Parameter Required DescriptionSEARCH_JOB_ID Yes The ID of the search job.

OFFSET Yes Return messages starting at this offset.

LIMIT Yes The number of messages starting at offset to return.



• The result will contain two lists– Fields is all the fields defined for the messages– Messages contains a list of maps, one map for each message

Search Job API - Paging thru messages


• Endpoint: /search/jobs/SEARCH_JOB_ID/records?offset=OFFSET&limit=LIMIT

• Method: GET

*The maximum value for limit is 10,000 messages

Search Job API - Paging thru records

Parameter Required DescriptionSEARCH_JOB_ID Yes The ID of the search job.

OFFSET Yes Return records starting at this offset.

LIMIT Yes The number of records starting at offset to return.



• The result will contain two lists– Fields is all the fields defined for the records– Records contains a list of maps, one map for each records

Search Job API - Paging thru records


• Endpoint:/search/jobs/SEARCH_JOB_ID

• Method: DELETE

• Although search jobs ultimately timeout, it is best practice to delete a search job when it is no longer needed.

Search Job API - Deleting a Search Job


Search Job API

Demo


• Java Client Library– Available on Maven Central

– https://github.com/SumoLogic/sumo-java-client

• Python Client Library– https://github.com/SumoLogic/sumologic-python-sdk

Search Libraries


• Documentation– https://github.com/SumoLogic/sumo-api-doc/wiki– https://support.sumologic.com/hc/en-us/sections/200934938-APIs

• Community Forum– https://support.sumologic.com/hc/communities/public/topics/200263058-

Sumo-Logic-API

• Email– [email protected]

API Resources

Software

How To Webinar - Sumo Logic API