Scale your alerting: Package and share Instana Smart Alerts

Edit online

Smart Alerts can be bundled to enable scalable, collaborative observability similar to packaging event definitions and custom dashboards. This approach turns observability from an individual effort into reusable, ecosystem-wide best practices.

Smart Alerts are intelligent, metric-based alerts that provide automatic threshold suggestions and advanced features like forecast alerting for proactive monitoring. With the Instana CLI for integration package management, you can define, export, and package Smart Alert definitions just like event definitions and custom dashboards.

Including Smart Alerts in your integration workflows ensures that sophisticated, metric-driven alerting remains consistent and reusable across teams and environments. This flexibility enables organizations to build modular, shareable observability assets that scale as their needs evolve.

Prerequisites

Before you begin, ensure that the Instana CLI for integration package management (stanctl-integration) is installed. For installation instructions, see stanctl-integration – Instana CLI for integration package management.

Create an integration package (Producer)

As a package producer, you need to create Smart Alert configurations that can be shared and reused across teams and environments:

Initialize your integration package. To initialize the package, run stanctl-integration init and select the integration types you want to include. The directory structure is generated based on your selection. For example, if you select smart alerts and dashboards, the following structure is created:
```
packages
└── @instana-integration
   └── packagename
       ├── dashboards
       ├── smart-alerts
       ├── README.md
       └── package.json
```
For complete initialization details, see Making your Instana dashboards publicly shareable
Define your Smart Alert in Instana. With your package structure ready, create your Smart Alert definitions in the Instana UI. Smart Alerts can be created for different contexts by navigating to the relevant section and accessing the Smart Alerts tab. For example:
- For infrastructure Smart Alerts, go to the Infrastructure > Smart Alerts tab and click Create Smart Alert.
- For mobile app Smart Alerts, go to the Websites & mobile apps > Mobile apps tab, click your mobile app name, and then click Add Smart Alert.
For more information about creating Smart Alerts in the UI, see:

Export your Smart Alert definitions. When your Smart Alert definitions are completed, use the CLI to export them into reusable JSON files:

# Export Smart Alerts by name
$ stanctl-integration export \
  --server $INSTANA_SERVER \
  --token $API_TOKEN \
  --include type=smart-alert name="High CPU" \
  --location ./my-package# Export a Smart Alert by ID
$ stanctl-integration export \
  --server $INSTANA_SERVER \
  --token $API_TOKEN \
  --include type=smart-alert id=alert12345 \
  --location ./my-package# Export multiple Smart Alerts with different filters
$ stanctl-integration export \
  --server $INSTANA_SERVER \
  --token $API_TOKEN \
  --include type=smart-alert name="CPU" \
  --include type=smart-alert id=alert1234 \
  --location ./my-package

The CLI automatically queries Smart Alert endpoints and saves every alert as a separate JSON file in the smart-alerts folder, ready to be included in an integration package.

Lint your Smart Alert definitions. Before publishing your package, you can use the lint command to validate your Smart Alert definitions:
```
# Navigate to the folder of the package you want to lint
$ stanctl-integration lint# Linting with a specific package path
$ stanctl-integration lint --path /path/to/package# Linting with debug mode enabled
$ stanctl-integration lint --debug
```
The lint command validates that each Smart Alert JSON file contains the required fields (name, granularity, timeThreshold, and either rule + threshold OR rules[]) and provides detailed error or success messages for each file.
Publish your package. After your Smart Alert definitions are ready, publish the package to make it available for others. You have two options:
- Publish to a self-hosted registry. To publish to a registry, run the following command with your registry credentials:
```
$ stanctl-integration publish --package @instana-integration/packagename \
  --registry-username <your_username> --registry-email <your_email>
```
  If this is the first time publishing, the system prompts you to authenticate with the registry.
- Contribute to the IBM-hosted repository. To publish through the official IBM-hosted repository:
  - Fork the observability-as-code GitHub repository.
  - Add your integration package.
  - Submit a pull request for review.
  After approval and merge, the package is published to the IBM-hosted central registry. The package is now available to the entire Instana community.

Consume an integration package (Consumer)

If you are a package consumer rather than a package creator, you only need to download the package and apply it to your Instana environment.

Download the package. Packages that contain Smart Alert definitions can be downloaded from the central registry before importing them into your Instana environment.
```
# Download a package from the central registry
$ stanctl-integration download --package @instana-integration/packagename
```

Import the Smart Alert definitions. After downloading, you can import the Smart Alert definitions into your Instana environment.

# Import all Smart Alerts from the package
$ stanctl-integration import \
  --package @instana-integration/packagename \
  --server $INSTANA_SERVER \
  --include "smart-alerts/**/*.json" \
  --token $API_TOKEN# Import a single Smart Alert from the package
$ stanctl-integration import \
  --package @instana-integration/packagename \
  --server $INSTANA_SERVER \
  --include "smart-alerts/**/smartAlertTitle.json" \
  --token $API_TOKEN

After your import is complete, the Smart Alert definitions are active and ready to provide intelligent, metric-based alerting with automatic threshold suggestions and forecast capabilities.