Troubleshooting Performance Issues - What to Expect

Author: Amanda Jennewein

Updated: August 2024

Audience: Everyone

Environmental details: Jama Connect®

Summary

Performance is one of the most pivotal elements of user experience in a web application. This document is geared toward giving our customers insight into what we look for and ask while handling these complex issues.

Understanding performance issues is like peeling an onion. You must uncover each layer of the problem to get to its core. Moreover, the root cause of the issue may be in a different location than where the problem is visible on the application's front end.

Effective troubleshooting of performance issues is a collaborative effort. The more information you can provide while the issue occurs, the faster we can identify and resolve the problem. If you're having a performance issue, answering the following questions will help us start working on the problem and reach a solution more efficiently.

Note: Jama Software® Support cannot assist with issues that do not meet our minimum supported requirements. Supported Software & System Requirements

The Four Dimensions of Performance Troubleshooting

Who?

• Which users are affected by the problem?
• Are these all users, or only specific users (or subsets of users)?
• Are these users all the same license types or contained within a particular user role (a group used to assign permissions)?
• Are these users particularly valuable or important? For example, is this affecting an executive or a set of testers whose results are critical to shipping a product on a tight timeline?
• Which user reported the problem?

What?

• What, specifically, is the actual problem?
  • Does loading a page/feature/item take excessive time, or do things fail?
  • Are you seeing error messages or warnings? If so, can you provide the exact error message or a screenshot?
• What specific actions or areas are "slow"?
  • Is this limited to a specific feature, or is it perceived application-wide?
    • If application-wide, is it worse in some areas, or is it consistently slow across the app
      • What is the impact of the issue?
      • What are the specific business impacts of the issue?
        • Is it painful for users, but they can still complete their job (albeit less effectively), or is this preventing work from getting done?
• What does "slow" mean, quantifiable?
  • A network trace from the browser's developer tools is the most accurate way to provide quantifiable information about what is explicitly slow and how slow it is.
  • What behavior do you expect?
    • In other words, if the application isn't responding in the manner you expected, what were you expecting?
      • • Has this feature or portion of the application behaved differently in the past that was more consistent with your expectations?
• What browsers does this affect?
  • Is it particularly slowing on a specific browser, or is the performance relatively equal across browsers?
    • What changes, if any, have been made recently within your environment?
      • Did you recently begin using a particular feature?
      • Have you made any configuration changes recently within Jama?
      • If self-hosted, have you made any hardware, software, or network configuration changes recently?

Where?

• Where are the affected users located?
  • Are they all from the same office or geographical location?
  • Are they all on the same network?
    • Are users physically connected to that network, or are they using a VPN to access it?

When?

• When did the issue begin?
  • Specific dates and times
• Is the issue still occurring?
  • If not, when did it end?
• If the issue is intermittent, does it happen on a consistent schedule or pattern?
  • The specific time of day?
  • Specific day or week?
  • Always after using some feature or taking some specific action?
• When does the application perform well?
  • Understanding when the issue is not occurring is often just as important as it allows us to compare specific data to look for anomalies.

Only some questions will be relevant in some situations, and we don't expect you to copy and paste these questions as a template into your ticket. However, addressing as many of these elements as possible in your initial response to the ticket will provide a solid foundation for us to begin the investigation and help narrow down the scope of the problem quickly.

What to Expect from Jama Software® Support

