stanctl-integration – Instana CLI for integration package management

The stanctl-integration CLI is a powerful command-line tool that is designed to streamline the management of Instana integration packages. It enables platform engineers, developers, and DevOps teams to efficiently download, import, export, lint, initialize, and publish integration packages that define custom elements in Instana.

Overview

The stanctl-integration CLI serves as a comprehensive solution for managing the complete lifecycle of Instana integration packages. It provides a consistent, automated approach to managing custom dashboards and event definitions by using integration packages.

Key features

Package management: Download, initialize, lint, and publish integration packages with ease.
Validation through lint process: Ensure that packages meet quality and formatting standards before publishing.

Benefits

Efficiency: Automate repetitive tasks that would otherwise require manual UI interactions or custom API scripts.
Consistency: Maintain uniform configurations across development, testing, and production environments.
Error Reduction: Minimize human errors through standardized package validation and automated deployment.

Official configuration repository

For real-world examples, community-contributed packages, and tools support, see the official GitHub repository Observability as Code Repository.

This repository is maintained by the IBM Instana team and serves as the central source for:

Official Instana Integration packages: Prebuilt and community-reviewed packages for various technologies.
Package Configuration guidance: Learn how to define dashboards and event definitions by using the stanctl-integration CLI.
CLI tool: Download prebuilt binaries or build the CLI from source by using the provided instructions.
Contribution workflow: Submit new packages or improvements through structured pull requests.

This CLI tool helps teams efficiently manage and standardize Instana configurations by using integration packages. By adopting Instana configurations as code, teams can apply the same rigorous version control, testing, and deployment practices that they use for application code.

Syntax

Use the following syntax to run stanctl-integration commands from your terminal window:

$ stanctl-integration [command] [options]

Where the available command and options are:

command: Specifies the operation that you want to perform, such as download, import, export, init, lint, or publish.
options: Provides extra parameters or flags to modify the behavior of the command, such as --package, --server, --token, --location.

Commands

The following table includes all available stanctl-integration commands with descriptions:


Command	Description
download	Download an integration package from the registry to a local directory.
import	Imports an integration package into a specified Instana environment.
export	Export integration elements from an Instana environment to local files.
init	Start an interactive setup to initialize a new integration package.
lint	Validate an integration package for structure, formatting, and required fields.
publish	Publish a local integration package to the shared registry.
{: caption="Table 1. `stanctl-integration` commands" caption-side="top"}

Command reference and example usage

This section provides detailed syntax, available options, and real-world examples for each stanctl-integration command.

download

Downloads an integration package from the registry to your local machine.

$ stanctl-integration download [options]


Option	Description
`--package, -p`	(required): The package name.
`--location, -l`	(optional): The location to store the integration packages (default: current working directory).

Example:

$ stanctl-integration download --package @instana-integration/nodejs --location ./my-packages

import

Imports an integration package into an Instana environment.

$ stanctl-integration import [options]


Option	Description
`--package, -p`	(required): The package name or path to the package.
`--server, -S`	(required): Address of an Instana environment.
`--token, -t`	(required): API token to import the integration package.
`--location, -L`	(optional): The location to store the integration packages (default: current working directory).
`--include, -i`	(optional): Folder or pattern to match integration element files to include.
`--set, -s`	(optional): Parameter values in the format key=value.
`--debug, -d`	(optional): Enable debug mode (default: false).

Example:

$ stanctl-integration import --package @instana-integration/nodejs --server example.instana.io --token YOUR_API_TOKEN --include "dashboards/**/test-*.json" --set key1=value1 --set key2=value2

export

Exports integration elements from an Instana environment.

$ stanctl-integration export [options]


Option	Description
`--server, -S`	(required): Address of an Instana environment.
`--token, -t`	(required): API token to export the integration elements.
`--location, -L`	(optional): The location to store the integration elements (default: current working directory).
`--include, -F`	(optional): Pattern to match different aspects, for example, title, for the integration elements to export.
`--debug, -d`	(optional): Enable debug mode (default: false).

Example:

$ stanctl-integration export --server example.instana.io --token YOUR_API_TOKEN --include title="foo.*" --location ./my-package

init

Initializes a new integration package with a guided interactive setup.

$ stanctl-integration init

This command prompts you for:

Package name
Package version
Package description
Keywords
Author
License
Types of integration elements to include

Example:

$ stanctl-integration init

publish

Publishes the local integration package to the registry.

$ stanctl-integration publish [options]


Option	Description
`--package, -p`	(required): The package name or path to the package.
`--registry-username, -U`	(required): Username to access the integration package registry.
`--registry-email, -E`	(required): Email to access the integration package registry.

Example:

$ stanctl-integration publish --package @instana-integration/nodejs --registry-username your-username --registry-email your-email@example.com

Note: Publishing directly through the CLI with username and email is applicable only for self-hosted or private registries where you control access. For contributing to the official IBM-hosted central registry, packages must be submitted through the Observability-as-Code GitHub repository as a pull request. IBM maintainers will review and publish approved packages to ensure quality and consistency.

lint

Provides linting for an integration package to ensure that it follows best practices.

$ stanctl-integration lint [options]


Option	Description
`--path, -p`	(optional): The path to the package.
`--strict-mode, -s`	(optional): Restricts the validations.
`--debug, -d`	(optional): Enable debug mode (default: false).

Example:

$ stanctl-integration lint --path ./my-package --strict-mode --debug

Troubleshooting

Common issue

Authentication Failures
- Ensure that your API token has the necessary permissions.
- Check that you are using the correct server address.
- Verify that your token is not expired.
Package Not Found
- Verify that the package name is correct.
- Check whether the package exists in the registry.
- Ensure that you have network connectivity to the registry.
Import/Export Failures
- Enable debug mode with --debug to get more detailed error information.
- Verify that your JSON files are properly formatted.
- Check that the server address is correct and accessible.
SSL/TLS Issues
- The CLI uses a custom HTTPS agent that ignores self-signed certificate errors.
- If you are behind a corporate proxy, ensure that your proxy settings are correctly configured.

Debug mode

Most commands support a --debug flag that provides more detailed logging information. Use this flag to troubleshoot issues:

$ stanctl-integration import --package my-package --server example.com --token YOUR_TOKEN --debug

Exit codes

The CLI uses the following exit codes:

0: Command executed successfully.
1: General error during command execution.
-1: Linting failed with errors.