6.3.2. Dashboard¶

Settings for making the analysis results available to the Dashboard Web Application

This rule is used to configure properties of the database where erosion issues are being stored and how to transport the data to the Dashboard server.

6.3.2.1. Options¶

advanced¶

Options that are normally not required

advanced.edit_distance_limit : int = 4096

Maximum edit distance (in number of tokens) for which the diff algorithm guarantees finding a minimal diff. If the edit distance between two analyzed versions of a file exceeds this limit, the diff algorithm falls back to a heuristic. Higher values tend to more accurately connect issues when a file has significant changes, but will also cause the diff computation for such files to take more time. Setting the limit to 0 will disable it. Without a limit, diffing large files may take a very long time, e.g. more than one hour to diff two 10 MB source files.

The run time of the diff algorithm is O((N+M)*min(D,edit_distance_limit)), where N,M are the old/new input sizes and D is the actual edit distance.

advanced.import_only_first_style_violation_per_line : bool = False
If this option is enabled, the database importer will deduplicate multiple identical style violations within a single line that differ only in the column number. This option only affects multiple style violations that appear in the same line and have the same message and entity.
Example:
c = (int)a + (int)b;
MisraC2012Directive-4.6 reports two instances of "Use of base type outside typedef [int]" that only differ in the column number. If this option is enabled, only the first instance will be imported into the dashboard.
c = (int)a + (long)b;
In this case the two MisraC2012Directive-4.6 messages differ due to the different type. Both will be imported into the dashboard independent of this option value.
This option exists for compatibility with older versions of the Axivion Suite, where the database importer always performed this style of deduplication. Disabling this option tends to result in additional violations, which may be undesirable if comparing to a baseline. For new projects, we recommend disabling this option.

cache_directory¶

cache_directory : bauhaus.analysis.config.ProjectRelativePath = '.axivion-cache'

A directory that can be used to store temporary analysis files.

These files can safely be deleted while no analysis is running. However, keeping this folder between subsequent analysis runs can be beneficial to performance.

The directory will be created automatically if it does not exist.

ci_mode¶

Options that apply to a CI build and can be overridden by values in local_mode for a local build.

ci_mode.authentication

The credentials for connecting to the dashboard.
In case of the local build, you will need credentials to download a reference version where regular user credentials are usually sufficient. When triggering the local build via one of our IDE plugins, you do not need to configure anything here, as the IDE plugin will forward the necessary credentials.

ci_mode.authentication.passfile : bauhaus.analysis.config.PythonOnlyPlainPath | None = '$(AXIVION_PASSFILE=)'
If passfile is set and points to an existing file, behavior of input password is changed: password then contains an encrypted JSON object which contains the password while the passfile contains the key to decrypt.
Note that the file referenced here will be deleted after use for security reasons.

Do not change from the default value unless the implications are well understood; doing so may break your communication with the dashboard.

ci_mode.authentication.password : bauhaus.analysis.config.PasswordString = '$(AXIVION_PASSWORD=)'
The password to access the dashboard as the user specified in username. If unset and when not using the special value anon_auth as username, an interactive password prompt will ask for the password. Note, that you can also use a so-called "token" as password. Tokens can be created on the user preferences page in the dashboard.

ci_mode.authentication.username : str = '$(AXIVION_USERNAME=)'
The username used to authenticate with the Dashboard. If left empty, the name of the current OS user account will be used.
You can use the special value anon_auth to skip authentication. This requires the Dashboard to have the option dashboard2/AuthenticationMethods/DefaultUser in the file dashboard2.config configured.

ci_mode.check_integrity : bool = True
Whether the database's integrity should be checked in each CI execution.

ci_mode.directory : bauhaus.analysis.config.ProjectRelativePath = '$(AXIVION_DATABASES_DIR)'

ci_mode.filename : str | None = None
Name of the database file in the directory. If unset, this defaults to PROJECTNAME.db where PROJECTNAME denotes the option /Project/name. If /Results/Dashboard/database_mode is set to managed_upload, this will only be used for migration purposes and the master database will reside on the Axivion Dashboard server.

ci_mode.provide_ir

Provide an IR in the Axivion Dashboard. If there is no path specified for the IR, this will fall back to /Project/ir.

ci_mode.provide_ir.backup_existing : bool = False
Whether to move `destination` to `destination`.bak if `destination` already exists.

ci_mode.provide_ir.path : bauhaus.analysis.config.ProjectRelativePath | None = None
An optional path to the IR/RFG file to be provided. If unset the IR/RFG specified for the Analysis is used.

ci_mode.provide_ir.provide_in_dashboard : bool = True
If set to true, the IR/RFG will be made available for download in the Axivion Dashboard.

ci_mode.provide_rfg

