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
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.
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.
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>
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.
You have two options for installing a package:
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.
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.
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.
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.
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
firstname.lastname@example.org for more details.
It can be a list of parsers or full set of dashboards for a specific technology, or anything really.