Authored by @Ying Mo, @Disha Bhagat, @Paras Kampasi

In previous blog posts, we explored how to create custom dashboards and event definitions in Instana, and how to bundle them into integration packages for easy sharing (Making Your Instana Dashboards Publicly Shareable), (Sharing and Reusing Instana Event Definitions). But Instana offers another powerful alerting mechanism: Smart Alerts - 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 now 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.

Why Package Smart Alert Definitions?

Just as we package event definitions and custom dashboards, Smart Alerts can be bundled to enable scalable, collaborative observability. As we explained in our previous blog on event definitions, packaging observability assets allows producers such as domain experts, IBM teams, or business partners to share proven configurations with consumers, including internal teams, customers, or partners, via the central registry or private distribution channels. This approach turns observability from an individual effort into reusable, ecosystem-wide best practices.

Part 1: For Package Producers

As a package producer, you'll create Smart Alert configurations that can be shared and reused across teams and environments.

Initialize Your Integration Package

To initialize Smart Alerts, run stanctl-integration init and select Smart Alerts when prompted for types of integration elements to be included in the package. This will create a smart-alerts directory within your package structure.

For complete initialization details, see the "Init the package using CLI" section in our previous blog. The key difference is ensuring you select smart alerts during the setup process.

After initialization, your directory structure will look like this, depending on the elements you chose:

packages
└── @instana-integration
   └── packagename
       ├── dashboards
       ├── events
       ├── smart-alerts
       ├── README.md
       └── package.json

Define Your Smart Alert in Instana

Now that your package structure is 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:

• Infrastructure Smart Alerts: Navigate to Infrastructure > Smart Alerts tab and click Create Smart Alert
• Mobile App Smart Alerts: Navigate to Websites & mobile apps > Mobile apps tab, click your mobile app name, then click Add Smart Alert

For complete details on creating Smart Alerts in the UI, see the official Instana documentation and search for "Smart Alerts" to find documentation for the specific type you need.

Export Smart Alert Definitions

Once you're happy with your Smart Alert definitions, 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.

Publish Your Package

Once your Smart Alert definitions are added to the package, you can publish it for reuse by others. There are two publishing options: a self-hosted registry or the IBM-hosted central registry.

For detailed publishing instructions, see the "Publish the Package" section in our previous blog on event definitions. The process is identical for all packages.

Publishing your package allows other teams to import the same tested, production-ready Smart Alert definitions without needing to rebuild them from scratch.

Part 2: For Package Consumers

If you're a package consumer rather than a package creator, the workflow is straightforward: download the package and apply it to your Instana environment.

Downloading and Importing Packages

The download and import process for packages containing Smart Alerts follows the same pattern as other integration packages. Use the download command to fetch packages from the central registry, then use import to apply them to your environment.

For complete command syntax and examples, refer to the "Part 2: For Package Consumers" section in our previous blog on event definitions.

Quick reference for Smart Alerts:

# Download a package
$ stanctl-integration download --package @instana-integration/packagename

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

Once imported, the Smart Alert definitions are now active in your Instana environment - ready to provide intelligent, metric-based alerting with automatic threshold suggestions and forecast capabilities.

Understanding Smart Alert JSON Structure

If you're new to Smart Alerts or want to understand what's happening under the hood, it's helpful to examine the JSON structure of a Smart Alert definition. This knowledge will help you:

• Understand how Smart Alerts are configured
• Customize exported alerts for your specific needs
• Troubleshoot issues when importing or exporting
• Learn the relationship between UI settings and JSON configuration

Example: Infrastructure Smart Alert for High CPU Usage

Here's a complete example of an Infrastructure Smart Alert that monitors CPU usage on Kubernetes hosts:

{
  "name": "High CPU Usage on Kubernetes Hosts in k8s-demo Zone",
  "description": "CPU usage is greater than or equal to 80% on Kubernetes hosts in the k8s-demo zone.",
  "tagFilterExpression": {
    "type": "EXPRESSION",
    "logicalOperator": "AND",
    "elements": [
      {
        "type": "TAG_FILTER",
        "name": "kubernetes.cluster.name",
        "value": "k8s-demo",
        "operator": "EQUALS",
        "entity": "NOT_APPLICABLE"
      }
    ]
  },
  "groupBy": [],
  "alertChannelIds": [],
  "granularity": 600000,
  "timeThreshold": {
    "type": "violationsInSequence",
    "timeWindow": 600000
  },
  "enabled": true,
  "customPayloadFields": [],
  "rules": [
    {
      "thresholdOperator": ">=",
      "rule": {
        "alertType": "genericRule",
        "metricName": "cpu.used_percent",
        "entityType": "host",
        "aggregation": "MEAN",
        "crossSeriesAggregation": "MEAN"
      },
      "thresholds": {
        "CRITICAL": {
          "type": "staticThreshold",
          "value": 90.0
        },
        "WARNING": {
          "type": "staticThreshold",
          "value": 80.0
        }
      }
    }
  ],
  "alertChannels": {
    "CRITICAL": [],
    "WARNING": []
  },
  "evaluationType": "CUSTOM",
  "ruleLogicalOperator": "AND"
}

Key Structure Elements

Filtering and Scoping:

• tagFilterExpression: Filters which entities the alert applies to (in this case, hosts in the k8s-demo cluster)
• rules[].rule.entityType: The type of entity being monitored (host, container, etc.)
• rules[].rule.metricName: The specific metric to monitor (cpu.used_percent)

Threshold Configuration:

• rules[].thresholds: Multi-severity thresholds (WARNING at 80%, CRITICAL at 90%)
• timeThreshold: Defines how violations are detected (consecutive violations over a time window)

Aggregation:

• rules[].rule.aggregation: How to aggregate metric values within an entity (MEAN, SUM, MIN, MAX)
• rules[].rule.crossSeriesAggregation: How to aggregate across multiple entities

Alert Behavior:

• severity: Alert severity level (5 for warning, 10 for critical)
• granularity: Evaluation window in milliseconds
• evaluationType: "CUSTOM" for user-configured alerts
• enabled: Whether the alert is active

This structure gives you full control over Smart Alert behavior and can be customized to match your specific monitoring requirements.

Conclusion

Smart Alerts represent a powerful evolution in metric-based observability, offering automatic threshold suggestions, forecast alerting, and flexible aggregation methods. Like dashboards and event definitions, Smart Alerts should be made reusable and shareable to promote consistent monitoring practices across environments. With the Instana CLI for Integration Package Management, you can:

• Export Smart Alert definitions as portable JSON files.
• Bundle them into integration packages alongside dashboards and event definitions.
• Publish and share them across your teams or the broader community.

Start building your integration packages today and contribute to the growing Instana observability ecosystem!

#Alerting
#General
#OpenTelemetry
#Integration