Server Health

Since TeamCity 8.0, the Server Health report is available containing results of the server inspection for any configuration issues which impact or could potentially impact the performance. Such issues, the so called server health items, are collectively reported by TeamCity on the Server Health page in the Administration area.

The Project Administrator Role and Permission at least are required to see the report.

Scope and Severity

The report enables you to define the analysis scope: you can select to analyze the global configuration or report on project-related items. The scope available to you depends on the level of the View Project permission granted to you. Note that the report is not available for archived projects.

The Server Health analysis also employs the severity rating, depending on the issue impact on the configuration of the system on the whole or an individual project.

Visibility Options

By default, the warning and error level results pertaining to the global configuration will be displayed on the report page as well as at the top of each page in TeamCity.

Besides those, some items will be displayed in-place: depending on the object causing the issue, the server health item will be reported on the Build Configuration, Template or VCS root settings page.

Only active items are displayed on the TeamCity pages. To remove an item from display, use the hide option next to an item on the report page. For global items, this option is available in every server health message.

Hidden items will be removed from the TeamCity pages, and will be displayed on the Server Health page below the active items. Their description will be greyed out.

To return an item to display, use the Show option.

The visibility changes will be listed on the Audit page in the Administration area.

Issue Categories

Currently, TeamCity alerts you to the following configuration issue categories:

Global Configuration Items

Since TeamCity 8.1.3, TeamCity displays a notification on the availability of the new TeamCity version and a warning if any of the licenses are incompatible with this new version. The notification is visible to system administrators only and they can use the link in the "Some Licenses are incompatible" message to quickly navigate to the Managing-Licenses page, where all incompatible licenses will have a warning icon.

Critical Errors

This category shows the following errors:

errors in project configuration files - occur if the server detects some inconsistency or a broken configuration while it loads configuration files from the disk
errors raised by TeamCity Disk Space Watcher
warnings from the TeamCity Server TeamCity Memory Monitor

TeamCity will warn you if the server currently uses the internal database. Setting up an External Database.

As Upgrade Notes, a warning message will be displayed if you are using Sybase.

Possible Frequent Clean Checkout

This section of the report will show possible frequent Clean Checkout, which may be caused by the following two reasons:

Custom Checkout Directory

Build configurations having different Configuring VCS Settings but the same Build Checkout Directory may lead to frequent clean checkouts, slowing down the performance and hindering the consistency of incremental sources updates.

Build Files Cleaner (Swabra) Settings

Enabling the Build Files Cleaner (Swabra) build feature in several build configurations may cause extra clean checkouts. This may happen if builds from these configurations alternately run on the same agents and have identical Version Control Settings or the same custom checkout directory specified.

Possible frequent clean checkout (Swabra case) server health report shows such incorrectly set up configurations grouped by Swabra settings.

Configurations with Large Build Logs

Large Build Log (more than 200 MB by default) can reduce the server performance as they could be too heavy to parse and are hard to view in the browser.

The build script can be tuned to print less output if this inspection fails frequently for some Build Configuration.

Unused VCS Roots

TeamCity will show you the VCS Root defined in a project and will offer to delete the unused roots.

Similar VCS roots

TeamCity qualifies VCS Root as identical when their major settings (e.g. URLs, branch settings) are the same even if some of their settings (e.g. user name, password) are different.

The report will show you identical roots and will leave it up to you whether to merge them or not.

Similar VCS Root Usages (AKA instances)

You can define values for VCS Root settings or use parameter references to Configuring Build Parameters.

When the referenced VCS roots parameters are resolved to the same values as the values defined, such cases will be reported as identical VCS root usages.

The general recommendation is to use parameter references for root settings, thus optimizing the amount of VCS roots.

Trigger Rules for Unattached VCS roots

A rule of a Configuring VCS Triggers can reference a VCS root which is not attached to the build configuration. This is often a bug in the settings.

Redundant Trigger

The report will show cases when a build trigger is redundant, for example:

There are two build configurations A and B
A snapshot depends on B
Both have VCS triggers, A with the Configuring VCS Triggers option enabled.

In this case, the VCS trigger in B is redundant and causes builds of A to be put into the queue several times.

Unused Build Agents

The report is displayed for the agents not used for 3 days and more, if

you have more than 3 agents in your environment
your agents have been registered for more than 3 days
if the builds were run on the server during these 3 days

Suggested Settings

Since TeamCity 8.1, TeamCity analyzes the current settings of a build configuration and suggests additional options, e.g. adding a VCS trigger, a build step, etc. Besides the server health report, the suggestions for a specific build configuration are shown right on the configuration settings pages.

Extensibility

The default Server Health report provided by TeamCity might cover either too many, or not all the items required by you. Depending on your infrastructure, configuration, performance aspects, etc. that you need to analyze, a custom Server Health report can be needed. TeamCity enables you to write a Custom Server Health Report which will report on specific items.

Last modified: 20 April 2023