Because performance issues differ in nature from most other reported issues, the troubleshooting process often differs from that of the average ticket. You can expect the following (which may be different from the troubleshooting process you're already familiar with):

Expect to Be Actively Involved in the Troubleshooting Process

This is summarized in greater detail by the expectations below, but unlike other issues, working through performance issues often requires us to work together with your team. We typically won't be able to gather some data and then work on the resolution in a vacuum; we'll need to ask additional questions, obtain further data, and test hypotheses and changes using a Test/Measure/Repeat or an Observe/Orient/Decide/Act cycle. This is particularly true for self-hosted customers, as we do not have direct access to the instance of the data.

We will ask several questions.

Troubleshooting performance is an iterative process. Sometimes, we may encounter unknown issues that only become evident through asking questions, and your responses may find new areas for you to consider. We'll try to group these questions, but please be prepared for multiple rounds of questions (while avoiding duplication). 

Some of these questions may need to be more relevant or lead to dead ends.

As we investigate an issue, the data we collect may lead us in unexpected directions. This is because of the complex interconnections between different factors, making it hard for the user to see how they relate to their problem. Please trust that our questions are always relevant and based on data. We'll strive to explain why we're asking each question without making guesses. Sometimes, we ask for more information to rule out possibilities, so please don't worry if we change our line of questioning. We keep track of all the information we gather and will respect all responses as we adjust our focus.

We may request significant data from your server and, potentially, from your users.

Troubleshooting without actual data is like finding a needle in a haystack using a dessert fork on a moonless night; it's nearly impossible. Jama's specific data and configuration often cause performance issues. Due to the complexity of these issues, more than simply identifying the slow functionality and configuration is needed to pinpoint the cause. Actual data from the users and applications experiencing the problem is crucial. Don't worry; we'll help you collect data from tools and logs if needed. 

We may request that you use unfamiliar tools to collect empirical data.

Different situations call for a different set of data and, thus, a different set of tools. In general, we'll ask for a specific type of information instead of the output from a particular tool, but this may require you to set up or use certain kinds of tools that you aren't currently using. We understand that enterprises have varying degrees of security restrictions and validation processes for software and data; we will recommend built-in tools over third-party software where possible, and if a third-party tool is the only way, we'll always look for a free option. However, if we can gather the proper data types, we may be able to troubleshoot your issue effectively. Gathering Empirical Data for Troubleshooting.

We need you to recreate the problem in various environments or configurations.

Before ever asking you to reproduce an issue, we will attempt to replicate it ourselves locally. When we can't replicate the issue, we will often need your assistance to try this issue in multiple environments (such as a test environment) to help rule out environmental or client-side problems. We understand that this may be inconvenient, but your involvement is crucial in helping us to narrow our focus and drive to the root of the problem quicker. We will do our best to minimize these requests but be prepared to conduct thorough testing on your end.

We may request that you make changes to data or configuration. 

We might need you to modify the data or configuration we suspect is causing the issue to confirm our hypothesis. Ideally, we would do this in a test environment, but sometimes, we may need to make direct changes. While we strive to be mindful of each situation, there are occasions where substantial changes are necessary.

The issue may be out-of-scope for Jama Software® Support.

Performance issues with the Jama application may arise from factors beyond the application itself. These may include proxy or network issues, problems with API end-points, configuration issues in the user's browser or client, the user's geographical distance from the server, and problems with external services such as SSO provider (IDP) or integration provider (JIRA, Task Top, Rally, TFS, etc.).
It's important to note that using unsupported software or configurations that do not meet our minimum system requirements can cause performance issues. If we determine that the problem is related to any of these causes, we will request that you address the issues externally before we troubleshoot Jama together.

Performance issues may not have an immediate resolution.

We understand how much of an impact performance issues can have. However, troubleshooting these complex problems can take time due to their iterative nature. We will conduct a thorough investigation to pinpoint the root cause and gather the necessary data. Even if we quickly identify the cause, the solution may be complex and require extensive QA to ensure it fully resolves the issue without creating new problems. While we will work diligently to resolve these issues as quickly as possible, we may be unable to provide an immediate fix.

Great, I know what to expect. If I have an issue, what should I do?

If your site is down or unresponsive, please immediately gather a set of thread dumps and generate a support bundle.

• • Performing a thread dump in Linux or Windows

If you are self-hosted (On-premises), your role as a self-hosted customer is crucial. Review our Supported Software & System Requirements to ensure you're running a supported configuration and have the proper resource allocation for your Jama App server and Database Server.

Note: Jama Software® Support cannot assist with issues that do not meet our minimum supported requirements.

If the problem needs to be listed in the release notes and you have confirmed that your instance meets the minimum supported requirements, please refer to the Four Dimensions of Performance Troubleshooting above and try to answer as many questions as possible.

• Who? What? Where? When?

Collect all the empirical data and logs you can. It would be helpful to have a HAR file of the event.

If you're self-hosted, gather at least a Support Bundle, the contour.log, and some network JavaScript output. Support will provide you with further instructions.

Submit a request from the Jama Software® Support Portal. 

• Jama Connect® Cloud Customer Request Form
• Jama Connect® Self-hosted Support Request Form

Additional Resources

Please note the following: Some additional resources require a Support Portal Account for you to be logged in.

• Supported Software & System Requirements
• Jama Connect® Performance in Enterprise Recommendation for System Administrators
• Gathering Empirical Data for Troubleshooting
• Performing a thread dump in Linux or Windows
• Observe/Orient/Decide/Act

Please feel free to leave feedback in the comments below.