Gibraltar 2.5 New Feature Dive - Issue Tracking Integration

Quick Takeaway

Gibraltar 2.5 includes built-in integration with two issue tracking systems and provides hooks for integrating with others. This integration extends Gibraltar to automatically create issues for new problems as they occur and make it easy to drill into all of the Gibraltar data related to any issue.

Check out our release notes for technical details or watch videos of how Gibraltar integrates with FogBugz (by Fog Creek) and Gemini (by CounterSoft) to get an overview of our integration.

Update: Check out the article on Closed Loop Software Development over at CounterSoft which talks about this integration. It’s a really easy way to get going, even if you’re a one developer shop!

The Full Scoop

While validating the new Gibraltar Add-In API we wanted to pick a real-world, hard problem that would push the edges of the integration capability. We decided to pick up an idea that had always been on our to do list: Integration with a defect tracking system. We built the original integration for our internal use with our in-house system. After working with that for a few weeks we were clear that this was a must-have feature that became a cornerstone of the Gibraltar 2.5 release.

Integrate with Your Processes

The primary goal of the issue tracking integration was to integrate Gibraltar and the data it collects into your existing workflow. We realized that no matter how great we might make tracking and managing errors within Gibraltar it wouldn’t be as good as just being able to use your existing workflow. Why? Because you would still need your existing system, so why have two separate workflows? Instead, you want to be able to look in your issue tracking system and say this is all there is without having to manually key and translate.

As a baseline, consider what would happen if you just configured email notification to flow from Gibraltar to your issue tracking system. This would create a new issue each time a qualifying event happened. In a production environment the number of issues would quickly get out of hand - one recurring problem and you’d be spending your time closing duplicate cases instead of working the important ones. Instead you need to be sure:

Each new issues creates a new case
New sessions with the same problem just add more information to the open case
You have some way of ignoring errors that don’t represent a defect.

The Gibraltar integration delivers on this by scanning sessions as they come in and mapping errors into your issue tracking system. This integration ensures:

Errors with a new unique signature will open new issues.
Errors that match an existing signature will add additional information to the existing issue.
If an error reoccurs in a new version after the related issue has been closed it will be reopened, unless you’ve set that issue to be ignored.
Gibraltar sessions and issues will be related so you can easily see all of the sessions in Gibraltar for a particular issue.

All of this is possible because Gibraltar queries the issue tracking system while analyzing sessions to determine the right action to take.

Unexpectedly Awesome

When we first set this integration up ourselves we carefully sandboxed it off so it wouldn’t interfere with our existing approach to our CEIP. Several weeks in, the development team started pulling items out of the sandbox and into our support queue and defect backlog because they were spot on. Soon we were hooked - this was the way it should to be for everyone. We took our original implementation and included it in the release as a source code sample and set out to create in-the-box integration for some great systems.

This is one of those cases in software where the system is more valuable than the sum of its parts:

Real user errors are accurately and completely conveyed into your issue tracking system without any manual effort.
You manage issues the same way you always have, including whatever reporting you’re already doing.
You see all of the Gibraltar data for an issue with just a few clicks, no searching for the data by looking at messages until you find the right one.

Gibraltar adds value and reinforces your investment in issue tracking without requiring you to change how you work.

Translating between Gibraltar and Issue Tracking

In Gibraltar each session is identified by a distinct Product, Application and Version, like Gibraltar Analyst 2.5.0.742 or Gibraltar Hub 2.1.0.594. These are usually very specific. On the other hand in your issue tracking system you usually have more general categorization, like Gibraltar Current Development for the active branch and Gibraltar Support for shipped versions. Not only are the two lists different, but you need enough mapping information to put new issues into the right workflow which may require selecting a priority, area, category, or whatever your issue tracking system requires.

Once you’ve enabled support for your issue tracking system you can configure how to map Gibraltar sessions into it from within Analyst. When a session is being analyzed it’s compared against the list of mappings until it matches one. To help minimize the amount of configuration necessary you can specify:

Just a Product
Just a Product & Application
A Product, Application, and partial or complete version.

In the example at right, all sessions for Gibraltar Analyst with the major/minor version 2.2 would match. You can do more interesting wild card version matching to help fit your exact situation, see our documentation on configuring relationships.

