When you have a powerful near-real-time discovery and monitoring system like the Assimilation Suite, it’s essential to connect it into your existing processes, so that people can be notified when interesting events occur. One easy way to do that is using the Assimilation event API. With it, you can be notified when new IP or MAC addresses show up, when systems go up or down and a variety of other events.  In this post, we’ll walk through the API with emphasis on the things you need to know to note a service or server going up or down, and we point at a sample script for up/down email notification.

Basics of the Assimilation Event API

The Assimilation event API is very simple, and follows common UNIX system administration patterns. It’s simple: place an executable script or command in the directory /usr/share/assimilation/notification.d/, and then when an interesting event occurs, your script gets run. This is similar to a number of directories such as /etc/apm/event.d, /etc/sysctl.d, /etc/rc*.d.

For any given Assimilation event, there is a primary associated object, which is the corresponding graph node (object) to which the event has occurred. In addition there are other extrainfo attributes giving further details of the event. The event API creates an AssimEvent object which has the relevant information concerning the event in question. The main purpose of the Assimilation Event API is to pass this information along to its plugins in a convenient form.

What arguments are passed to Assimilation Event API plugins?

When a plugin is invoked, it always gets exactly two arguments. They are:

1. event type
2. graph node type

In most cases this is enough to let the plugin know if this is one of the kinds of events that is interested in. Here’s what these arguments mean.

Event Type

This indicates the type of event. At this writing, the types of events are:

• create – the associated object was created
• up – the associated object went into an “up” state
• down – the associated object went into a “down” state
• warn – the associated object had a warning added to it
• unwarn – the associated object had a warning removed from it
• update – the associated object was updated
• delete – the associated object was deleted

We don’t currently create any delete events. That’s coming. The 1.1.2 release started using warn and unwarn for best practice violations.

Graph Node Type

This indicates the type of the graph node which experienced the event. The types of graph nodes which have associated events are currently include the following:

• Drone – a system with our agent installed on it
• IPaddrNode – an IP address node
• MonitorAction – a monitoring action
• NICNode – a NIC / MAC address
• ProcessNode – a client or server process running on a Drone
• SystemNode – A system not running our agent – typically a switch or router
  

It’s worth noting that we will likely add new object types to our event API in the future.

What environment is passed to Assimilation Event API plugins?

Since the arguments are limited and simple, we provide the rest of the information through other mechanisms – the environment, and standard input. Most plugins only have to deal with the environment, making for a simple interface in any programming language. The question comes, of course, about exactly what’s passed in the environment. Since this is a very general mechanism, the first thing to explain is that the answer is necessarily very general. Let’s dive in!

The first thing to understand is that all the scalar (integer, string, boolean, etc) attributes of the associated object and “extra” information are passed – each in its own environment variable. The next thing to understand is that the attributes of the objects are prefixed with the string “ASSIM_” to avoid any conflicts with more normal environment variables. And finally, if there is a conflict between an “extra” attribute and an associated object attribute, the associated object wins out.

Let’s look in some detail at some of the major attributes for a Drone node.

• designation=servidor – This is the system name according to uname -n.
• monitors_activated=True – This indicates that we have activated the relevant monitoring agents since the system came up.
• nodetype=Drone – this is the same as argv[2]. Every graph node has a nodetype attribute.
• port=46215 – this is the port that the nanoprobe on this system is bound to
• reason=STARTUP packet – this indicates reason why it was marked up or down.
• status=up – meaning that it’s currently up.

As noted before, they come through as ASSIM_designation, ASSIM_nodetype, ASSIM_port and  so on. Each node type has its own set of attributes, and some attributes may only exist in certain circumstances.

Many of the event types don’t have extra information beyond the node they are associated with, but the MonitorAction up and down events associated with services going up and down bring a bit more information to the table. These additional attributes include:

• comment –  English text describing how this was observed, including details from monitoring agent.
• origaddr – IP address of the  machine performing the monitoring
• resourcename – name of the resource (from Assimilation’s perspective)

How do I get the full event JSON in the Assimilation Event API?

If you need non-scalar information, or if you’d just rather process the JSON than environment variables, the JSON representation of the AssimEvent object is available via standard input.

What else is there to know about the Assimilation Event API?

It’s really pretty simple, and a little experimentation will often be as fast as reading documents or source code. But there are a couple of things to note:

• We don’t care about your exit code. Success, failure, we don’t care. That’s your problem ;-).
• Event plugins are notified one at a time. This means if you’re doing something which might take a while, it’s best to spawn it off to a background process and don’t wait on it.

Why isn’t this Assimilation Event API a REST API?

It may eventually be provided through REST, but most system administrators are more comfortable with a fork/exec interface than a REST interface. If there’s demand for it, we can always add it to our REST interface. Feel free to submit a pull request with that capability ;-).

Are there any sample Assimilation Event API plugins?

I’m glad you asked! At the 2015 OSMC Hackathon we wrote a sample plugin which sends emails when systems or services go up or down. You can find a slightly more refined version of that plugin at https://github.com/assimilation/assimilation-official/blob/master/samples.d/event-exec.d/sendemail.sh

What are your questions about the Assimilation Event API

This is a basic overview of the Assimilation Event API – what questions does it bring to mind? What would you like to see us discuss in more detail?