We take an API-first approach to our product at Sumo Logic—everything you can do in the UI can be done via API. I talked about several use cases for automation with Sumo Logic APIs in my presentation at Illuminate 2020. Here’s a recap of what I covered.
Why automate with the Sumo Logic API?
Typically, automating via API is done for three reasons: cost savings, time savings, and accuracy and consistency.
Sumo Logic end users use APIs to automate repetitive tasks to save time, and, in the process, save costs. Sumo Logic partners also use APIs to create repeatable processes for tasks like provisioning new customer accounts or a combination of different tasks. Of course, regardless of your goals, automating everything is not probably a good idea—there are some things that are better as one-offs.
Automation in Sumo Logic
A popular question we get is whether the deployment of the installed collector component in Sumo Logic can be automated. Installed collectors cannot be deployed through the API directly, just their sources. The installed collector actually has to already be in place for the API to configure an installed collector. So, the actual installation of installed collectors needs to be done externally to the Sumo Logic Product.
You must use an external tool if you wish to automatically deploy installed collectors.
Examples of automated deployment methods:
Once you have your Installed Collector deployed, you can use the API to configure the sources that you want that collector to actually collect.
Getting started with Sumo Logic APIs
In order to automate with Sumo Logic APIs, you need an API key and secret. You also must know the API endpoint for your account. If you intend to use the API to perform administrative tasks in Sumo Logic, you should make sure that your API key is generated by a user with admin rights.
How to create an API Access Key and Secret
The API Access Key and Secret are randomly generated in Sumo Logic just like any other cloud service. Within the Sumo Logic UI, open Preferences and choose Add Access Key.
Name the key and the UI will generate the Access Key and Secret. This will only be shown once so make sure you copy and save the values in a safe place. You will use this to authenticate into the Sumo Logic API.
How to identify the API Endpoint
You’re going to need to connect to the API Endpoint URL to perform API tasks.
To get the API Endpoint URL, go into the Sumo Logic UI and take a look at the URL in the address bar. A part of the URL will give you a hint of which Sumo Logic instance you’re connected to based on your region (e.g. US1, US2, CA, EU). Look up the corresponding API Endpoint URL in this doc.
Now that you have the credentials, the next step is identifying how you want to talk to the API.
How to talk to the API: Multiple mechanisms to leverage Sumo Logic APIs
There are two general categories: direct REST Access and through third party tools.
Direct REST Access is basically calling the REST API directly over HTTPS. There’s a variety of APIs available for you to access through REST like the Search Job API which you can use to run Sumo Logic searches, and collector and source APIs for configuring collectors and sources–I’ll tell you more about these use cases in a later section.
Direct API access requires a lot of technical acumen so there’s potentially a lot of steps for this option. To ease that, we have a variety of SDKs created by the community. Some are more complete than others but they are all available on GitHub.
Accessing APIs can also be done through third party tools.
-
Sumo Logic Cmdlets was created by one of our sales engineers. This provides shell-level commands–command-line executables that can pull data directly out of the Sumo Logic API.
-
Sumotoolbox is a GUI interface I developed for performing some common tasks from a UI instead of from within a script.
Sumotoolbox is good for those who prefer not to write scripts for simpler tasks.
If you want to create repeatable, full end-to-end automation, Direct REST Access and Cmdlets and Terraform are better options.
Use cases for Sumo Logic API automation
Generally, the use cases for Sumo Logic API automation fall into three categories: provisioning, management, and search.
Provisioning–for tasks like replicating content across multiple orgs, and provisioning sources to a set of collectors. Management–for tasks like mass update of content, and deleting a set of collectors based on status and/or name. And finally, search– you can run any Sumo Logic query and return results through the API instead of the UI.
Here are some example use cases I presented at the conference. I suggest that users get a basic familiarity for JSON because this is the standard method for transferring data between REST APIs. These examples–except for the one on Sumotoolbox–are in Python and use the Python Sumo Logic SDK I developed. You can access all these samples on Github through this link.
I created these scripts for the purposes of Illuminate so please be careful as they’re not heavily tested. These are open source tools that are not officially supported by Sumo Logic, but you can leverage to get started with in automating with APIs.
Use case: Create source
Remember that you have to have your installed collector defined. The source we’re creating in this use case is a local file source.
Use case: Delete dead collectors by name
This use case is for when you want to delete all deprovisioned endpoints that all start with the same substring.
In this use case, I used the instantiated endpoint sumo_org to do a get_collectors_sync. get_collectors is a call that can pass a limited number of results back, up to a thousand collectors. It’s a paging system so you can make multiple calls.
With get_collectors_sync, I’ve implemented synchronous calls that do that sort of looping for you so you won’t have to implement your own algorithm for retrieving pages and pages of collectors. Technically, our API is asynchronous for a lot of these get calls.
Use case: Copy sources to multiple collectors
I presented this last sample use case using Sumotoolbox which I created for day 1/day 2 type tasks. With this GUI, rather than writing a script, you can click and highlight on your collectors and sources, copy them from place to place, manipulate them, delete them, and so on. There are other use cases using this UI tool, but for my presentation, I used Sumotoolbox to copy sources to multiple collectors.
Hopefully this recap of my presentation gave you an idea of how to access Sumo Logic APIs, and how you can use API automation to save time and enhance your Sumo Logic experience.
