Sharing and reusing Instana event definitions

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)

1. Initialize an integration package. Before exporting event definitions, initialize an integration package by using the Instana CLI for Integration Package Management:

   $ stanctl-integration init

   During initialization, select the integration types you want to include. The directory structure is generated based on your selection. For example, if you select only events, the following structure is created:

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

   For complete initialization details, see Making your Instana dashboards publicly shareable
2. Create the event definitions. To define an event in Instana:
   1. Navigate to Settings > Events.
   2. Click New Event.
   3. Provide the required configuration:
      • Name and description
      • Severity (warning or critical)
      • Incident configuration and grace period
      • Scope and metric conditions
   For detailed configuration options, see the Instana product documentation on defining Custom events.
3. Export the event definitions. After creating an event definition, export it by using the CLI.

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

   The exported event definition is saved in JSON format and must be moved into the events directory of your integration package.
4. Lint your event definitions. Before publishing your package, you can use the lint command to validate your event 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 event definition JSON file contains the required fields and provides detailed error or success messages for each file.
5. Publish the integration package. After adding event definitions to the package, publish it for reuse. There are two ways to publish:
   • Publish to a self-hosted registry. To publish to a registry, run the following command:

     $ 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)

1. Download the package. Packages that contain event 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

2. Importing the event definitions. After downloading the package, you can import event definitions from either a registry-hosted package or a local package.

   # Import the full package
   $ stanctl-integration import \
     --package @instana-integration/packagename \
     --server $INSTANA_SERVER \
     --token $API_TOKEN# Import only event definitions
   $ stanctl-integration import \
     --package @instana-integration/packagename \
     --server $INSTANA_SERVER \
     --include "events/**/*.json" \
     --token $API_TOKEN# Import a single event definition
   $ stanctl-integration import \
     --package @instana-integration/packagename \
     --server $INSTANA_SERVER \
     --include "events/**/eventTitle.json" \
     --token $API_TOKEN

   After your import is complete, the event definitions are available in your Instana environment and can be reviewed or modified as needed.