Creating a Humio Package

This page will teach you how to author, install and maintain custom Humio packages. A package is a bundle of assets that can be installed in a Humio repository. They allow you to make assets reusable across multiple teams, repositories and even share your work with the Humio community.

In this guide we will assume you are working against your personal sandbox repository. This means you will always have the required permissions to manage packages. If you are not working against sandbox you may encounter errors due to lacking permissions. Make sure you have “Integrations > Change Packages” permission for the repository. You can read more about permissions under Role Based Authorization

Preparation

Throughout this guide we will be using the Humio CLI to perform a lot of the tasks related to authoring a package.

These tasks can also be performed using the Humio UI. So before you start, be sure to Install Humio’s CLI.

Install Humio CLI

Follow the instruction in the CLI documentation. Once you are ready, you can validate that humioctl is set up correctly using:

$ humioctl status

If this does not return an error, you’re ready to begin.

Creating the assets that will go into your package

You create the dashboards, parsers, saved queries, etc. as you normally would in Humio. There is nothing special about them. You may already have the things you want to go into your package created.

When working on your package it can be useful to upload sample data from a file to e.g. test a parser. You can either setup a data shipper like FileBeat or use Humio’s CLI and just upload a file:

$ humioctl ingest <REPO> --tail <FILENAME> --parser <PARSER_NAME>

Exporting the package

Once you have your assets ready you can export them as a package using the Package Export Wizard. You can find it in the UI under “Settings” -> “Packages” → “Create custom package”

A package is essentially a zip file with a bunch of YAML files describing the dashboards, alerts, etc. and some metadata files. While you could create these files by hand, the easiest way to get started with a package is by using the ‘Package Export Wizard’.

On the export page you will be asked to select the assets that you would like to go into your package. It will also fill in some metadata about your package such as name and description. This metadata will go into the README.md file and manifest.yaml file, which are at the root folder of your package.

Once you have exported your package you should unzip the file and add it to source control, such that the manifest.yaml file is at the root of the code repository. That way you can manage changes over time and collaborate with others. Alternatively you can upload your package to a shared location like S3 and have people install it from there.

Installing a Package

You have two options for installing a package:

  1. Using Humio’s CLI
  2. Using Humio’s UI

The choice comes down to your use-case. If you are using a custom package to manage your Humio repository’s dashboards for instance, the CLI is the best way to go. Installing packages this way will override any manual modification done in the UI. This is equivalent to a force push in git terminology. Any changes must be exported and placed in source control.

If you instead use the UI, you will be able to merge local changes with changes made in the new version of the package.

Using humioctl

Let’s install the package we just exported and unzipped:

$ humioctl packages install /path/to/my/packages/root/

alternatively, if you are maintaining your package on Github you can install from the Github URL,

$ humioctl packages install https://github.com/myorg/my-package/

or you can point directly to the zip file you just created:

$ humioctl packages install /path/to/my/package.zip

there are a few more options that you can read about using humioctl packages install --help.

Using Humio’s UI

Alternatively, you can install your package in the UI using the Zip file upload.

To install a package through the UI go to:

“Settings” -> “Packages > Installed” -> “Upload”

and select your Zip file.

If a previous version of the package is already installed this will guide you through a merge process, where you are given the option to keep any modification, made. At the moment this an “all or nothing” merge where either you keep the local changes or use the new modifications coming from the package.

Maintaining a Package

You should maintain your package as a Git repository. That allows you to collaborate on changes to dashboards, parsers, etc.

You can either edit YAML files by hand, or make changes in Humio’s UI and “Export as Template” on the individual asset. There is no need to go through the “Export Package” flow again.

If you want to make changes to the YAML manually, there is a documentation section about package file formats.

Humio does not allow overwriting existing versions of a package. So remember to bump your package version number when you update the content of your package. You do this either in the manifest.yaml file or be going through the export wizard again.

Publishing a Package in Humio Marketplace

If you want to publish a package and make it available to everyone - we would love to hear from you or your company. You can contact support@humio.com for more details.

It can be a list of parsers or full set of dashboards for a specific technology, or anything really.