Provide an RFG in the Axivion Dashboard. If there is no path specified for the RFG, the RFG saved by rule /Analysis/AnalysisControl/SaveRFG will be used. If the provide_in_dashboard option here is enabled and the SaveRFG rule is not enabled, SaveRFG will be implicitly enabled.

ci_mode.provide_rfg.backup_existing : bool = False
Whether to move `destination` to `destination`.bak if `destination` already exists.

ci_mode.provide_rfg.path : bauhaus.analysis.config.ProjectRelativePath | None = None
An optional path to the IR/RFG file to be provided. If unset the IR/RFG specified for the Analysis is used.

ci_mode.provide_rfg.provide_in_dashboard : bool = True
If set to true, the IR/RFG will be made available for download in the Axivion Dashboard.

dashboard_url¶

dashboard_url : str = '$(AXIVION_DASHBOARD_URL)'

Dashboard server URL of running dashboard. This is used for example in a local build to download a reference version, and during database import to inform the dashboard and send mails.

This option can be configured to an empty string, which will disable the dashboard integration.

Note: When overriding this option, it is recommended to not set a URL directly, but set it as the default value of the variable expansion $(AXIVION_DASHBOARD_URL=my_url). This is required for compatibility with the IDE plugins, which use this variable to override the URL.

database_mode¶

database_mode : DatabaseMode = 'shared_database'

The Dashboard server supports different methods for transferring analysis results from clients to the server. This option allows you to switch between the modes shared_database (default) and managed_upload (recommended for new projects and also the default when using the Project Wizard from version 7.10 onwards).

shared_database: Results are stored in a SQLite database on your local disk. Note that you have to use a network file system in case your Dashboard server is running on a different host than the one on which the analysis results are created.
If you choose this setting, do not forget to also configure the location where the database is to be placed (and accessed by the Dashboard server) via the setting ci_mode.directory.
managed_upload: Results are stored in a dedicated folder on the host where the Dashboard server is running. The folder, named artifacts, is located within the Dashboard configuration directory. The data are transferred chunk-wise from the host running axivion_ci to the host running the Dashboard server using HTTP(s) requests.
In order for this to work, you need to set the option dashboard_url, specifying the URL of the host running the Dashboard server. In addition, user credentials must be supplied through the environment variables AXIVION_USERNAME (storing the name of the user who will access the Dashboard server API through which analysis results are transferred to the server) and AXIVION_PASSWORD (storing the corresponding access token of type Continuous Integration). It is recommended to create a dedicated user, e.g., a user named builduser, whose sole purpose is to provide the necessary credentials. Note that this user needs the permissions Log In and Update Analysis Artifacts.
This option also makes it unnecessary to make analysis projects explicitly known to the Dashboard server. If there is no pre-existing Dashboard project with /Project/name, a new project will automatically be created after analysis results are uploaded for it.
When changing this setting from shared_database to managed_upload, pre-existing files in ci_mode.directory will not be modified by future analysis runs - likewise, the repository for generated files (VCSIntegration Shadow) will not be updated anymore at the old location. The new database will be stored in the directory specified by the setting cache_directory (which defaults to .axivion-cache). It is not necessary to put anything into that cache directory by hand. The required data is either downloaded from the Dashboard server or copied from, e.g., ci_mode.directory. Note that retaining the cache directory and its contents between analysis runs may save a great amount of network traffic and speed up the entire artifact download/upload process in successive runs.
Besides the analysis database, other artifact files, which are described in the following, will also be uploaded through the Dashboard server API.
The options provide_ir and provide_rfg will behave differently: If enabled, the corresponding artifacts are uploaded to the Dashboard server instead of being copied to ci_mode.directory. The options provide_ir.backup_existing and provide_rfg.backup_existing have no effect with managed_upload mode and are ignored.
If you have configured /Project/VCSIntegration/SpecialVCS/Shadow, the repository database file will also be uploaded to the Dashboard server. Accordingly, file shares to synchronize these files are not necessary anymore. Moreover, the options /Project/VCSIntegration/SpecialVCS/Shadow/sourceserver_remote_url and /Project/VCSIntegration/SpecialVCS/Shadow/sourceserver_repository will be ignored.
WARNING Do not delete the database or any other artifact from the old locations before they were uploaded successfully because the new database is only available after the first run. You can verify the successful upload from within the Dashboard Project Management and by looking into the artifacts folder on the Dashboard host file system.
Should you want to switch back from managed_upload mode to shared_database mode, keep in mind that you manually need to ensure that the artifacts are stored at the shared locations again. This can be achieved by either looking up the artifact paths in Dashboard Project Management and manually copying them, or by using the project backup API to download all the project artifacts as an archive, extracting that and putting the artifacts into their old places. The migrated managed_upload project must then be deleted and installed again from ci_mode.directory.

