Reading and Writing Text-Based Events with the Netuitive API

From Ansible to Windows (and nearly everything in between) Netuitive has an impressively large library of third-party platform integrations. As far as system monitoring tools go, this level of integration is crucial to establishing ubiquity within any application environment. But what do you do if you have to monitor uncommon or proprietary platforms that nobody integrates with? To accommodate this need, Netuitive has created a public API for reading and writing custom metrics data from any Internet-connected platform. To illustrate how flexible the Netuitive API is, let’s take a look at logging data from a legacy application that doesn’t utilize any modern logging conventions, and is written in a language Netuitive doesn’t have an agent for.

If you’ve ever read any of my other articles, there’s a good chance that you know how much of a fan I am of multi-user dungeons. For the uninitiated, multi-user dungeons (or MUDs for short) are the text-based, online role-playing games that predate today’s modern MMORPGs like World of Warcraft. What makes MUDs so fascinating to this day is that many of the original codebases are still available to download and run, given enough patience.

My personal favorite MUD codebase, called DikuMUD, was originally released to the public in 1991. Written in ISO C and released long before things like REST, SSH, and even the World Wide Web were invented, DikuMUD is a perfect candidate to integrate a modern monitoring solution like Netuitive.

Getting Started with the Netuitive API

So, how exactly do we plug a 21st century API into a 20th century codebase?

Before we consume Netuitive’s API, we first need to gather some necessary authentication information. Netuitive’s API uses HTTP Basic Authentication, so the first two things we need to gather are our username and password (this should be pretty self explanatory). Next, we need to get an API key. To do this, head on over to Netuitive’s Integrations page and click on the “Custom Datasource” integration and take note of the “API Key” field. It is important to note that the “Data Collection” field should be enabled as well.

Making The Call

Now that we have the proper authentication information, let’s compose a basic API call to better understand the format and process that is required to communicate with it. I should note that, for the sake of this article, we will only be consuming the event creation API endpoint, but there are several other endpoints listed in Netuitive’s API documentation that can be taken advantage of as well.

To test API calls, I’m a big fan of Postman, a cross-platform application that can be used to manually compose and make calls to any RESTful API. Making a request to Netuitive’s event creation API endpoint requires a few things in addition to the information gathered above: a URL, a custom request header, and a JSON representation of the event.

[Editor’s Note: Netuitive uses Swagger, an alternative to Postman, to document our API. Swagger can also be used to manually compose and make API calls.]

First, the endpoint’s URL takes the following format, replacing API_KEY with the API key copied above:

Netuitive API: Postman Endpoint

Next, we need to add our login credentials to the Authorization tab:

Netuitive API: Postman Authentication

Then, we need to create a JSON string representing the event we are posting to the API. While there are a few choices listed in Netuitive’s documentation, the majority of them are optional. That said, some of the optional fields provide some great value, so we will be including them where appropriate.

So, what do all of these values mean?

While title and message are pretty self-explanatory, the others may not be.

First up is type. This field is required, and according to the Netuitive documentation, must be set to INFO. While in this request, level is also set to INFO, it is an optional field that can be set to either INFO, WARNING, or CRITICAL, to indicate the severity of the event in question.

The elementId field is a text field that should be consistent across all request to identify the element that is making the API calls. In the case of our example, since we are using Postbox, I chose to simply put Postbox here. This will allow us to look at requests made from only the Postbox element.

One important thing to be aware of is that, while Netuitive’s event API endpoint does accept a timestamp parameter, it can be omitted and Netuitive will automatically assign it to the current timestamp. This automatic timestamp generation will only happen if the following custom header is added to the request:

X-Netuitive-Api-Options: INJECT_TIMESTAMP

Netuitive API: Postman Headers

If that header is not found, then the event will not show up in your Netuitive dashboard.

Now that we’ve put our test request together, let’s run it and take a peek at what shows up on the Netuitive dashboard:

Netuitive API: Posted Netuitive Event

Success! As you can see, all the information we provided in our JSON object is available in the event details, and the timestamp has been auto-generated.

Putting It All Together

Now that we know how to make API calls to the Netuitive API, how do we go about doing this from our legacy codebase?

While accomplishing this task in ISO C requires both the libjansson and libcurl libraries, installing and configuring both of them can become complicated enough to justify their own articles. That said, the pkg-config command can be used to simplify the process of generating the appropriate compilation flags. To do this, I added the following compiler command to the project’s Makefile:

`pkg-config –cflags –libs jansson libcurl`

With the proper libraries installed and the Makefile updated, we can now make our API calls. While the code to handle this isn’t entirely insignificant, there are two primary functions to be aware of. The first method to take note of is called curl_json_push. This function is what will actually send our JSON payload to the Netuitive API:

The next method to be aware of is log_event, which is what we will call to compose our JSON payload:

These two methods make up the bulk of the code necessary to send requests to the Netuitive API in ISO C. Additionally, some configuration settings can be found in the proper header file, allowing us to change the login credentials, API key, and even the element. To illustrate their use, let’s add a call to the log_event method where players log in to the game:

sprintf(log_buf,”%s!%s@%s has connected.”, ch->name, d->user, d->host);
log_event(“Player login”, NETUITIVE_LEVEL_INFO, log_buf);

This call composes a request to the Netuitive API with “Player login” as the title, “INFO” as the level, and the player’s username and hostname in the description. Taking a look at the Netuitive dashboard, we can see the event that gets posted whenever a player logs into the game:

Netuitive API: Posted Netuitive Event

Next Steps

While this article only covers a fairly simplistic use of the Netuitive API, it does a good job of illustrating its flexibility. RESTful APIs have the advantage of being able to be consumed by nearly any Internet-connected service, as HTTP is a platform-agnostic protocol. This means that, regardless of Netuitive’s own proprietary integrations, everything from Internet-of-Things devices to brand new programming languages have the opportunity to send and receive data using Netuitive’s API.


Zachary Flower (@zachflower) is a freelance web developer, writer, and polymath. He has an eye for simplicity and usability, and strives to build products with both the end user and business goals in mind. From building projects for the NSA to creating features for companies like Name.com and Buffer, Zach has always taken a strong stand against needlessly reinventing the wheel, often advocating for the use of well established third-party and open source services and solutions to improve the efficiency and reliability of a development project.

capterra

Join other DevOps who love Metricly!

Sign up for a free, fully featured, 21-day trial. No credit card required!