Sumo Logic Search Job API
-
Upload
sumo-logic -
Category
Software
-
view
80 -
download
0
Transcript of Sumo Logic Search Job API
Sumo Logic Confidential
Sumo Logic Search Job API
Sumo Logic Confidential
Available APIs
Performing SearchesManaging Collectors
Sumo Logic Confidential
General API Details• Authentication
– Initial request MUST include a HTTP Basic Authentication header using an 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.
Sumo Logic Confidential
• API requests are limited to 4 calls per second, 240 requests per minute
• 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.eu.sumologic.com https://api.eu.sumologic.com/api/v1/https://service.au.sumologic.com https://api.au.sumologic.com/api/v1/
Sumo Logic Confidential
• 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
Sumo Logic Confidential
• 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
Search Job API
Sumo Logic Confidential
• 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 rangeto String Yes End of the time rangetimezone String Yes Time Zone format in TX format
Sumo Logic Confidential
• Status Codes
• Response Headers
• Sample JSON Response Document
Search Job API - Creating a Search Job
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
Sumo Logic Confidential
• 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
Search Job API - Creating a Search Job
Sumo Logic Confidential
• Endpoint: /search/jobs/SEARCH_JOB_ID
• Method: GET
Search Job API - Checking the Status of a Search JobSumo Logic Confidential
10
Parameter Type
Required
Description
SEARCH_JOB_ID
String Yes The ID of the search job.
Sumo Logic Confidential
• Sample JSON Response Document
• Possible States
Search Job API - Checking the Status of a Search Job
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.
Sumo Logic Confidential
• 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.
Search Job API - Checking the Status of a Search Job
Sumo Logic Confidential
• 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 Through Messages
Parameter Required
Description
SEARCH_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.
Sumo Logic Confidential
• Sample JSON Response Document
• 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 Through Messages
Sumo Logic Confidential
• 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 Through 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.
Sumo Logic Confidential
• Sample JSON Response Document
• 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 Through Records
Sumo Logic Confidential
• 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
Sumo Logic Confidential
Search Job API
Demo
Sumo Logic Confidential
• 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
Sumo Logic Confidential
• Documentation– https://help.sumologic.com/APIs/02Search_Job_API/
About_the_Search_Job_API
• Email– [email protected]
API Resources