Getting Your Feet Wet with the Logz.io API

Logz.io API

API access is available at the Enterprise tier of our product. With it, you can create a whole range of heavily customized use cases to further expand our suite of offerings. For example, you can hit our API to send customized query results to a third party service like Nagios, or you can automate the creation and deletion of sub-accounts. 

To help introduce you to our API before you start your next project, we’re going to work through a short use case where we create a sub-account, send it data, and search the data.

Getting set up with the API

An important note before we continue: You need to be an account admin to create API tokens or request API access.

If you want to use the Logz.io API, you’ll need to be on an Enterprise account. If you’re not on an Enterprise account, no worries! You can sign up for a free 14-day trial, but you’ll need to ask for API access. To make the request, just email help@logz.io, or click the blue chat button in the lower right corner of this page.

Don’t worry too much if you’re not a coding expert. The examples we’re outlining in this article can be easily run from the command line using cURL or from an API tool like Postman. For this article, we’ll use Postman because it’s easy to use.

We may be a little biased, but we also think our API docs will be your best friend as you work through this article. You can visit the API docs at https://docs.logz.io/api/.

Postman: A crash course

First things first—if you don’t have Postman, go ahead and download it. You can sign up for a free account if you don’t already have one.

Postman is easy to work with once you get the hang of it. The basic things you need to know are here:

Postman

  1. Collections: Create new collections (or folders) to hold your API requests.
  2. Environments: We’re using more than one Logz.io account, so we’ll assign each account to an environment in Postman. Each environment is a discrete set of variables.
  3. Request: You’ll use the set of controls at the top of the tab to construct your request—the HTTP method, the request URL (including any path parameters), and the header and body.

  4. Response: When you click the blue Send button, you’ll execute an honest-to-goodness, real API request. The response from the server shows up in the bottom of the tab. This includes the HTTP status, response time and size, and the response itself (the header and body).

Making your first API token

Sign in to your main account as an admin, and then go to the API Tokens page.

main account

access

From there, type the name of a new API token at the bottom of the table and click Save. For this example, we’ll use “API practice token”.

API tokens

Simple as that.

One more thing: See the x all the way to the right of the API token? Use that to delete a token if you’re done using it or you think it’s been compromised in some way. There’s no limit to the number of API tokens you can create. We recommend getting in the daily or weekly habit of removing all API tokens that aren’t in use.

Okay, now let’s put our practice token in Postman and make a test call.

Testing 1, 2, 3… is this thing on?

Now we’ll assign our token an environment variable in Postman. First, we’ll click (top right corner of the app) to show the Manage Environments dialog box and click Add. This brings up the Add Environment dialog box. In the text box at the top, name this environment “Logzio main account”.

Manage Environments

In the first row, type “token” In the Variable column and paste your API token in the Initial Value column.

In the next row, type “url” in the Variable column. We’ll set this variable as your Logz.io region’s API URL. To find your region, sign into Logz.io and look at the app URL—you’ll see either app.logz.io (US region) or app-eu.logz.io (EU region). For the US region, you’ll set Initial Value to https://api.logz.io/v1. For the EU region, you’ll set Initial Value to https://api-eu.logz.io/v1.

Click Add when you’re done. You’ll see your new environment in the Manage Environments list. Click X in the top right corner to return to the main Postman screen.

Logz.io Main Account

Your new environment is in the Manage Environments list. Click the X in the top right corner to return to the main Postman screen.

Select Logz.io main account from the Environments list (top right corner).

no environment

Then, in the main area of the window, make this magic happen:

  • Set the method to GET
  • Set the request URL to {{url}}/account-management/whoami

Now click the Headers tab. All Logz.io API requests contain at least X-API-TOKEN and Content-Type in the header, so we’ll add reusable header presets to Postman.

To do this, select Presets > Manage Presets, click Add, and then click Bulk Edit (on the right of the dialog box).

Set the Header Preset Name to “Logzio header”, and then paste this code:

X-API-TOKEN:{{token}}
Content-Type:application/json

Click Add, and then return to the main Postman window. Now you can add your header presets by clicking Presets > Logzio header.

who am i

In the Headers tab, set X-API-TOKEN to {{token}} and set Content-Type to application/json.

