TeamCity Server Logs
TeamCity Server keeps a log of internal activities that can be examined to investigate an issue with the server behavior or get internal error details.
The logs are stored in plain text files in a disk directory on the TeamCity server machine (usually in <TeamCity Server home>/logs
). The files are appended with messages when TeamCity is running.
While the server is running, the logs can be viewed in the web UI on the Server Logs
tab of Administration | Diagnostics section.
General Logging Description
TeamCity uses log4j 2.x library for the logging and its settings can be customized. Versions prior to TeamCity 2022.04 used Log4j 1.x for the logging.
By default, log files are located under the <TeamCity Server home>/logs
directory.
The most important log files are:
| General server log |
| Log of user-initiated and main build-related events |
| Log of VCS-related activity |
| Contains clean-up-related log |
| Contains Commit Status Publisher-related log. Apply the |
| Notifications-related log |
| Pull Requests-related log. Apply the |
| (off by default) Cloud-integration-related log |
| (off by default) Log of SQL queries, see details |
| (off by default) Log with messages related to NTLM and other authentication for HTML requests |
| (off by default) Log of messages sent by the server to agents and IDE plugins via XML-RPC |
| (off by default) Log related to individual file content requests from VCS |
| (off by default) REST-API related logging |
| (off by default) Notification templates processing-related logging |
| (off by default) Logging related to agent push operations |
| (off by default) Logging related to personal builds processing on the server |
| (off by default) SVN integration log |
| (off by default) TFS integration log |
| (off by default) StarTeam integration log |
| (off by default) ClearCase integration plugin log |
| LDAP-related log |
| NuGet-related log |
| (off by default) logs of back-up/ restore/ migration performed with maintainDB tool |
| (off by default) contains extended information on possible data truncation during back-up/ restore/ migration performed with maintainDB tool |
| (off by default) contains information on synchronization of the project settings with the version control |
| logs related to communication between browsers and the TeamCity server using the WebSocket connection |
| logs related to communication between TeamCity and configured issue tracker |
Other files can also be created on changing Logging Configuration.
Some of the files can have .N
extensions — that are files with previous logging messages copied on main file rotation. See <DefaultRolloverStrategy/>
for preserving more files.
Logging-related Diagnostics UI
Users with System Administrator role can view and download the server logs right from the TeamCity UI using Administration | Diagnostics | Server Logs.
Changing Logging Configuration
While TeamCity is running, active logging settings can be changed by selecting between available logging presets.
The active logging preset is changed in the Administration | Diagnostics | Troubleshooting | Debug logging section. Choosing a preset changes logging configuration immediately, and the preset is preserved after a server restart, until manually changed on this page again. It is strongly advised to return to the Default preset once the necessary logs were collected.
The available presets are stored in the files with the .xml
extension under the <TeamCity Data Directory>/config/_logging
directory. New files can be added into the directory and existing files can be modified (using the .dist
convention). New presets can also be uploaded via Diagnostics | Logging Presets.
If it is not possible to enable debug logging mode via logging presets (for example, to get the logging during server initialization) or to make persistent changes to the logging, you can back up the conf/teamcity-server-log4j.xml
file and copy/rename the <TeamCity Data Directory>/config/_logging/debug-general.xml
file over conf/teamcity-server-log4j.xml
before the server start.
Changing Logging Settings
If you want to fine-tune the log4j configuration, you can edit <TeamCity Server home>/conf/teamcity-server-log4j.xml
file. If the server is running, the log4j configuration file will be reloaded automatically and the logging configuration will be changed on the fly (some log4j restrictions still apply, so for a massive change consider restarting the server).
If you change settings in other preset files, like debug-all.xml
or debug-vcs.xml
, the settings won't be picked up automatically. To enforce the change, switch logging preset to some other value, like <Default>
and then switch back to debug-all
.
Most useful settings of log4j configuration:
To change the minimum log level to save in the file, tweak the level
attribute of the Logger
element.
The logs are rotated by default. When debug is enabled, it makes sense to increase the max
attribute of <DefaultRolloverStrategy/>
element to affect the number of preserved log files. While doing so, ensure there is sufficient free disk space available.
For detailed description of <DefaultRolloverStrategy/>
and other supported attributes, see RollingFileAppender in Apache documentation.
Reading Logs
Each message has a timestamp and level (ERROR
, WARN
, INFO
, DEBUG
).
Example:
ERROR
means an operation failed and some data was lost or action not performed. Generally, there should be no ERRORs in the log.WARN
generally means that an operation failed, but will be retried or the operation is considered not important. Some amount of WARNs is OK. But you can review the log for such warnings to better understand what is going OK and what is not.INFO
is an informational message that just reports on the current activities.DEBUG
is only useful for issue investigation, for example, to be analyzed by TeamCity developers.
General Logging Configuration
By default, TeamCity searches for log4j configuration in the .../conf/teamcity-server-log4j.xml
file (this resolves to <TeamCity Server home>/conf/teamcity-server-log4j.xml
for TeamCity .exe
and .tar.gz
distributions when run from bin
). If no such file is present, the default log4j configuration is used. The logs are saved to the ../logs
directory by default.
If necessary, you can change the path to the configuration by adding the log4j2.configurationFile
JVM option or internal property. The path to the logs
directory is configured via the TEAMCITY_LOGS_PATH
environment variable, or, alternatively, via the teamcity_logs
JVM option or internal property.
For example: log4j2.configurationFile=file:../conf/teamcity-server-log4j.xml
and teamcity_logs=../logs/
.
Default values can be looked up in the bin/teamcity-server
script available in the .exe
and tar.gz
distributions.
If you start TeamCity by the means other than the bundled teamcity-server
or runAll
scripts, make sure to pass the above-mentioned options to the server JVM. See also the recommendations on installing TeamCity into not bundled web server.
The default teamcity-server-log4j.xml
file content can be found in the .exe
and tar.gz
distributions. The one with debug enabled can be found under <TeamCity Data Directory>/config/_logging/debug-general.xml
name after server's first start.