Creating a Package

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.

Make sure you have Integrations ‣ Change Packages permission for the repository in which you’re creating a package. Otherwise, you may encounter errors due to permissions. For testing the examples here, you might use your personal Sandbox repository since there you’ll have the required permissions to manage packages. You can read more about permissions under Role Based Authorization.

Exporting the Package

Once you have your assets ready, you can export them as a package using the Create a package link within the Settings view.

For a more detailed guide to the different fields and contents, see Developer Guidelines for Packages.

To crate a package:

  1. Click on the Create a Package link under the Settings tab in your view

  2. The Create package page provides background information on exporting assets to a package. To create a package, click the Export package button.

    Figure 1, Create package view
  3. The fields within the Package Metadata section of the form marked with a * (asterisk) are required and must be filled in:

    Figure 2, Package Metadata
    • Scope is the scope or namespace for the package, for example you might use the product or domain name, for example humio or github. Names must start with an upper or lower case letter, then use alphanumeric characters, dashes or underscores, and be between 3 and 107 characters in length.

    • Package Name is the specific package name, for example you might use a log name or functionality group, such as weblog or metrics. Names must start with an upper or lower case letter, then use alphanumeric characters, dashes or underscores, and be between 3 and 107 characters in length.

    • Brief Description is the outline description given in lists, the marketplace listings, and during installation.

    • Icon is the location of an icon or image to be used when viewing the package; it will be shown in summaries and lists and can be a helpful tool for identification.

    • Version is the version number of this package. This should be used as with any version number to enable you to distinguish between versions and functionality as your package develops. Each version is distinct, and there can be multiple versions of a package available.

    • Package type is either Library or Application using the radio buttons.

    Click the Next to continue to the next page.

  4. The Package contents page enables you to select the package contents according to the different asset types that you can want to include in the export packed.

    To include a component, you must click the checkbox next to each item that you want to include in the package. Items in bold, or with the package icon next to them indicate that the asset is already part of another package. Selecting a package asset by default includes all related assets within that package.

    Figure 3, Choosing Package Assets
  1. Once you have finished defining the contents of the package, click the Download Package button. You will be presented with a Save File dialog where you can select the location to download the Zip file of the generated package.

A package is essentially a Zip file containing several YAML files, with each file describing the dashboards, alerts, and other components, as well as some metadata files.

Once you have exported your package, you should unzip the file and add it to source control, so 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 Amazon S3 and have others install from there.

Maintaining a Package

You should maintain your package within a source control mechanism, such as git or hg. 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, read the package file formats documentation page.

Note

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.

Submitting a Package to the Humio Marketplace

The Humio Marketplace holds a number of packages that are tailored for different use cases. If you want to contribute to the marketplace your package needs to include specific metadata among other things. The Developers Guidelines documentation provides information on what to include in the package as well as how to submit a package to the 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.