• Users are able to get aggregated information about issues and dependencies across the entire application portfolio.
• Identify portfolio-wide trends or drill down to the single line of source code.
• Analysis results are now fully integrated with the main Konveyor UI, without requiring dedicated reports.
• Downloading static reports or analysis results files for individual applications is still available.

 

Dynamic Reports

The results of source code and binary analysis are vital to assessment of applications. They enable users to define and plan appropriate migration strategies in the later stages of the Konveyor methodology. So far, Konveyor relies on Windup output to present the results of these analyses. It is largely static and isn't stored in Konveyor. It is limiting in that Konveyor cannot aggregate the analysis results for multiple applications in the inventory.

In this enhancement, we present Dynamic Reports. Dynamic Reports use the analysis data created by the new LSP analyzers. They can be generated on-demand for one or more applications from the most recent analysis data available in Konveyor. They enable users to see analysis information of multiple applications in one place to get a high level of migration issues across their portfolio. At the same time, they allow the users to drill down into specifics of each issue.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#motivation

Motivation

With the upcoming integration of new LSP analyzers in Konveyor, the data generated by analyzers becomes a first class entity in Konveyor. We talked about this in our previous enhancement on [Reporting Format](./TODO: Link here). It opens up lots of possibilities for Konveyor in terms of what it can do with the data. We want to leverage that and improve reporting capabilities of Konveyor. Dynamic reports are simply reports that give users much more control on what information is displayed via filters, visualizations, etc. They bring important information across all applications in the inventory in one place and make it easier for users to query that information.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#goals

Goals

We only intend to define requirements and scope for dynamic reports.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#non-goals

Non-Goals

We do not intend to discuss technical details in this enhancement. More enhancements will follow for technical details on implementation.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#proposal

Proposal

The three main components of the dynamic reports we are proposing are Issues, Dependencies and Facts.

Issues and Dependencies are the primary components that will be aggregated over multiple applications, whereas Facts are specific information showed only in the context of a specific application. Note that the analyzers create data pertaining to all three components for one application at a time.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#issues

Issues

An issue is analogous to a Violation created by the analyzer. They are created when analyzer finds a match for a Rule.

Issues have following properties:

• Description: A text description in markdown format
• Rule ID: Rule for which the issue was created
• Category: Helps define severity of issue
• Effort: A numeric value denoting efforts needed to fix the issue
• Hyperlinks: External links that provide additional information pertaining to the issue
• Incidents: Occurrences of the issue across the source code. Each incident will have a file URI and a message that helps show information about that particular incident.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#dependencies

Dependencies

Analyzers output dependencies for an application with each dependency having following properties:

• Name: Name of the dependency.
• Version: Version of the dependency.
• SHA: Checksum of the dependency.
• Indirect: Whether the dependency is indirect.
• Type: Type of the dependency.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#facts

Facts

Facts are additional application specific data generated by the analyzers. Depending upon application technology, different analyzers (providers) will generate different type of data for an application. The application facts will be generated from this information. Examples of application facts for a Java application are:

• Enterprise Java Beans reports
• Java Persistent API usage reports
• Spring Beans reports
• Hibernate session usage

Facts are data that don't necessarily fit into the notion of "issues" or "dependencies". Since the data types for facts are arbitrary, we do not envision aggregating this data at the portfolio level. Facts will only be presented in the context of an application. Filtering / querying application facts will not be possible due to the nature of the data.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#user-stories

User Stories

We define two scopes for the reports:

• Portfolio scope: This is the part of report which is in the context of all or a selected subset of applications in the inventory.

• Application scope: This is the part of report which is in the context of one specific application.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#portfolio-scope

Portfolio scope

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#dependencies-1

Dependencies

• As a user, I want to be able to see a list dependencies across a selected subset applications in the inventory. (See application selection)

• As a user, I want to be able to filter dependencies by whether the dependency is a direct or an indirect dependency.

• As a user, I want to be able to see a list of name of the dependencies shared by two or more applications in the inventory. (See shared dependencies)

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#issues-1

Issues

• As a user, I want to be able to see a list of all issues generated by the analyzer for a selected subset of applications in the inventory. (See application selection)

• As a user, I want to be able to see issues that belong to one or more applications. (See grouping)

• As a user, I want to be able to filter issues by their category, effort and name of the source / target technologies. (See technology filters)

• As a user, I want to be able to use filter by one or more criterias at a time to further narrow down my search of issues. (See Filters on multiple columns)

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#statistics

Statistics

There are two types of statistics proposed - first, statistics generated from the most recent analysis available for applications and second, statistics generated from the history of all analyses that were executed so far.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#based-on-most-recent-analysis-data

