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

In our last blog, we covered how to create Instana custom dashboards and make it publicly sharable by building an integration package to include the dashboards. We also mentioned that IBM has a GitHub repository to host the integration packages that are officially maintained by IBM. Contributing to the IBM Instana Observability as Code GitHub repository is a great way to share your work and get involved in the IBM Instana Observability community. In this blog, we will guide you through the simple steps to contribute your custom dashboards and integration packages to this IBM-hosted repository as well as some best practices.

Fork and clone the repository

The first step is to fork the Instana Observability as Code GitHub repository, then clone to your local machine.

git clone https://github.com/<your-github-account>/observability-as-code.git

Now you have the repository on your local machine, ready for edits!

Create a local package

Next, you need to create a package that follows the Instana integration package structure. For this, you can refer to the blog Making Your Instana Dashboard Publicly Sharable for full instructions on how to create a package. In this repository, all packages are located under the packages directory. You can create a subdirectory for your integration package, or use the init command provided by Instana CLI for Integration Package Management to generate the package skeleton for you.

Imagine you are creating a Python integration that will help users monitor Python applications, simply use the init command to set up the structure. Once the package skeleton is created, define your dashboards on Instana UI, save the contents as dashboard definition files into the dashboards subdirectory and update the README.md file with relevant information.

$ tree packages/@instana-integration/python
packages/@instana-integration/python
├── README.md
├── dashboards
│   └── runtime.json
└── package.json

2 directories, 3 files

Create a pull request

Once your local package is ready, you can push the changes to your repository. Here is how you can do it:

git add .
git commit -m "Add Python integration package"
git push origin <your-branch-name>

Next, go to the GitHub repository and open a pull request against the upstream repository. This will notify the project maintainers to review your contribution.

Monitor pull request pipeline

After opening the pull request, an automated pipeline will run. The pipeline will check the following things:

• Linting rules
• Code quality
• Validity of integration files

Here is where things get interesting. Let’s say we introduce a linting error by missing a critical field in package.json, for example, the version field. The pipeline will fail, and you will notice an error in your pull request.

You can click on "View details" to see the detailed report for the linting. In this case, you will see an error like this:

Error: Missing required field: version in package.json

No worries! All you have to do is to fix the error in your package.json. Here is how:

• Open your local package.json file.
• Add the missing field, e.g.: "version": "1.0.0".
• Commit the fix.
• Push your changes again to your repository.

git commit -m "Fix missing version field in package.json"
git push origin <your-branch-name>

Once you push the changes, the pipeline will automatically re-run. If everything looks good, it will pass without any issues.

After your pull request passes the automated checks, a project maintainer will review your changes to make sure everything looks good and follows best practices. Once approved, the pull request will be merged into the main branch.

Monitor merge pipeline

Now that your changes are merged, another pipeline will trigger to publish all newly-added or updated integration packages to the central public registry. You can monitor the pipeline status to confirm everything is running smoothly. Here is how you can track the process:

• Navigate to the Actions tab: After the pull request is merged, head over to the Actions tab in your repository. This tab lists all workflows and their statuses, including the one triggered after your pull request is merged.
• Check running workflows: Once you are in the Actions tab, look for the workflow that corresponds to your merge. You will see the status of the workflow, e.g.: running, completed, or failed, right on the workflow's summary page.
• View workflow details: You can click on workflow to see more detailed information. This will take you to a page showing the steps of the pipeline and any logs associated with the process. Here, you can monitor each stage of the workflow and check if the package was successfully published.

Check the public package

Once the merge pipeline completes, your latest integration package will be available in the Instana integration organization on the central public registry. To find your package, simply visit the link and explore the available integrations. You can verify that your package has been successfully published by searching for the package name within the Instana integration organization’s homepage. Here’s how you can do it:

• Go to the Instana Integration page: Instana Integration on npm.
• Verify your package: You should see your package listed with the latest version details.

Congratulations! You have successfully published your python integration package as an official IBM Instana integration package and publicly available to the Instana ecosystem.

Best Practices for Authoring a Package: Stay Lint-Friendly!

When you are creating an integration package for Instana, it is essential to follow some best practices that align with the linting rules to ensure everything is in top shape. Let’s break down some key things you should keep in mind when developing your package and how the linting process can help.

Naming your package: stick to the convention

Your package name must follow the IBM naming convention to ensure consistency and easy discoverability. The linting tool checks if your package name matches the pattern @instana-integration/<integration-name>.

• Example of a valid name: @instana-integration/python
• Example of an invalid name: @instana/python-integration
• Example of another invalid name: python-integration

If the name does not match the required pattern, the linting tool will flag it as an error.

Pro tip: This convention is only required for the integration packages that are officially maintained by IBM. If you want to build and maintain your packages on your own, it does not have to follow this convention.

Versioning: stick to SemVer

The versioning of your package should follow Semantic Versioning (SemVer). The linting tool ensures your version format follows x.y.z (e.g., 1.0.0). Moreover, if you are updating your existing package, it checks your version is higher than the currently published one on the central public registry. If it is not, you will get an error.

• Example of valid version: 1.0.1
• Invalid version errors: Invalid version 1.0.0. It must be greater than the currently published version 1.0.0.

Required fields: fill them out

Your package.json file should include some essential fields like name, version, author, license, and description. These fields are required by Instana for clarity and functionality. If any are missing, the linter will notify you with an error.

Pro tip: Even though description is optional, it is highly recommended to add a brief description of what your package does. This helps users understand its purpose right away.

README.md: be detailed and clear

A great README.md file makes it easy for others to understand what your integration does, how to use it, and where to find additional resources. The linter checks for the following key sections in your README.md file:

• Package name: The title of your integration package.
• Dashboards: Details about the dashboards included in your package.
• Metrics: Information on the metrics collected.
• Semantic conventions: Any defined standards or practices related to the integration.
• Resource attributes: Key attributes your integration relies on.

If any of these sections are missing, the linter will flag your README.md file as incomplete.

Dashboard files: make them sharable

The linter will check the dashboards folder for any .json files. It verifies that each file contains a global access rule. If this rule is missing, you will receive an error. This ensures that your dashboards are accessible as intended for all users.

Example of a valid global access rule:

{
    "accessType": "READ_WRITE",
    "relationType": "GLOBAL",
    "relatedId": ""
}

By following these best practices and aligning with the linting rules, you will ensure that your integration package is clean, error-free, and easy for others to use. These steps will help you pass the linting process in one step, ensuring a smooth experience.

Conclusion

Contributing to the IBM Instana Observability as Code GitHub repository is a great way to enhance your skills and make valuable contributions to the Instana ecosystem. By following the simple steps outlined in this guide, you can easily create, test, and submit your own integrations to improve observability for the entire community. With the collaborative nature of the ecosystem, your contributions help to shape a more powerful and adaptive IBM Instana Observability platform for everyone.

Ready to contribute? Clone the repository, follow these steps, and make your mark on the Instana ecosystem!

#CustomDashboards
#General
#OpenTelemetry
#Integration
#Tutorial