That’ll do it for this request. Click Send and watch the body area of the window. You should see a response come back with the account name.

apache

And just like that, you sent your first Logz.io API request. Well done!

If you don’t see something like this response, double-check your API token, account region, and request URL.

Creating a sub account

Now we’ll use the API token from your main account to create a new sub-account. Before we go any further with this, make sure you know your plan’s capacity limits (total daily GB). Logz.io sub-accounts can take parts of your plan’s capacity, but the total capacity in your main account and sub-accounts can’t exceed your plan’s limit.

With that out of the way, let’s make a new request in Postman:

  • Set the method to POST
  • Set the request URL to {{url}}/account-management/time-based-accounts

In the Headers tab, click Presets > Logzio header.

And in the Body tab, click raw, and paste this code:

{
    "email": "your@email.com",
    "accountName": "API test",
    "retentionDays": 1,
    "maxDailyGB": 1,
    "accessible": false
}

The email address you send with this request has to belong to an existing user, so use the email address from your own Logz.io email account.

You’ll get a response back with the account ID and account token.

account id

Copy accountToken so you can use it later on.

Searching an account’s logs

Hopefully, now you see that the API isn’t too difficult to get acquainted with. Now we’ll try something a little more complicated—searching your Logz.io data using Lucene, the querying language used in Kibana.

Upload the sample data

First, we’ll need some sample data. It just so happens that Logz.io regularly uploads sample Apache logs to Amazon S3. This command will download the sample Apache logs and ship them to your Logz.io account.

curl https://logzio-elk.s3.amazonaws.com/apache-daily-access.log
 --output apache-daily-access.log && curl -T apache-daily-access.log 
https://listener.logz.io:8022/file_upload/<ACCOUNT-TOKEN>/apache-access

Just a couple things that you need to do before you ship:

  • Replace <ACCOUNT-TOKEN> with your new sub-account token (the one you copied from Postman when you made the new sub-account)
  • If your account is in the EU region, then change the url to https://listener-eu.logz.io. Otherwise, leave the URL as it is.

Add your sub-account token to Postman

Just to make sure you really get Postman and API calls, let’s run one more request.

First, you’ll need to log in to Logz.io and make a new API token for your sub-account.

Then, in Postman, you’ll need to make a new environment, which we’ll call “Logzio sub account”. Give this environment the same two variables that we used in the last environment (“token” and “url”). Set “token” to an API token from the sub-account, and set “url” to your region’s API URL (either https://api.logz.io/v1 or https://api-eu.logz.io/v1).

Send the search request

Can you see the finish line? You’re almost there!

Open a new tab in Postman, and make it a POST request. In the request URL box, type {{url}}/search.

Add the usual Headers by clicking Presets > Logzio header.

Now click Body, and then click raw. We’ll run a really simple query here—let’s search for anything that came from Europe:

{ "query": { "bool": { "must": [ { "query_string": { "query": 
"geoip.continent_code:EU" } } ] } } }

If your sample logs didn’t return any results, try searching for requests that came from North America:

{ "query": { "bool": { "must": [ { "query_string": { "query": 
"geoip.continent_code:NA" } } ] } } }

You can get there from here!

Even though Logz.io integrates with a bunch of software and services, we can’t possibly answer every need. That’s why we made the Logz.io API—so you can make Logz.io work with your tools and workflows.

We get it—the Logz.io API can be overwhelming at first. We’re hoping you learned enough of the basics in this article to get started.

So where do you go from here?

We’d definitely encourage you to visit the Logz.io API Docs. You’ll find everything you need there, including the API endpoints we covered in this post (managing sub-accounts and searching logs).

And while you’re there, we’d love to hear from you! Feel free to suggest updates and improvements. We’re also working hard on an API cookbook, so if you have a use case you’d like us to write about, let us know! You can open a ticket at our Docs GitHub repo or leave us a message at help@logz.io.

Monitor, troubleshoot, and secure your environment with one unified platform.
Artboard Created with Sketch.
×

Turn machine data into actionable insights with ELK as a Service

By submitting this form, you are accepting our Terms of Use and our Privacy Policy

×

DevOps News and Tips to your inbox

We write about DevOps. Log Analytics, Elasticsearch and much more!

By submitting this form, you are accepting our Terms of Use and our Privacy Policy