Docs

Integrations

While Outlyer makes the process of configuring your monitoring super simple, we take it one step further by providing a collection of out-of-box integrations for all the common services. With integrations, you’re only a one click away from comprehensive monitoring of your favourite service. All our integrations are open-source and actively maintained.

These integrations are fantastic, but how do I create my own?

Monitoring of-the-shelf services is great, but really you want to monitor the state of your custom services.

Making custom monitoring simple is one of the core ideas behind Outlyer, so of course, we support creating your own integrations.

Nobody likes repeating the same task, so we allow you to define your monitoring configuration, describe what it does, then wrap it up in a custom integration. Then next time you need to deploy monitoring for that type of service, just install your Integration and done.

That sounds like a lot of work?

Most of the work has really already been done by building all your Checks, Plugins and Dashboards. Wrapping on all these components in an integration just required three steps:

  1. Organise the components into the required folder layout
  2. Create a package.yaml descriptor file
  3. Lastly, create a README.md file detailing what your integration does

Folder layout

All integrations should follow our consistent folder structure. An integration consists on a folder (with the name of your integration), and a set of subfolders for each on the different component types within your integration.

Okay, so what does that look like?

integration_name/
├── alerts/
├── checks/
├── dashboards/
├── plugins/
├── resources/
├── package.yaml
├── README.md
  • integration_name/: This is the root folder of your Integration. You will need to keep this name unique so it doesn’t conflict with any other Integrations in Outlyer.
  • alerts/: The alerts folder contains all the alert YAML definitions that should be installed with the integration.
  • dashboards/: The dashboards folder contains all the dashboard YAML definitions that should be installed with the integration.
  • plugins/: The plugins folder contains all the plugins that should be installed with the integration in their original file format.
  • resources/: The resources folder contains any additional resources such as images and icons. Generally an SVG icon for the integration is put here, and any images for the README.md that need to be included.
  • package.yaml: This is your integration descriptor file, its used for specifying the details of your integration, such as author, license and version.
  • README.md: Obviously, this file is used to provide a description of your Integration, as well as other important information like: metrics collected, installation instructions and a change-log.

package.yaml

The package.yaml is used by Outlyer to read metadata about the Integration such as title, short description, icon, version etc. The file contain the following fields:

title: My Awesome Integration
description: A short description of my awesome integration
icon: 
	url: https://image.host.com/awesome.svg
author:
	name: Outlyer
	url: https://www.outlyer.com
version: 1.0.1
license: MIT
labels:
  awesome:v1
  type:system

All fields are required and help Outlyer import the Integration into the application so it can easily be searchable and displayed on the Integrations page in Outlyer.

README.md

The README.md is written in standard markdown, but uses some custom section breaks to ensure that long read me files are broken up into tabs inside the Outlyer UI. Below is an example README.md file:

My Awesome Integration
======================

== Description ==

In this section you can put a longer desciption. Think of it as the front page of your Integration when 
a user opens the Integration in Outlyer to tell users what the integration is for and what it does. 
You may also want to provide some knowlege around the service the Integration monitors so users can 
understand what it being monitored.

You can also include images from the web or the resources folder. ![alt text](screenshot.png) will load an 
image called screenshot.png stored under the reousrces folder for the pack. This allows you to include 
useful images to help show users what the Integration can do.

== Metrics Collected ==

This section includes a markdown table of all the metrics collected so a user can easily see what 
metrics are being collected by any plugins in the Integration, along with labels, units and what 
the metrics actually mean.

Although this section is free form, it is generally recommended that metrics are listed with the 
following information, and any additional columns that make sense can be added. For example our 
Java integrations have an additional column to list the MBean query the metric is being collected from:


| Metric Name     |Type   |Labels          |Unit |Description                              |
|-----------------|-------|----------------|-----|-----------------------------------------|
|my.metric_gauge  |Gauge  |function, region|Count|Metric description of what its monitoring|
|my.metric_counter|Counter|function, region|Count|Metric description of what its monitoring|

== Installation ==

A lot of integrations will provide plugin varables to configure the checks fo different services, 
and will also need some setup on the service itself to enable the service to be monitored 
(for example enabling JMX on Kafka). The plugin variables should be listed in a table like below:

|Variable  |Default   |Description                                           |
|----------|----------|------------------------------------------------------|
|port      |1567      |Port running management plugin APIs                   |
|protocol  |http      |HTTP Protocol, either http or https                   |

== Changelog ==

This is simply a table like below that can be updated so users who see a newer version of an 
existing Integration they've installed can get a summary of the changes in the new version:

|Version|Release Date|Description                                         |
|-------|------------|----------------------------------------------------|
|1.0    |22-May-2018 |Initial version of our lambda monitoring integration|

As you can see above, the README.md file uses custom section breaks so that the Outlyer UI can display each section separately for easy reading. Additional sections may be added in future to ensure all integrations have all the information about them easily accessible to users.

Integration Forms

Wait a minute, some of my integration properties won’t be known until install time!

Don’t worry, we haven’t forgotten this. Integrations should be designed as generic bundles of monitoring configuration; A MongoDB integration should work regardless of how you’ve deployed MongoDB.

To facilitate collecting install-time configuration, you just specify the information you need and we will take care of collecting it.

Awesome, how do I do it?

You start by adding a new Form section to your package.yaml, then in this section add an entry for each property need the installing user to supply. Let me show you how:

title: My Awesome Integration
description: A short description of my awesome integration
icon: 
  url: https://image.host.com/awesome.svg
author:
  name: Outlyer
  url: https://www.outlyer.com
version: 1.0.1
license: MIT
labels:
  awesome:v1
  type:system
form:
- name: name
  description: Enter a name for your check
  prompt: Check name?
  type: string
  required: True
- name: selectors
  description: Specify a selector for the Hosts you would like to monitor with this check
  prompt: Select hosts to monitor
  type: labelSelectors
  default:
    - "role=web"

So what have we got here?

For each of our fields we are configuring the following attributes:

  • name (string): As you would expect, this is the name of the field we want to collect. This name is used when we reference the field (more on this to follow), so ensure each one is unique
  • description (string): Here you will give a more verbose description of what your field is for. This will be available to the user when we are prompting them for this field
  • prompt (string): Here you will specify the exact question/prompt to be displayed to the installing user.
  • type (string): The value type for this field. The can be string, int, float, date and labelSelector.
  • default (optional list of strings): A default value to be used for this field
  • required (optional boolean): Whether the user is required to complete this field.

Whats a labelSector type?

A labelSelector is a special type used for selecting hosts from their labels. A very common use case for is specifying the host you would like a check to run against.

How do I use the form properties

Well, all of those YAML files (except for package.yaml) you have created for your integration are actually templates. The templates support the injection of template variables using the following format {{.my_var}} (no, apparently the full-stop is not a mistake). This might sound complicated, but it’s really quite simple. Suppose your integration has a Check. As part of that check you need to supply a Selector to indicate which hosts should run this check. With a regular Check YAML file you would include something like selectors: [‘role=mongodb, env=prod’], but in our case we want the installing user to specify which hosts should run the check. All we need to do instead is set selectors: {{.selectors}}, where selectors is then name of the form field we previously specified.

Thats it we’re done. You can now specify dynamic fields to be collected and set at time of installation