Skip to end of metadata
Go to start of metadata

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.

Enable Debug in Server Logs

Icon

In the web UI, go to Administration | Diagnostics page. On the Troubleshooting tab, choose a logging preset, view logs under Server Logs subsection.
If it is not possible to enable debug logging mode from the TeamCity web UI, refer to Changing Logging Configuration section to learn how to adjust logging options manually.

In this section:

General Logging Description

TeamCity uses log4j library for the logging and its settings can be customized.

By default, log files are located under the <TeamCity Server home>/logs directory.

The most important log files are:

teamcity-server.log

General server log

teamcity-activities.log

Log of user-initiated and main build-related events

teamcity-vcs.log

Log of VCS-related activity

teamcity-cleanup.log

contains clean-up-related log

teamcity-notifications.log

Notifications-related log

teamcity-clouds.log

(off by default) Cloud-integration-related log

teamcity-sql.log

(off by default) Log of SQL queries, see details

teamcity-http-auth.log

(off by default) Log with messages related to NTLM and other authentication for HTML requests

teamcity-xmlrpc.log

(off by default) Log of messages sent by the server to agents and IDE plugins via XML-RPC

vcs-content-cache.log

(off by default) Log related to individual file content requests from VCS

teamcity-rest.log

(off by default) REST-API related logging

teamcity-freemarker.log

(off by default) Notification templates processing-related logging

teamcity-agentPush.log

(off by default) Logging related to agent push operations

teamcity-remote-run.log

(off by default) Logging related to personal builds processing on the server

teamcity-svn.log

(off by default) SVN integration log

teamcity-tfs.log

(off by default) TFS integration log

teamcity-starteam.log

(off by default) StarTeam integration log

teamcity-clearcase.log

(off by default) ClearCase integration log

teamcity-ldap.log

LDAP-related log

teamcity-nuget.log

NuGet-related log

teamcity-maintenance.log

(off by default) logs of back-up/ restore/ migration performed with maintainDB tool

teamcity-maintenance-truncation.log

(off by default) contains extended information on possible data truncation during back-up/ restore/ migration performed with maintainDB tool

teamcity-versioned-settings.log

(off by default) contains information on synchronization of the project settings with the version control

teamcity-ws.log

logs related to communication between browsers and the TeamCity server using the WebSocket connection

teamcity-issue-trackers.loglogs related to communication between TeamCity and configured issue trackers

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 maxBackupIndex 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.

The debug logging can be enabled via "Active logging preset " under the Administration | Diagnostics page, Troubleshooting, Debug logging subsection. Choosing a preset changes logging configuration immediately and the preset is preserved after a server restart, until changed on the page again. It is recommended to return to the "<Default>" once the necessary logs were collected.

Icon

Prior to TeamCity 9.1 the preset was reset to the default on the server restart, see the related issue.

 New presets can also be uploaded via Diagnostics | Logging Presets.

The available presets are configured by the files available under <TeamCity Data Directory>/config/_logging directory with .xml extension. New files can be added into the directory and existing files can be modified (using .dist convention).

Changing Logging Configuration

While TeamCity is running, logging configuration for the server can be switched to a logging preset.

If it is not possible to enable debug logging mode via logging presets (e.g. to get the logging during server initialization) or to make persistent changes to the logging, you can backup 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 (for .war TeamCity distribution, see the related section). 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).

Most useful settings of log4j configuration:
To change the minimum log level to save in the file, tweak the "value" attribute of the "priority" element:


The logs are rotated by default. When debug is enabled, it makes sense to increase the "value" attribute of "maxBackupIndex" element to affect the number of preserved log files. While doing so, please ensure there is sufficient free disk space available.

For detailed description of maxBackupIndex and other supported attributes, see http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/RollingFileAppender.html.

Reading Logs

Each message has a timestamp and level (ERROR, WARN, INFO, DEBUG).

e.g.:

[2010-11-19 23:22:35,657] INFO - s.buildServer.SERVER - Agent vmWin2k3-3 has been registered with id 19, not running a build

ERROR means an operation failed and some data was lost or action not performed. Generally, there should be no ERRORs in the log.

WARNs 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. e.g. 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.

The configuration options values can be changed via the corresponding log4j.configuration and teamcity_logs" JVM options or internal properties.
For example:log4j.configuration=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, please 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. See also sample teamcity-server-log4j.xml file.



See also:

Administrator's Guide: Viewing Build Agent Logs
Troubleshooting: Reporting Issues

2 Comments

  1. If I send an HTTP request to trigger a build (add2Queue) and the user doesn't have permissions to trigger a build in that project, it seems that this is not logged in any of the log files?

    1. This information is not written anywhere with default logging preset. Please, enable "debug-all" preset.