Waiting for Build Statistics to be published

Since tcWebHooks version 2.0.2

If we want to see build statistics in a webhook payload, we might find that some statistics are missing due to the way statistics are processed by TeamCity.

When a build runs, build statistics are generated by the build. Typical examples are as follows:

• Insert examples here

Some of these values may take a while to be analysed and TeamCity will process them in a different tread to the build. Therefore, some statistics can be published after the build has finished.

tcWebHooks listens for a buildFinsihed event, and uses that to trigger webhook execution for the following states:

• build failed
• build successful
• build fixed
• build broken

If we want the webhook to wait until all the required statistics are published we can enable the Build Statistics Collator.

How the Build Statistics Collator works

The Build Statistics Collator starts a cache to hold published statistics. When a build runs a beforeBuildFinished event is emitted by TeamCity when the build has completed but before any cleanup tasks are executed.

tcWebHooks listens for this event, and then checks if a webhook is configured for one of the buildFinished states (listed above). If so, the webhook parameters are then checked and if a parameter named waitForBuildStatistics is found it registers this build for deferred processing. If a parameter named requiredBuildStatistics is found in the webhook configuration, then this is added as meta-data to the cache. The requiredBuildStatistics is a comma-delimited list of statistic keys that must be collated.

It then listens for any statisticValuePublished events and adds them to the cache. Once one of the following "completion criteria" are matched, the buildFinished event is fired, and one of the above states will be invoked on the webhook.

Completion Criteria

• The build has completed and all requiredBuildStatistics have been received by the cache.
• It has been failure-timeout seconds since the build was registered for interest.

Enabling Build Statistics collation

For this to be enabled, we need two settings:

1. The Build Statistics Collator service to be started This is a setting that needs to be set once for all builds on TeamCity.
2. WebHooks configured to waitForBuildStatistics. This is configured for each webhook that must collate statistics before sending the webhook for the build finished states.

Starting the Build Statistics Collator service

Running the collator takes extra resources. It stores details about the build, stores the build statistics, and runs a dedicated thread that checks constantly to see if new statistics need to be collated and notified.

Therefore, the function must be explicitly enabled and teamcity must be restarted for the service to be started. The following configuration must be added to the main-config.xml file on the TeamCity server before restarting TeamCity.

Example minimal configuration

  <webhooks>
	<build-statistics-collator enabled="true" /> 
  </webhooks>

Example full configuration

  <webhooks>
	<build-statistics-collator enabled="true" check-interval="10" failure-timeout="3600" /> 
  </webhooks>

Configuration values

Setting	Default value	Description
enabled	false	Enables the collator engine and starts the running thread
check-interval	10	Interval in seconds to repeatedly check for work and to then collate any outstanding statistics
failure-timeout	3600	Time in seconds to wait from when the build was registered for interest until checking is abandoned

Configuring WebHooks to waitForBuildStatistics

Then we configure specific webhooks to collate statistics, and wait until all the requested statistics have been assembled.
When editing a webhook add at least the following two Parameters:

• waitForBuildStatistics
  This can be any value. It just must be configured as a paramter
• requiredBuildStatistics
  A comma separated list of statistics names that must be published before the webhook will trigger. Don't include spaces, and make sure the case is correct (they are case-sensitive)