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:

• ArtifactsSize
• BuildDuration
• BuildDurationNetTime
• BuildTestStatus
• InspectionStatsE
• InspectionStatsW
• TimeSpentInQueue

Some of these values may take a while to be analysed and TeamCity will process them in a different thread 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.

The Build Statistics Collator starts a cache to hold published statistics and reference to the build once it completes. When a build starts, a buildStarted event is emitted by TeamCity.

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.

The following diagram illustrates the points at which a webhook would be triggered. The buildFinished event is only triggered once, at the point in time when the criteria is first met.

Note: Once one of the following criteria are met, the cache will be cleaned up and no further criteria will be evaluated.

Referring to the above diagram, the numbers correspond to the items below:

1. The webhook either has no requiredBuildStatistics defined or all requiredBuildStatistics have been published. As soon as the build finishes the webhook will execute.
2. The webhook has requiredBuildStatistics defined but they had not all been published when the build completed. At this point the build has finished and then any requiredBuildStatistics have also been published. This is the main use case for this feature.
3. The build has finished, but not all requiredBuildStatistics have been published. No further build statistics have been published since the build completed and BuildCompletedTimeout seconds has elapsed since the build completed.
4. The build has finished, but not all requiredBuildStatistics have been published. Some further build statistics have been published since the build completed and BuildCompletedTimeout seconds has elapsed since the last build statistic was published.
5. This is when none of the above criteria have been met and is used to clean up the cache of any outstanding listeners. There are two likely causes for this event to be triggered.
   (a) The buildFinished event was never received from TeamCity. The build may have failed for some unknown reason.
   (b) The build takes longer than failureTimeout seconds to run after the build starts. The default value for failureTimeout is one hour.
   Note: It is highly unlikely that the webhook will be successfully executed for this criteria because the build instance was not stored in the cache, and is therefore not available for the webhooks code to process.

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.

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.

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

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

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)

The following parameters can also be defined. They are used if we want to override the global values for a single webhook.

• buildStatisticsFailureTimeout
  Override the global failure-timeout value above.
• buildStatisticsBuildCompletedTimeout
  Override the global build-completed-timeout value above.