Package Content Guidelines

When building and sharing a new LogScale package make consider all of the contents of the package as described below.

  • Scope — A unique identifier for the package

  • Name — the Vendor's product name.

  • Version — The version of the package.

  • Package Type — the type of package, which can be either application or library.

  • Author — The person or company who authored the package.

  • Brief Description — a brief description of the package.

  • Icon — the icon to be used on the marketplace for the package .

  • License — The apache 2.0 license.

  • README — a read me file for the package.

Note

All Marketplace submissions are made under the Apache 2.0 license. In the event that a duplicate package is submitted, or significant overlap between packages is identified, LogScale may decide to combine the assets.

Some examples where an existing package should not be duplicated:

  • Apache httpd Web Server

  • AWS VPC Flow

If you did feel you had a unique package related to the functionality already included here, a good question to ask is "would my new package be useful without the existing package?", or "would the same group of people always be interested in both?".

Scope

The package scope and name provide a unique identifier for the package. For the scope, use the vendor/manufacturer of the technology to which the package relates.

If the package uses logs from multiple different vendors/manufacturers, then you can enter the scope as your company name or relevant industry standard or framework. Scope should be entered as lower case with only standard text characters. See below for some examples.

Technology / Vendor Scope Notes
Amazon Web Services aws Some AWS services are referred to as aws and some Amazon. The scope should always be aws but the right name should be used in the package README.
Microsoft Azure azure Azure apps are distinct from traditional Microsoft packages.
Google Cloud Platform gcp This includes GSuite, as Google continues to integrate these services.
Apache Software Foundation apache All projects related to the Apache Software Foundation (httpd, kafka, etc). App versions specific to a commercial variant of these technologies should use an alternative scope, for example confluent/kafka.
Okta okta Where a vendor only offers a single technology, service, or tool, the scope and name may be the same. It is acceptable to therefore have a scope name combination like okta/okta.
Center for Internet Security (CIS) cis Where the package supports multiple log source types use a scope of any related frameworks or standards if possible.

Note

LogScale may choose to alter the scope and/or name of any package submitted to ensure it properly fits the naming schema. The scope does not denote any ownership of the package, or necessarily reflect the author or that the package is in any way sponsored or supported by the entity. Additionally the scope can not be changed once the package is in the marketplace so ensure it has longevity.

Name

The package name should be the specific vendor's product name to which the package relates, or the use case for the package. The name should be entered as lower case with only standard text characters.

Examples

AWS VPC Flow would use the scope aws and the name vpcflow, so the final package identifier becomes aws/vpcflow. A package for Okta is likely to use the same name and scope, so the identifier becomes okta/okta. A use-case specific package, such as one based on the CIS Foundations Benchmark for AWS, would use cis for the scope, and aws_foundations_benchmark or similar for the name.

Version

LogScale recommends following the Semantic Versioning standards for package versions. From the standards: Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,

  • MINOR version when you add functionality in a backwards compatible manner, and

  • PATCH version when you make backwards compatible bug fixes.

Note

API incompatible changes for the purposes of a LogScale package would be where the log format has changed, or the way the data needs to be parsed is changed in an incompatible way with data users have already ingested. It is critical that any change to a package that is not compatible with previous parsing and/or field naming convention is released as a new major version.

Package Type

Select Application for the package components to be automatically installed in the target repository; i.e. when a user deploys an "Application" type package, the assets in that package are automatically deployed into the repository.

Select Library to not install any components automatically, but to install templates from which customers can create and install the components later.

Author

It is suggested that you enter the Author as your own name (although you can use your company name if you like). It is preferred to NOT include email addresses here. There is the ability to include 'Contributors' in the marketplace listing but this is not yet available in the LogScale UI. You can tell LogScale what you want listed as Contributors via email when submitting the package (see later section).

Example: "John Doe" or "Acme"

Brief Description

This text is displayed next to the package name in the marketplace. It should be 65 characters or less and provide a brief description of what the package does.

Example: "A parser and sample overview dashboard for Amazon VPC Flow Logs"

Icon

Provide a link to a suitable icon, that is displayed next to the package in the marketplace. For a package specific to a certain vendor/manufacturer, please use their standard logo and ensure that the logo you use conforms to their guidelines on usage, and that you are allowed to use it in this way. For example, if creating an AWS package then the 64px PNG icons from the AWS asset pack must be used to generate the icon. Provide the link in either of the https:// or data:url: formats. The icon should be 64x64 px PNG or SVG on a transparent background.

It is highly recommended to encode the icon as a data:url, and there are various assets online that make this conversion straightforward, search "png to data uri conversion" for options.

License

For inclusion in the marketplace, LogScale requires the package to be usable under Apache 2.0 license. This is the default choice when creating a package using the LogScale UI.

Note

Any package submitted to the Marketplace without a license, or with a license that is not Apache 2.0 will require amending to include Apache 2.0 license prior to review.

README

For inclusion in the marketplace, LogScale requires the README part of the package to follow the below format as consistently as possible. This is to ensure simplicity for customers. LogScale intends to incorporate some of these points as top level package metadata at some point in the future.

The README is written in Markdown and should follow the guidelines provides in these pages README.md.