Based on most recent analysis data

• As a user, I want to see total number of issues that belong to the "mandatory" category across a selected subset of applications in the inventory.

• As a user, I want to be able to see all categories of issues with their associated story points across a selected subset of applications in the inventory.

See current statistics

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#based-on-historical-data

Based on historical data

• As a user, I want to be able to see trend of story points of issues belonging to "mandatory" category generated from the history of all analyses.

• As a user, I want to be able to see trend of number of issues in each category from the history of all analyses.

See historical data

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#application-scope

Application scope

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#dependencies-2

Dependencies

• As a user, I want to be able to see a list of dependencies for a specific application.

• As a user, I want to be able to see a tree of dependencies so that I can distinguish between a direct and an indirect dependency.

• As a user, I want to be able to filter Java dependencies by package groups. (See java package groups)

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#issues-2

Issues

• As a user, I want to be able to see a list of all issues for an application.

• As a user, I want to be able to filter issues by their category and effort.

• As a user, I want to be able to see number of issues that belong to each category with their associated story points.

• As a user, I want to be able that belong to "mandatory" category broken down by their effort with associated story points for each level of effort.

• As a user, I want to be able to see number of issues generated per Java package.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#facts-1

Facts

• As a user, I want to be able to see all tags generated for the application by the analyzer.

• As a user, I want to be able to filter tags created by the analyzer by categories (tag types).

• As a user, I want to be able to see Enterprise Java Beans in an application.

• As a user, I want to be able to see Java Persistence API usage with details including persistent units, entities and queries.

• As a user, I want to be able to see a list of Spring Beans in an application with details including Bean Name and Class.

• As a user, I want to be able to see Hibernate session factories and entities in an application.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#implementation-detailsnotesconstraints

Implementation Details/Notes/Constraints

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#selection-of-applications

Selection of applications

Since there could be thousands of applications in the inventory, displaying all issues / dependencies for all applications in the inventory might not be ideal for user experience. In this enhancement, we are proposing that the users select a subset of applications via a separate filter for which they want to see the list of issues or dependencies. They can also select all applications, but we want that to be the choice of the user.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#grouping-of-issues

Grouping of issues

At the portfolio level, there's value in displaying impact of an issue or dependency across their portfolio. For the report, it translates into an ability to show distinct issues grouped by applications. Looking at an issue or a dependency, the user needs to be able to see how many applications have the same issue or use the same dependency.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#shared-dependencies

Shared Dependencies

When finding dependencies between two or more applications, it is implied that the dependencies will only be matched using their names. Note that dependencies have more fields than names such as versions, SHAs etc.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#technology-filters

Technology filters

Technologies are modelled as name of the technology along with a range of versions of the technologies, both being string values. In this enhancement, the proposed filter is based only on the name of the technology, and does not filter on version of the technology.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#filters-on-multiple-columns

Filters on multiple columns

One or more columns can be combined together to form complex searches. When filtering by multiple columns, logical AND between different types of columns is implied. Within the same type of columns, however, selecting multiple values implies a logical OR. For instance, when I select "mandatory" for the category column, and "java" and "golang" for target technology, it is implied that a list of issues with "mandatory" category AND with target technologies "java" OR "golang" will be returned.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#filter-dependencies-by-package-groups

Filter dependencies by Package Groups

From analyzers perspective, Name field of a dependency would have fully qualified name for the dependency. It makes the most sense to have a generic "Name" field to accomodate all different kinds of dependencies out there for different technologies. As a result, implementing a filter based on Java package group names implies a full text search within names of dependencies.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#current-statistics

Current statistics

It is possible that the analyses aren't available for all applications in the inventory. When selecting applications to generate statistics, we are only considering applications for which analyses data are available.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#historical-data

Historical data

Trends are generated from high level statistics of all analyses that happened so far. We want to store the computed statistics of every analysis and not the entire output. We want to limit the data points we store. But we are not defining a limit on the period of time for which the data stays. In this enhancement, we are saying all of the data from day 1 is available.

https://github.com/konveyor/enhancements/blob/9b11c7f0f674c33adf2d74aab948cb89bdd7ab20/enhancements/dynamic-reports/README.md#tags

Tags

In this enhancement, we have referred to tags as a part of Facts. From Hub's perspective, they are really just tags that currently exist. We don't intend to introduce a new concept. It's just a way of categorizing information into three pillars of data specific to an application. The ask is to be able see tags that were reported by the analyzer. Whether to include the existing tags created by the users in there is open for discussion.