Outlyer provides a simple but powerful way to install integrations into accounts via Integration Packs. The Pack format described below allows users to bundle all the plugins, dashboards, alerts and other resources required to monitor an Integration that can be installed into an Outlyer account in one click.
Outlyer already provides many supported integrations out of the box for common services which are available publicly under our Integrations repo on Github. However users can easily contribute improvements to existing integrations or add additional integrations via pull requests to the repo, and also build private Integration packs for their own organisation that can be applied easily to their account.
This doc describes how Integration Packs are organised and work so users can easily contribute and create private Integration packs for their own account.
An Integration pack is essentially a folder with subfolders for each of the different resources included in the integration with the associated configuration files, readme, and plugins.
When an Integration pack is installed into your account, you can generally think of it as a merge to add all the resources to your account so they can be used to easily monitor the intended services.
The folder layout is as follows:
integration_name/ ├── alerts/ ├── dashboards/ ├── plugins/ ├── resources/ ├── tests/ ├── package.yaml ├── README.md
- integration_name/: This is the root folder of the Integration pack and should be named uniquely for that Integration so it doesn’t conflict with another Integration 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 logos. Generally an SVG logo for the integration is put here, and any images for the README.md that need to be included.
- tests/: Any unit tests required for your plugins should go under this folder if needed
- package.yaml: This is the Integration Pack definition with general information about the Integration such as author, license and verion.
- README.md: This is a general readme for the Integration pack which provides a description, metrics collected, installation instructions and changelog.
All folders are optional, as long as the package.yaml and README.md are available under the root folder, an Integration will be available in Outlyer’s Integrations page. This may be useful for Integrations that only include dashboards such as our own Docker integration which essentially uses the agent’s core container metrics to display a Dashboard of them, and no additional plugins are required.
The package.yaml is used by Outlyer to read metadata about the Integration pack such as title, short description, logo, version etc. which are displayed on the Integrations page when installed. The general structure is defined below:
title: My Awesome Integration description: A short description of my awesome integration logo: awesome.svg author: Outlyer author-uri: https://www.outlyer.com version: 1.0.1 license: MIT categories: - system - databases - aws
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 of the web UI. The logo filename will be relative to the resources folder under the root folder.
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 pack 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 seperately for easy reading. Additional sections may be added in future to ensure all integrations have all the information about them easily accessible to users.