The idea is to configure a session to get into the right initial state in your workflow. From there it should flow through just like if you keyed the defect yourself.

Details you Can’t Ignore

As more sessions come in they will be checked and the appropriate issues updated. A special case for this is when you’ve closed the related issue. Gibraltar has to decide whether to ignore the new data or reopen the issue. To work this out it focuses on the version of the new session:

If it’s the same or older as the latest version previously seen on the issue then the new data is ignored.
If it’s for a newer version the defect is reopened

The idea is that Gibraltar recognizes there’s a lag between when you declare an issue resolved and when that fix gets deployed to users. As long as it’s only occurring in the same set of versions it showed up in previously it’s still reasonable that the issue is closed. If it shows up in a newer version then it probably hasn’t been fixed and certainly should be rechecked.

Until you have to Ignore Them

In any system there’s a set of errors that aren’t defects. Temporary network connectivity issues, user errors, server timeouts… They are still errors but they don’t call for any action on your part. To handle this, Gibraltar supports marking an issue to be permanently ignored. The exact mechanism depends on the particulars of the issue tracking system, but it’s selected to make it natural and obvious.

When you first enable automatic integration these noise issues will get opened once, but all you have to do is mark them to be permanently ignored and they’ll never resurface again. Within a short period of time all of the common noise items will be suppressed and every new item will be gold.

Researching and Resolving Issues

Opening issues automatically is just one direction of integration. Once the issue exists you want to be able to see all of the related sessions in Gibraltar effortlessly. Within Analyst you can click on a dedicated node in the tree to see all of the open issues with Gibraltar sessions and drill down to the list of all related sessions.

Pick a session and you can open it or just preview all of the errors and warnings within it. In this view you can quickly spot trends in the sessions: perhaps they’re all in the same timezone or same operating system, or have another error that’s the true culprit.

Imagine that - you receive an email notification that there’s a new issue for you to look at. You double-click the Analyst icon on your system tray and Analyst pops up. Click on the issue tracking node and the most recent issue is on the top. In seconds you’re seeing the whole picture of the error: Related exception(s), actions they took leading up to the problem, performance and memory data. You’ll get the whole picture quickly.

The dedicated issue tracking display supports a number of built-in views that are designed to match each system’s typical grouping & sorting to help you find what you want faster.

Creating Issues by Hand

You don’t have to just rely on the automatic issue management feature: When you’re viewing a session you can select a range of messages and make a new issue from them on the fly.

Each of the messages you’ve selected are summarized with the last message in full detail. This lets you show events leading up to a problem and then the big problem itself.

Gibraltar will still search your issue tracking system to see if there’s an existing case matching the last message you selected so it can handle adding new data to an existing issue or creating a new one. It also checks your mapping configuration to pick the best defaults for the new case in your issue tracking system.

You can add whatever additional text you feel is useful to describe why you’re creating the issue and override some of the initial defect options like category or priority, depending on the system.

Create issues for suspicious items in our data - warnings, or just messages that don’t make sense. Regardless of how you create the issue the rest of the integration works the same.

Work as a Team

Issue tracking systems are fundamentally about tracking & sharing knowledge on the state of your environment with a team of people. Gibraltar fits right into this by:

Sharing configuration with your whole team: Only one person needs to go in and update the mapping setup when you deploy a new version or application and the whole team is kept current.
Centralizing Analysis: You can have the Hub perform all of the session analysis so no one need run Analyst for you to get new issues created & updated.

You can perform all of the configuration within Analyst and it flows back and forth to the Hub automatically, no need to get IT involved on the server when you need to adjust something.

An Army of One

If you’re using just Analyst stand alone you can still take advantage of everything we’ve covered - you just need to leave Analyst running to automatically have sessions analyzed (otherwise they’ll wait for you to run it the next time). Fortunately we’ve made that a pretty good experience in this release.

Get Started Today

We’ve designed the integration to work without requiring anything be installed into your issue tracking system: Just enable the integration feature and go. You can get it started with just one member of your team and see how it goes, or charge in full-bore by configuring automatic integration with the Hub and sharing the configuration with your whole team. Download Gibraltar and get started! If you don’t have a defect tracking system, FogBugz will provide a free hosted instance for 1 or 2 users and Gemini offers a free license for up to three users.