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

In a previous blog, we demonstrated how to create custom dashboards in Instana and bundle them into integration packages for easy sharing. But dashboards are only one part of a comprehensive observability strategy. Just as important are event definitions - rules that detect issues such as high CPU usage or custom metric thresholds.

With the Instana CLI for Integration Package Management, you can now define, export, and package these event definitions just like dashboards. Including both in your integration workflows ensures that alerts, incidents, and health signals remain consistent and reusable across teams and environments. This flexibility enables organizations to build modular, shareable observability assets that scale as their needs evolve.

But why go through the effort of packaging event definitions?

Because observability is a team sport—and increasingly, an ecosystem effort.

While anyone can define event rules using the Instana UI, this blog focuses on a more scalable, production-grade approach that supports both internal team workflows and cross-organization collaboration:

• Package producers: whether internal domain experts within a team or entire organizations like IBM or Business Partners, they create well-defined event definitions and package them for reuse.
• Package consumers: which could be other teams in the same company, or entirely different organizations (e.g., customers), can then import and apply these tested packages without needing to reinvent the wheel.

This working model is foundational to how the Instana ecosystem is being built: domain-specific knowledge and best practices are captured in reusable packages, which are then shared through trusted channels like the central registry or private distribution mechanisms. Whether you’re contributing to the public ecosystem, distributing within a partner network, or operating in a self-hosted, air-gapped environment—this approach enables scalable, consistent, and collaborative observability across environments and organizational boundaries.

Part 1: For Package Producers

As a package producer, your goal is to define reliable event rules and make them portable across environments. In this section, you’ll learn how to structure, define, export, and publish event definitions using the Instana CLI for Integration Package Management — enabling consistent and reusable monitoring practices for your team or organization.

Initialize Your Integration Package

Before creating or exporting any event definitions, initialize an integration package using the Instana CLI for Integration Package Management. This sets up the correct folder structure and prepares your project for publishing.

To initialize an integration package, including event and dashboard definitions, follow the same process as described for dashboards using the Instana CLI for Integration Package Management. For detailed instructions, refer to the Init the package using CLI section in our previous blog.

$ stanctl-integration init

When initializing the package using the CLI, make sure to select both dashboards and events as the types of integration to include, if your package contains both. The only difference is that exported event definition files should be placed inside an events directory (instead of dashboards) within your integration package.

After initialization, your directory structure should look like this:

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

Define Your Event Definition in Instana

Now that your package structure is ready, create your event definitions in the Instana UI:

1. Navigate to Settings > Events, then click New Event.
2. Provide the basic event information:
   • Name and description: Avoid using hyphens, as they can interfere with search.
   • Severity: Choose either warning or critical.
   • Incident flag and grace period: Define whether this should be treated as an incident and specify how long to wait before closing the issue once the condition clears.

For a complete breakdown of all available fields including metrics selection, conditions, scope, and more, see the official Instana documentation on defining custom events.

Export Event Definitions

Once you're happy with your event definitions, use the CLI to export them into reusable JSON files:

$ stanctl-integration export \
  --server $INSTANA_SERVER \
  --token $API_TOKEN \
  --include type=event title="High CPU Alert" \
  --location ./my-package

Or, if you know the event ID:

$ stanctl-integration export \
  --server $INSTANA_SERVER \
  --token $API_TOKEN \
  --include type=event id=event12345 \
  --location ./my-package

The CLI ensures consistency and simplifies the export process, making it easier to reuse definitions across teams and environments. This saves the event definition to your local file system in JSON format. You can then include it in an integration package.

Publish the Package

Once your event definitions are added to the package, you can publish it for reuse by others.

There are two options depending on where you want to publish:

Option 1: Self-Hosted Registry

If you're using a private or self-hosted registry, you can publish directly using the CLI:

$ stanctl-integration publish --package @instana-integration/packagename \
  --registry-username <your_username> --registry-email <your_email>

Option 2: IBM-Hosted Central Registry

If you want your package to be published to the official IBM-hosted central registry, it must go through a formal review and approval process.

To do this:

• Fork the Observability-as-Code GitHub repo.
• Add your integration package as a pull request.
• IBM maintainers will review, approve, and publish your package once it meets contribution guidelines.

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

Part 2: For Package Consumers

As a package consumer, your goal is to quickly adopt and apply proven observability assets created by others. The primary way to do this is by downloading and applying a complete integration package from the central registry.

This section explains how to import full integration package into your Instana environment, helping you maintain consistent, production-ready monitoring setups across teams and organizations.

Download the Package from the Central Registry

To begin consuming event definitions, first download the integration package from the central registry:

$ stanctl-integration download \
  --package @instana-integration/packagename

This fetches the latest version of the package and stores it locally in the current working directory.

Import Event Definitions

Once the package is downloaded, you can import its elements into your Instana environment:

$ stanctl-integration import \
  --package @instana-integration/packagename \
  --server $INSTANA_SERVER \
  --token $API_TOKEN

To import multiple event definitions from a specific folder inside the package:

$ stanctl-integration import \
  --package @instana-integration/packagename \
  --server $INSTANA_SERVER \
  --include "events/**/*.json" \
  --token $API_TOKEN

This command helps import all event definitions from the package folder in one go.

Once imported, the event definitions are now available in your Instana environment—ready to be applied, customized, or extended as needed.

Real-World Example: Language-Specific Reference Packages

A simpler and more practical way to see this approach in action is by exploring the language-specific reference packages—such as Go, Python, and Nodejs. These packages now include event definitions alongside dashboards, offering a ready-to-use observability setup for common application environments.

You can connect the opentelemetry-demo application to your Instana server, then import one of these packages to see relevant dashboards and pre-configured event definitions automatically appear. This makes it much easier to get started and understand how integration packages work in a real-world scenario.

Conclusion

Just like dashboards, event definitions can and should be made reusable and sharable to promote consistent observability practices across environments. With the Instana CLI for Integration Package Management, you can:

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

By treating event definitions as code, you create scalable, transparent, and modular observability solutions that are easy to maintain and extend.

#Integration
#General
#OpenTelemetry
#Tutorial