WARNING Before enabling this feature please be aware of the following use-cases that currently are not possible or difficult to realize with managed_upload mode.

cidbman version remove and similar. These commands are still possible, but you will need to manually look up the database path in the UI. There is no API for deriving the database path from the project name and the database path even changes after a successful axivion_ci run.

Also be aware that for the following use-cases it is required that your Dashboard server is running at least version 7.8.0 for managed_upload.

Branching:
With managed_upload mode, branch project creation is done by calling a Dashboard API instead of manually copying the project artifacts. The corresponding Dashboard API was only added with 7.8.0. Please also see the HOWTO on Project Branching for further guidance on the topic.
backups Backup support with managed_upload mode requires a Dashboard server version 7.8.0 or later as the corresponding APIs were only added in that version. Please consult the Dashboard API documentation on how to create and restore project backups.

import_suppressed_issues¶

import_suppressed_issues : bool = False

When this option is selected, issues that are suppressed with AXIVION DISABLE commentary activators are imported into the project database as well. Those issues are then displayed as "suppressed" in the Axivion Dashboard.

Note that excludes (violations from system headers; or paths excluded from analysis) differ from suppressions. Issues in excluded files will never be imported into the dashboard.

limit_violations¶

Report (non-)violation of limits with a status message
The status plugin checks for allowed limits of added and/or removed issues per erosion kind and either displays a success or a failure message on stderr, depending on whether the limits are met or not

limit_violations.architecture_violations

Limits for architecture violations

limit_violations.architecture_violations.added_limit

Maximum of added violations before analysis is a failure

limit_violations.architecture_violations.added_limit.percentage : float | None = None
If set, use this percentage of the total number of violations as limit

limit_violations.architecture_violations.added_limit.value : int | None = None
If set, use this absolute number of violations as limit

limit_violations.architecture_violations.removed_limit

Maximum of removed violations before analysis is a failure

limit_violations.architecture_violations.removed_limit.percentage : float | None = None
If set, use this percentage of the total number of violations as limit

limit_violations.architecture_violations.removed_limit.value : int | None = None
If set, use this absolute number of violations as limit

limit_violations.clones

Limits for clones

limit_violations.clones.added_limit

Maximum of added violations before analysis is a failure

limit_violations.clones.added_limit.percentage : float | None = None
If set, use this percentage of the total number of violations as limit

limit_violations.clones.added_limit.value : int | None = None
If set, use this absolute number of violations as limit

limit_violations.clones.removed_limit

Maximum of removed violations before analysis is a failure

limit_violations.clones.removed_limit.percentage : float | None = None
If set, use this percentage of the total number of violations as limit

limit_violations.clones.removed_limit.value : int | None = None
If set, use this absolute number of violations as limit

limit_violations.cycles

Limits for cycles

limit_violations.cycles.added_limit

Maximum of added violations before analysis is a failure

limit_violations.cycles.added_limit.percentage : float | None = None
If set, use this percentage of the total number of violations as limit

limit_violations.cycles.added_limit.value : int | None = None
If set, use this absolute number of violations as limit

limit_violations.cycles.removed_limit

Maximum of removed violations before analysis is a failure

limit_violations.cycles.removed_limit.percentage : float | None = None
If set, use this percentage of the total number of violations as limit

limit_violations.cycles.removed_limit.value : int | None = None
If set, use this absolute number of violations as limit

limit_violations.dead_code

Limits for dead code

limit_violations.dead_code.added_limit

Maximum of added violations before analysis is a failure

limit_violations.dead_code.added_limit.percentage : float | None = None
If set, use this percentage of the total number of violations as limit

limit_violations.dead_code.added_limit.value : int | None = None
If set, use this absolute number of violations as limit

limit_violations.dead_code.removed_limit

Maximum of removed violations before analysis is a failure

limit_violations.dead_code.removed_limit.percentage : float | None = None
If set, use this percentage of the total number of violations as limit

limit_violations.dead_code.removed_limit.value : int | None = None
If set, use this absolute number of violations as limit

limit_violations.failure_exit_code : int | None = None
If set, exit code to use for analysis run if at least one limit is exceeded.

limit_violations.failure_message : str = 'Analysis Status: FAILURE'
Message to output on stderr if at least one limit is exceeded.

limit_violations.metric_violations

Limits for metric violations

limit_violations.metric_violations.added_limit

Maximum of added violations before analysis is a failure

limit_violations.metric_violations.added_limit.percentage : float | None = None
If set, use this percentage of the total number of violations as limit

limit_violations.metric_violations.added_limit.value : int | None = None
If set, use this absolute number of violations as limit

limit_violations.metric_violations.removed_limit

