CDash:Administration

From KitwarePublic
Revision as of 18:32, 18 April 2009 by Jjomier (talk | contribs)
Jump to navigationJump to search

< CDash Main Page

CDash administrator page
CDash administration from the main dashboard

Creating a project

Go to the administrative section of MyCDash (login as administrator) and select [Create new project]. Here’s a description of the fields.

  • Name: Name of the project. CDash allows spaces for the name of the project but it is not recommended. If the project’s name contains space make sure you replace the space by the corresponding HTML entity, i.e. %20.
  • Description: description of the project.
  • Home URL: Home url of the project (with or without http://) . This URL is referred in the top menu of the dashboard for this project.
  • CVS/SVN Viewer URL: URL of the CVS/SVN viewer
  • CVS/SVN View Type: Current CDash supports ViewCVS, Trac, Fisheye, ViewVC, WebSVN and CVSTrac as CVS/SVN viewers. Select the appropriate viewer depending on your current configuration.
  • CVS/SVN repository: In order to get the daily updates, CDash should be able to access the current repository. It is recommended to use the anonymous access, for instance :pserver:anoncvs@myproject.org:/cvsroot/MyProject. If the project needs ssh access, make sure that the user running the webserver running CDash as the proper ssh keys. CDash doesn’t store any passwords.
  • Bug tracker URL: URL of the bug tracker for this project
  • Documentation URL: URL of the documentation for this project
  • Logo: small logo for this project. It is recommended to upload a transparent gif to blend with CDash’s banner. The height of the image shouldn’t be more than 100 pixels an optimized look. Project logos are stored in the database directly.
  • Public dashboard: if the box is checked that means that the dashboard is public and anybody can access the dashboard, claim sites and look at the current status. By default dashboards are private.
  • Coverage threshold: CDash marks the coverage has passed (green) if the global coverage for a build or specific files is above this threshold. It is recommended to set the coverage threshold to a high value and decrease it when the coverage is getting higher.
  • Nightly start time: CDash displays the current dashboard using a 24hours window. The nightly start time defines the beginning of this window. Note that the start time is expressed in the form HH:MM:SS TZ, i.e. 21:00:00 EDT.
  • Google Analytics Tracker: CDash supports visitor tracking through Google analytics. See “Adding Google Analytics” for more information.
  • Enable test timing: Enable/Disable test timing for this project

For more information about test timing see the Test Timing section.

  • Test time standard deviation: Set a multiplier for the standard deviation for a test time. If the time for a test is higher than mean+multiplier*standarddeviation, the test time status is marked as failed. Default is 4 if not specified. Note that changing this value doesn’t affect previous builds but only builds submitted after the modification.

For more information about test timing see the Test Timing section.

  • Test time standard deviation threshold: Set a minimum standard deviation for a test time. If the current standard deviation for a test is lower than this threshold then the threshold is used instead. This is particularly important, for tests that have a very low standard deviation but still some variability. Default threshold is set to 2 if not specified. Note that changing this value doesn’t affect previous builds but only builds submitted after the modification.

For more information about test timing see the Test Timing section.

  • Email broken submission: Enable/Disable sending email for broken submissions for this project. This is a general feature.
  • Email build missing: Enable/Disable sending email when a build has not submitted. This feature is currently not implemented.
  • Email low coverage: Enable/Disable sending email when the coverage for files is lower than the default threshold value specified above.
  • Email test timing change: Enable/Disable sending email when a test timing has changed. This feature is currently not implemented.
  • Download CTest config: Automatically generated CTest configuration file. downloading this file and putting it at the root of your project, allows to quickly get started with CTest/CDash and submitting to the dashboard.

Editing a project

To edit the current configuration for a project.

  1. Log in as project administrator
  2. Select [edit project] in the administration section.
  3. If you have more than one project hosted on CDash, select the project you want to modify.

In order to update the current project’s logo.

  1. Log in as project administrator
  2. Select a new image file by clicking on the "Browse" button
  3. Click “Update Project”.

See the section Creating a project for more information.

Test Timing

See Test timing for more information.

Recompute test timing

If you just upgraded CDash, you might notice that the current submissions are showing a high number of failing test due to time defects. This is due to the fact that CDash doesn’t have enough sample points to compute the mean and standard deviation for each test, and particularly the standard deviation might be very small (actually zero for the first samples).

It is recommended to turn the “enable test timing” to off (see edit project section) for about a week (or until you get enough build submissions and CDash has an approximated mean and standard deviation for each test time.

The other option is to force CDash to compute the mean and standard deviation for the test for the past X days. Be warned that this process might take a long time depending on the number of test and projects involved. In order to recomputed the test timing, go to the [backward compatibility tools] in the administration section and specify the number of days (default is 4) and click on “Compute test timing”. When the process is done the new mean, standard deviation and status should be updated for the tests submitted during this period.

Adding Google Analytics

In order to get a Google analytics account:

  1. First go to http://www.google.com/analytics/indexu.html
  2. If you don't have an account, set one up.
  3. Then, add a website profile.
  4. On CDash, login and edit your project
  5. Add the code you get from google into the Google Analytics Tracker (i.e. UA-43XXXX-X) for your project.

Project Roles

CDash support three levels of roles for users: Normal user, Site maintainer and Project administrator.

  • Normal users are regular users with read and/or write access to the project’s code repository.
  • Site maintainers are responsible for periodic submissions to CDash.
  • Project administrators have reserved privileges to administer the project in CDash.

The first two levels can be defined by the users themselves. Project administrators access has to be granted by another administrator of the project or CDash’s administrator.

CDash role management page

In order to change a current role for a user:

  1. Select [Manage project roles] in the administration section.
  2. Then, if you have more than one project, select the appropriate project.
  3. In the “current users” section change the role for a user
  4. Click “update” to update the current role
  5. In order to remove completely a user from a project, click “remove”

If the cvs login is not correct it can also be changed from this page. Note that users can also change their CVS login manually from their profile.

In order to add a current role for a user:

  1. Select [Manage project roles] in the administration section.
  2. Then, if you have more than one project, select the appropriate project.
  3. In the “Add new user” section type the first letters of the first name, last name or email address of the user you want to add. Or type ‘%’ in order to show all the users registered in CDash.
  4. Select the appropriate user’s role
  5. Optionally put the user’s cvs login
  6. Click on “add user”

Importing from CVS users file

In some cases, it is useful to batch import a list of current users for a project. In order to import:

  • Click on [manage project role] in the administration section
  • Select the appropriate project (if more than one)
  • Click “Browse” to select a CVS users file.
The current file should be formatted as follow: 
 cvsuser:email:FirstName LastName
  • Click “import”
  • Make sure the reported names and email address are correct and deselect the ones that shouldn’t imported and click on “Register and send email”. This will automatically register the users, set a random password and send a registration request to the appropriate email addresses.

Build Groups

(also called tracks in Dart2)

Builds can be organized by groups. In CDash, three groups are defined automatically and cannot be removed: Nightly, Continuous and Experimental. These groups are the same imposed by CTest.

Each group has a description associated with it that is displayed when clicking on the name of the group on the main dashboard. In order to change the description see the section update group description below.

CDash group management page

Adding a new group

  1. Click on [manage project groups] in the administration section
  2. Select the appropriate project (if more than one)
  3. Under the “create new group” section enter the name of the new group
  4. Click on “create group”

Newly create group appears at the bottom of the current dashboard. In order to reorder the groups, see the next section.

Turning on Summary email (CDash 1.2)

In CDash 1.2, the ability to send summary email for specific groups has been added. One email is sent when the first build of a group fails, and a link to the current dashboard is sent.

Ordering groups

  1. Click on [manage project groups] in the administration section
  2. Select the appropriate project (if more than one)
  3. Under the “Current Groups” section, click on the [up] or [down] links.

Note: the order displayed in this page is exactly the same at the order on the dashboard.

Update group description

  1. Click on [manage project groups] in the administration section
  2. Select the appropriate project (if more than one)
  3. Under the “Current Groups” section, update or add a description in the field next to the [up][down] links.
  4. Click “Update Description” in order to commit your changes.

Move builds to another group

By default builds are going to the group associated with the build type defined by CTest, i.e. a nightly build will go in the nightly section. There are two ways to move a group into the proper group and define a rule, such that if a same build is submitted it goes to the appropriate group: Global Move and Single Move.

CDash matches the builds by Name, Site, and Build Type. For instance if the build named “Linux-gcc-4.3” from the site “midworld.kitware” is a nightly build it will be move to the nightly section unless a rule on “Linux-gcc-4.3”-“midworld.kitware”-Nightly is defined.

Global Move

Global move allows to move builds as a batch.

  1. Click on [manage project groups] in the administration section
  2. Select the appropriate project (if more than one)
  3. Under “Global Move” you will see a list of all the builds submitted in the past 7 days. (without duplicates). Note that expected builds are also shown, even if they have not been submitting in the past 7 days.
  4. You can narrow your search by selecting a specific group (default is All).
  5. Select the builds to move. Hold “shift” in order to select multiple builds.
  6. Select the target group. This is mandatory.
  7. Optionally check the “expected” box if you expect the builds to be submitted on a daily basis. For more information on expected builds see the “Expected builds” section below.
  8. Click “Selected Builds to Group” to move the groups.

Single Move

From the main dashboard page, if logged as administrator of the project, a small folder icon will be present next to each build. Clicking on the icon will show some option for this build. In particular users are able to mark a build as expected (see section below) and move a build to a particular group or delete a bogus build.

Expected builds

Project administrators can mark certain builds as expected. That means builds are expected to submit daily. This allows to quickly check if a build has not been submitting on today’s dashboard or even by clicking on the info icon on the main dashboard to quickly assess for how long the build as been missing.

CDashExpectedAjax.jpg

Note: CDash is going to send email when a build is missing in the near future. This feature is not currently implemented (in 1.0)

Logging management

CDash supports internal logging mechanism using the error_log() function from PHP. Most of the critical SQL queries (almost all the queries) are logged if an error occurs. By default CDash log file is located in the $CDASH_BACKUP_DIRECTORY as cdash.log. Note that CDash doesn’t perform any log rotation. The location of the log file can be modified by changing the $CDASH_LOG_FILE variable in the config.php configuration file.

The log file can be access directly from CDash if the log file is in the standard location.

  1. Log into CDash as administrator
  2. Click on [CDash logs] in the administration section
  3. Click on cdash.log to see the log file.

For developers, these two functions should be used to add logging mechanism into CDash. 

 function add_log($text,$function)
 function add_last_sql_error($functionname)

Backup mechanism

CDash backups all the XML submissions for a certain period of time. The default timeframe is 48hours. The timeframe can be changed in the config.php file using the $CDASH_BACKUP_TIMEFRAME variable.

Note 1: If projects are private it is recommended to set the backup directory outside of the apache root directory to make sure that nobody can access the XML files.

Note 2: The backup directory is emptied only when a new submission arrives.

Importing from backups

If necessary, CDash can automatically import builds from the Backup directory.

  1. Log into CDash as administrator
  2. Click on [Import from backups] in the administration section
  3. Click on “Import backups”.

Import Dart1 files

CDash supports importing from Dart1. CDash doesn’t support from Dart2 because Dart2 doesn’t have any ways to export the database as XML (as far as we know).

  1. Log into CDash as administrator
  2. Click on [Import Dart1 Files] in the administration section
  3. Select the project to import to
  4. Select the path to the Dart1 "Sites" directory for the project on the server. Note that the filesystem should be accessible from the webserver user.
  5. Select the appropriate date range
  6. Click on import

Note that the import mechanism might take a long time.

Maintenance Tools

Several tools are provided for backward compatibility and administrative purposes.

Assign builds to default group

If some builds are not assign to any groups for some unknown reasons (this should be really rare), you can assign the builds to their group based on their build type (Nightly, Experimental or Continuous).

Fix build groups based on build rules

If some group rules are defined but the builds are not going to the proper group (this should be really rare), you can fix this by running this script.

Delete builds with wrong dates

Some builds might be coming into CDash with the wrong date, because either the date in the XML file is not correct or the timezone is not recognized by CDash (mainly by PHP). These builds will not show up in any dashboard because the starting time is bogus. It is recommended to delete these builds.

First check if you have any bogus build by selecting the [check builds], then delete the builds by selecting [Delete builds].

Compute test timing

See the recomputed test timing section for more information.

Upgrade CDash

See the upgrade CDash section for more information.

Automatic removal of builds

As of version 1.4, CDash allows the automatic removal of builds in order to keep the database to a reasonable size. There are two ways to setup the automatic removal:

  • Without cronjob. Just edit the config.local.php (or config.php) and set the
 $CDASH_AUTOREMOVE_BUILDS='1';

This will automatically remove builds on the first build of the day (which might not be optimal).

  • With cronjob:
 0 6 * * 0 php5 /var/www/CDash/autoRemoveBuilds.php all
Retrieved from "https://public.kitware.com/Wiki/index.php?title=CDash:Administration&oldid=15053"