Configuring Change Tracking

3 minute readData analyticsAutomation

Change Tracking must be enabled when CloudBees CD/RO starts for your system to track changes and record the Change History.

By default, Change Tracking is enabled for projects created in CloudBees CD/RO 5.3 or later. It is disabled for projects created in CloudBees CD/RO versions before CloudBees CD/RO 5.3, but can be enabled manually.

Enabling Change Tracking Globally

When installing CloudBees CD/RO:

  1. Add this line to the database.properties file:

    COMMANDER_DB_AUDITING_ENABLED=true
  2. Restart the CloudBees CD/RO server.

Enabling Change Tracking on a Per-Project Basis

Unless the allowEnablingDisablingChangeTrackingProjectLevel setting has been altered, only admin users are allowed to perform this task. The default setting is adminOnly. If the setting is changed to anyoneWithAccess, any user with access to the project can enable or disable Change Tracking for the project

You can enable Change Tracking one of the following ways:

In the CloudBees CD/RO Platform UI

Change Tracking is enabled when the Enable Change Tracking check box is selected.

To disable Change Tracking, click the Enable Change Tracking check box to clear it. and click OK.

Using ectool

  • Enter ectool modifyProject <projectName> --tracked true to enable Change Tracking.

  • Enter ectool modifyProject <projectName> --tracked false to disable Change Tracking.

Using ec-perl:

  • Enter $cmdr→modifyProject(<projectName>, {tracked ⇒ true}); to enable Change Tracking.

  • Enter $cmdr→modifyProject(<projectName>, {tracked ⇒ false}); to disable Change Tracking.

For properties that are frequently updated always to be a numerical value, it is possible to suppress Change Tracking of numerical-value updates by using one of these commands: ectool: ectool modifyProperty <projectName> — path <propertyPath> — counter true

or

ec-perl: $cmdr→ modifyProperty (<projectName>, {path ⇒ <propertyPath>, counter ⇒ true});

When the counter flag is set for a property, Change Tracking does not track changes to the property if the only change was a change in the property value from one numeric value to another. All other forms of changes to the properties that have this flag set are tracked normally.

Reverting an object that owns a counter property to a previous state will revert the value of the counter property to its value at the previous time that a change to this property was tracked–typically this is when its value is initialized. This may not be the desired behavior, so you may need to manually set a counter property if it is reverted.

Upgrading to CloudBees CD/RO 6.x

Change Tracking is enabled when you upgrade to CloudBees CD/RO 6.x. This can significantly increase the time it takes to complete the upgrade.

If you want to upgrade with Change Tracking disabled, add this line to the database.properties file before starting the upgrade:

COMMANDER_DB_AUDITING_ENABLED=false

Customizing the Change History Page

The performance of the Change Tracking feature is affected by number of records in the Change History as well as the number of entries being tracked. For example, a page showing 5000 entries may be slow to load and update and does not provide much useful information.

This CloudBees CD/RO server uses the lowest of the following limits to determine the maximum amount of records to display in the Change History page:

  • Maximum amount of records on the Change History page

    To change the maximum number of records in the Change History page: .. Set the CHANGE_TRACKING_HARD_MAX_RECORDS parameter in the wrapper.conf file to a new value.

    + The default value is 1000.

    1. Restart the CloudBees CD/RO server.

  • Maximum number of records retreived

    Set the TrackingMax Records server setting to a new value not exceeding the CHANGE_TRACKING_HARD_MAX_RECORDS parameter in the wrapper.conf file.

    To set TrackingMaxRecords, do one of the following:

    Change the value in the UI. See the Server Settings page in the automation platform UI.

    Use ectool to change the value. For example, enter the following command to limit the number of records retrieved to 100:

    ectool setProperty /server/settings/changeTrackingMaxRecords --value 100