Maximum of removed violations before analysis is a failure

limit_violations.metric_violations.removed_limit.percentage : float | None = None
If set, use this percentage of the total number of violations as limit

limit_violations.metric_violations.removed_limit.value : int | None = None
If set, use this absolute number of violations as limit

limit_violations.style_violations

Limits for style violations

limit_violations.style_violations.added_limit

Maximum of added violations before analysis is a failure

limit_violations.style_violations.added_limit.percentage : float | None = None
If set, use this percentage of the total number of violations as limit

limit_violations.style_violations.added_limit.value : int | None = None
If set, use this absolute number of violations as limit

limit_violations.style_violations.removed_limit

Maximum of removed violations before analysis is a failure

limit_violations.style_violations.removed_limit.percentage : float | None = None
If set, use this percentage of the total number of violations as limit

limit_violations.style_violations.removed_limit.value : int | None = None
If set, use this absolute number of violations as limit

limit_violations.success_message : str = 'Analysis Status: SUCCESS'
Message to output on stderr if all criteria are met.

local_mode¶

Options that only apply to the local build and override the corresponding options of the ci_mode.

local_mode.authentication

The credentials for connecting to the dashboard.
In case of the local build, you will need credentials to download a reference version where regular user credentials are usually sufficient. When triggering the local build via one of our IDE plugins, you do not need to configure anything here, as the IDE plugin will forward the necessary credentials.

local_mode.authentication.passfile : bauhaus.analysis.config.PythonOnlyPlainPath | None = '$(AXIVION_PASSFILE=)'
If passfile is set and points to an existing file, behavior of input password is changed: password then contains an encrypted JSON object which contains the password while the passfile contains the key to decrypt.
Note that the file referenced here will be deleted after use for security reasons.

Do not change from the default value unless the implications are well understood; doing so may break your communication with the dashboard.

local_mode.authentication.password : bauhaus.analysis.config.PasswordString = '$(AXIVION_PASSWORD=)'
The password to access the dashboard as the user specified in username. If unset and when not using the special value anon_auth as username, an interactive password prompt will ask for the password. Note, that you can also use a so-called "token" as password. Tokens can be created on the user preferences page in the dashboard.

local_mode.authentication.username : str = '$(AXIVION_USERNAME=)'
The username used to authenticate with the Dashboard. If left empty, the name of the current OS user account will be used.
You can use the special value anon_auth to skip authentication. This requires the Dashboard to have the option dashboard2/AuthenticationMethods/DefaultUser in the file dashboard2.config configured.

local_mode.check_integrity : bool = False
Whether the database's integrity should be checked in each CI execution.

local_mode.directory : bauhaus.analysis.config.ProjectRelativePath = '/home/builduser/.bauhaus/localbuild/projects'

local_mode.filename : str | None = None
Name of the database file in the directory. If unset, this defaults to PROJECTNAME.db where PROJECTNAME denotes the option /Project/name. If /Results/Dashboard/database_mode is set to managed_upload, this will only be used for migration purposes and the master database will reside on the Axivion Dashboard server.

local_mode.provide_ir

Provide an IR in the Axivion Dashboard. If there is no path specified for the IR, this will fall back to /Project/ir.

local_mode.provide_ir.backup_existing : bool = False
Whether to move `destination` to `destination`.bak if `destination` already exists.

local_mode.provide_ir.path : bauhaus.analysis.config.ProjectRelativePath | None = None
An optional path to the IR/RFG file to be provided. If unset the IR/RFG specified for the Analysis is used.

local_mode.provide_ir.provide_in_dashboard : bool = True
If set to true, the IR/RFG will be made available for download in the Axivion Dashboard.

local_mode.provide_rfg

Provide an RFG in the Axivion Dashboard. If there is no path specified for the RFG, the RFG saved by rule /Analysis/AnalysisControl/SaveRFG will be used. If the provide_in_dashboard option here is enabled and the SaveRFG rule is not enabled, SaveRFG will be implicitly enabled.

local_mode.provide_rfg.backup_existing : bool = False
Whether to move `destination` to `destination`.bak if `destination` already exists.

local_mode.provide_rfg.path : bauhaus.analysis.config.ProjectRelativePath | None = None
An optional path to the IR/RFG file to be provided. If unset the IR/RFG specified for the Analysis is used.

local_mode.provide_rfg.provide_in_dashboard : bool = True
If set to true, the IR/RFG will be made available for download in the Axivion Dashboard.

6.3.2.2. Option Types¶

These types are used by options listed above:

DatabaseMode¶

An enumeration.

shared_database

CI writes database to specified folder, dashboard reads from there.

managed_upload

CI uses HTTP(S) to upload database, location is managed by dashboard.

Axivion Suite 7.12.0

Navigation