报告问题
如果您在运行 TeamCity 时遇到问题,并且认为这些问题与软件有关,请通过联系我们详细描述该问题。
为了解决问题,我们可能需要您的系统的各种信息以及各种日志。 下面的部分解释了如何针对不同的问题收集此类信息。
报告问题时的最佳实践
遵循这些指南将确保及时的响应和有效的问题解决。 请查看 Feedback 以找到合适的联系我们的方式。
提交支持请求时,请包括以下一般信息:
正在使用的 TeamCity版本 ,包括构建编号(这可以在页脚和
teamcity-server.log
中找到)。 同时,也值得包含正在使用的操作系统和 Java 版本。记录任何问题出现的模式(首次出现、重复出现等),如果过去有过缓解,是否有任何最近的环境变化。 具体明确:请记下准确的时间,错误消息,并描述预期和实际的行为。
尽可能包括与 TeamCity UI 相关的 屏幕截图(捕获时始终包括整个页面和浏览器 URL),并提供有关相关设置文件、实际值、REST API 实体表示的详细信息。
当包含错误消息或其他相关文本消息(作为文本,而非作为图片)时,包含完整的消息 以及它在何处被/正在被观察。 如果消息超过几行,将其作为文件附加到工单上。
如果发送超过三个文件,将文件打包成一个单独的档案。
如果您要发送的文件大于 10Mb, 请按照 上传大型数据档案 的指南操作。
针对特定问题的其他有用建议:
如有必要,附加/上传一个包含 TeamCity 服务器日志的存档(请参见 详细信息),理想情况下,整个
<server_home>\logs
目录及其内部的所有目录。 如果不切实际,所有在问题发生时间或之后更新的文件);如果与构建时间或代理行为有关,请附上整个<agent_home>\logs
目录。对于性能/缓慢/延迟问题,请在问题发生时获取一组(10+ 分布在问题时间内的)服务器或代理 thread dumps ,并确保将 dumps 和相关数据一起发送给我们。
请考虑查看问题是否存在于我们的 YouTrack Issue Tracker 中。 我们在此处识别出大多数的错误和边缘条件。 有可能您的问题在较新的 TeamCity 版本中已经得到修复。
如果您的构建逻辑出现问题,请确保这是一个与 TeamCity 相关的问题(也就是说,在没有 TeamCity 的同一环境中无法重现)并包含您调查的详细信息。
在报告构建过程问题时,尝试在代理机器的相同环境中不使用 TeamCity 来重现这些问题,并告知我们结果。
如果特定的构建受到影响,请包含完整的构建日志(通过构建结果的构建日志选项卡上的专用链接下载)。
在替换或遮蔽日志中的敏感数据时,请注意所使用的替换模式。
如果您的系统中安装了防病毒软件,和/或者在 TeamCity 服务器前有网络代理或反向代理,请在您的请求中包含这些信息。
列出所有已安装的非捆绑插件。
请注意之前对 TeamCity Data Directory 或数据库所做的任何修改。
不要在邮件正文中包含大部分(超过10Kb)的文本数据 - 建议以文件形式附加上去。
请参阅以下关于发帖的指南:
当发布有关已报告问题的新详情时,更新主题上的前一个帖子,而不是创建新的帖子。 然而,如果您需要创建一个重复的话题,请务必记下您所发表或发现的所有同一话题的先前帖子。
每次提交只发布一个问题,最重要的问题优先。 如果您确实进行了多次提交,请记下其他相关问题。
请参考下面的章节获取常见的情况和需要收集并发送给我们的特定信息。
性能缓慢、挂起和性能下降
如果 TeamCity 的运行速度比您预期的慢,请按照下面的说明来找出运行缓慢的进程,如果这个进程是 TeamCity 的进程,请把所有相关的细节发送给我们。
确定哪个进程运行缓慢
如果您在使用 TeamCity 网页用户界面时响应速度较慢、检查更改的过程较长、服务器端的源代码检出时间较长、清理时间较长或其他服务器活动较慢,您应该检查安装有 TeamCity 服务器的机器。
如果问题仅与单一构建有关,则您需要排查运行该构建的 TeamCity 代理机器和服务器。
调查系统资源(CPU,内存,IO)的负载。 如果负载过高,请确定导致此问题的进程。 如果这不是与 TeamCity 相关的进程,那可能需要在 TeamCity 范围之外解决。 另外,还需检查如防病毒软件、维护时间等通用的减速原因。
如果是 TeamCity 服务器正在负载 CPU / IO,或者没有显著的 CPU / IO 负载,一切都运行得很好,只有 TeamCity 出了问题,那么这就需要进一步调查了。
检查您的机器上是否有任何冲突的软件,如防病毒软件正在运行。 请考虑暂时禁用它以进行测试,但请确保这不会威胁到您设置的安全。
检查由 TeamCity 使用的数据库以及 TeamCity 数据目录的文件存储是否存在性能问题。
如果您有一个大型的 TeamCity 安装,请首先检查您的 内存设置。
收集数据
在慢速操作中,以 5-10 秒的间隔获取慢进程的多个线程转储(有关线程转储获取方法,请参见下文)。 如果慢的情况持续存在,请再次获取几个更多的线程转储(例如,几分钟内的3-5个),然后在一段时间后重复(例如,10分钟),在此期间,该进程仍然运行缓慢。
然后向我们发送问题的详细描述,并附上线程转储和完整的服务器(或代理)日志以涵盖该问题。 除非出于某种原因不希望这么做,首选的方式是在我们的 问题跟踪器中提交一个问题,并通过支持邮件告知我们。 请包含所有相关的调查细节,包括 CPU / IO 负载信息,具体哪些慢,哪些不慢,记录受影响的 URL,可见的影响等等。 对于大量的数据,使用 我们的文件上传 服务与我们共享档案。
服务器线程转储
当服务器上的操作运行缓慢时,您需要获取一系列服务器线程转储(10+),并在操作缓慢的时间段内进行分析。 TeamCity 会自动保存在超级慢的操作中的线程转储,因此,可能已经有一些保存在 logs / threadDumps - < 日期>
目录中。 建议您把服务器 <TeamCity 安装目录>/logs/threadDumps-<date>
目录中所有近期日期的全部内容打包成档案后发送给我们。
建议您如果挂起是本地发生并且仍能打开 TeamCity 管理 页面,那么通过 Web 用户界面获取 TeamCity 服务器的线程转储:前往 管理 | 服务器Administration | Diagnostics 页面,然后点击 保存线程转储 按钮将转储保存在 <TeamCity 安装目录>/logs/threadDumps-<date>
目录下(之后您可以从 "服务器日志" 下载文件)。 如果服务器已完全启动但网络用户界面无反应,尝试使用您的 TeamCity 服务器的实际 URL 来直接访问 直接 URL。
如果用户界面无法访问(或服务器尚未完全启动),您可以使用下面描述的方法手动进行服务器线程转储。以下。
您还可以调整 teamcity.diagnostics.requestTime.threshold.ms=30000
内部属性 来更改线程转储自动在超时后创建到 TeamCity 日志下的 threadDumps-<日期>
目录中,每当有一个用户发起的网页请求超过了超时时间。
自动获取服务器线程转储
TeamCity 服务器能够按照一些设定的间隔自动获取多个线程转储。 为此,应添加以下 内部属性:
teamcity.diagnostics.periodicThreadDumps.name
- 作为线程转储文件名后缀使用的某个名称teamcity.diagnostics.periodicThreadDumps.count
- 要保存的线程转储数量teamcity.diagnostics.periodicThreadDumps.period.ms
- 等待每个线程转储之间的毫秒数时间
一旦添加了属性,服务器将开始获取线程转储。 所有线程转储将存储在 <TeamCity 安装目录>/logs/threadDumps-<date>
目录下。
代理线程转储
建议您从Web UI获取代理线程转储:转到 Agent 页面,代理概要选项卡,然后使用在代理上转储线程操作。
如果无法访问 UI,您可以使用下述方法手动获取 dump 线程。
获取线程转储
如果您无法通过 TeamCity 网页用户界面获取线程转储,这些可能会有所帮助。
要获取线程转储:
在 Windows 下
您有几个选项:
如果从控制台运行服务器,要获取服务器线程转储,请在控制台窗口中按 Ctrl+Break(有些键盘上是 Ctrl+Pause)(这对于代理程序不起作用,因为其控制台属于启动器进程)。 如果服务器作为服务运行,请尝试以与服务中配置的相同用户身份登录到控制台并执行
<TeamCity服务器主目录>\bin\teamcity-server.bat run
命令。另一种方法是确定 TeamCity 服务器进程的 ID (它是最顶层的 "java" 进程,带有 "org.apache.catalina.startup。 在命令行结束处启动 Bootstrap" 并使用以下方法:
在用于进程的 Java 安装的
bin
目录中运行jstack <pid_of_java_process>
(可以在进程命令行中查找 Java 主目录。 如果安装中没有jstack
工具,您可能需要通过java -version
命令获取 Java 版本,下载相同版本的完整 JDK 并使用其中的jstack
形式。 您也可能需要给命令提供-F
标志。使用 TeamCity-bundled 代理线程转储工具(可以在代理的插件中找到)。 执行以下命令:
<TeamCity agent>\plugins\stacktracesPlugin\bin\x86\JetBrains.TeamCity.Injector.exe <pid_of_java_process>请注意,如果将挂起进程作为服务运行,线程转储工具必须在具有提升权限的控制台上运行(使用以管理员身份运行)。 如果服务是在系统帐户下运行,您可能还需要通过
PsExec.exe
-s <工具的路径>\<工具> <选项>
启动线程转储工具。 当服务在普通用户下运行时,用PsExec.exe -u <用户> -p <密码> <工具路径>\<工具> <选项>
包裹工具调用可能也会有所帮助。
如果这些对作为服务运行的服务器都不起作用,尝试运行服务器从控制台,而不是作为服务。 这样,第一个(Ctrl+Break)选项便可以使用。
在 Linux 下
运行
jstack <pid_of_java_process>
(使用进程使用的 Java 安装中的 jstack)或kill -3 <pid_of_java_process>
。 在后一种情况下,输出将出现在<TeamCity 安装目录>logs/catalina.out
或<TeamCity agent home>/logs/error.log
。
参见上面的 服务器性能 部分。
数据库相关的减速
当服务器运行缓慢时,请检查问题是否由数据库操作引起。建议使用专用于数据库的工具。
您也可以使用 debug-sql
服务器 日志预设。 启用后,所有耗时超过1秒的查询都将被记录到 teamcity-sql.log
文件中。 时间可以通过设置 teamcity.sqlLog.slowQuery.threshold
内部属性 来更改。 该值应以毫秒为单位设定,默认为 1000。
MySQL
除了服务器线程转储外,还请确保附上在 MySQL 控制台中执行的 show processlist;
SQL 命令的输出结果。 就像线程转储一样,如果出现了缓慢的情况,多次执行命令并将输出结果发送给我们是有意义的。 另外,MySQL 可以设置为记录与 my.ini
中的更改执行的长时间查询的日志:
日志也可以发送给我们进行分析。
内存溢出问题
如果您发现 TeamCity 占用过多内存,或者在日志中出现 "OutOfMemoryError" / "Java heap space" 错误,请执行以下操作:
确定哪个过程遇到了错误(实际的构建过程, TeamCity 服务器,或者 TeamCity 代理)。 您可以通过 TeamCity 网页用户界面的 管理 | 服务器Administration | Diagnostics 页面上的图表来跟踪 TeamCity 的内存和 CPU 使用情况。
如果问题出在服务器端,请检查您是否已经从默认设置中提高了内存设置,以便在生产环境中使用服务器(请参见 部分)。
如果问题出在构建过程一侧,请在构建运行程序中设置 "JVM 命令行参数" 设置。 增加
-Xmx
JVM 选项的值:例如,-Xmx1200m
。 请注意,Java Inspections 构建可能需要特定地增加-Xmx
值。如果问题出在 TeamCity 服务器端,且增加内存大小并未解决问题,请向我们报告此情况以供我们调查。 为此,当服务器在内存消耗方面比较高时,按照上述方法获取多个服务器线程转储,获取内存转储(见下文)和包括
threadDumps-*
子目录在内的所有服务器日志,存档结果,并将它们发送给我们以供进一步分析。 确保在获取转储前,-Xmx
的设置少于 8Gb:如果内存转储(
hprof
文件)会自动创建,那么java_xxx.hprof
文件将在进程启动目录(<TeamCity 安装目录>/bin
或<TeamCity 代理 home>/bin
)中创建;对于服务器,您也可以在内存使用率达到峰值时手动获取内存转储。 请到您的 TeamCity UI 的管理 | 服务器Administration | Diagnostics页面,然后点击转储内存快照。
另一种手动获取内存转储的方法是使用与进程使用的 Java 相同版本的完整 JVM 安装的标准 JVM 命令行工具
jmap
。 示例命令行是:jmap -dump:file=<file_on_disk_to_save_dump_into>.hprof <pid_of_the_process>
"打开的文件过多"错误
确定该问题在哪台计算机上发生
确定已打开大量文件的进程及文件列表(在 Linux 上使用
lsof
,在 Windows 上您可以使用 handle 或 TCPView 来列出套接字)如果数字在千以下,请检查操作系统和文件句柄的进程限制(在 Linux 使用
ulimit -n
),如有必要,请增加它们。 请注意,对于像 TeamCity 这样的服务器应用程序来说,Linux 默认的每个进程 1024 个句柄实在是太少了。 将数字增加到至少 16000。 更改后请检查实际过程限制,因为在 OS 中,全局和每次会话限制的设定存在差异(例如,请看帖子)。
如果文件数量众多且看起来可疑,且锁定进程是 TeamCity 进程(没有其他网络应用正在运行的 TeamCity 代理或服务器),那么,在问题仍在发生时,隔几分钟抓取几次打开句柄的列表,并将结果连同相关详细信息一起发送给我们进行调查。
请注意,调查后,您可能需要重新启动出现错误的机器,以恢复应用程序的正常运行。
代理无法连接到服务器
请参阅 常见问题。
记录事件
TeamCity 服务器和代理会生成日志,这些日志可以用来调查问题。
要获取详细信息,请参考相应的章节:
版本控制调试日志
大多数 VCS 操作都发生在 TeamCity 服务器上,但如果您正在使用 代理端签出(agent-side checkout),则 VCS 检出会在构建代理上进行。
对于代理和服务器,您可以在 <TeamCity 安装目录>/conf/teamcity-server-log4j.xml
或者 <BuildAgent home>/conf/teamcity-agent-log4j.xml
文件中手动修改 Log4j 配置,以包含以下片段:
确保更新 <appender name="ROLL.VCS">
节点以增加要存储的文件数量:
如果针对特定版本控制有单独的日志选项,那么它们会在下面进行说明。
Subversion 调试日志
对于代理端日志记录,也需要一个替代的手动方法。
首先,启用通用 VCS 调试记录,正如上文所描述的那样。
在服务器和代理(如果使用了 代理端签出(agent-side checkout))上,取消对 Log4j 配置文件中的 SVN 相关部分( SVN.LOG
appender 和 javasvn.output
类别)的注释。 日志将保存到 logs/teamcity-svn.log
文件中。 通用 VCS 日志也应从 logs/teamcity-vcs.log
中获取。
ClearCase
取消 <TeamCity 安装目录>/conf/teamcity-server-log4j.xml
文件中与 Clearcase 相关的行的注释。 日志将会保存至 logs/teamcity-clearcase.log
目录。
补丁应用问题
在使用 服务器端检出 的情况下,可以通过以下方式检索从服务器传递给代理的 "补丁":
将属性
system.agent.save.patch=true
添加到构建配置中。触发构建。 构建日志和代理日志将包含行“补丁已保存到文件 ${file.name} ”。获取文件并将其提供给问题描述。
构建触发器调试日志
要收集 TeamCity 2021.1 及更高版本中的所有构建触发器调试日志,请在 Administration | Diagnostics 页面 上切换日志预设到 debug-triggers
,复现问题,然后收集所有的 teamcity-triggers.log
文件。
在 2021.1 之前的 TeamCity 版本中,只能为在特定构建配置中定义的 VCS 触发器启用调试日志记录:
将默认的日志预设文件
<TeamCity 安装目录>/conf/teamcity-server-log4j.xml
另存为其他名称,放在<TeamCity 数据目录>/config/_logging/
目录下。按照以下方式修改结果文件:
向日志中添加一个新的 appender,将 VCS 触发器相关事件记录到一个单独的文件中:
<appender name="ROLL.VCS.TRIGGER" class="jetbrains.buildServer.util.TCRollingFileAppender"> <param name="file" value="${teamcity_logs}/teamcity-vcs-trigger.log"/> <param name="maxBackupIndex" value="20"/> <layout class="org.apache.log4j.PatternLayout"> <param name="ConversionPattern" value="[%d] %6p [%15.15t] - %30.30c - %m%n"/> </layout> </appender>按照以下步骤添加一个名为
jetbrains.buildServer.buildTriggers.vcs.AllBranchesVcsTrigger_<构建配置 id>
的新类别:
<category name="jetbrains.buildServer.buildTriggers.vcs.AllBranchesVcsTrigger_MyBuildConfigurationId"> <priority value="DEBUG"/> <appender-ref ref="ROLL.VCS.TRIGGER"/> </category>注意:在上述示例中,
MyBuildConfigurationId
是我们想要调试的具有 VCS 触发器的构建配置的 ID。将 Administration | Diagnostics 页面 上的日志预设切换为新创建的预设文件。
不需要重新启动服务器。 如果配置正确,TeamCity 将在几分钟内创建 teamcity-vcs-trigger.log
日志文件。 该文件将只包含与所选配置相关的调试日志。
.NET 运行器的日志记录
为了调查与 .NET-related runners 相关的进程启动问题,您需要按照下面的描述启用调试功能。 详细信息将随后打印到构建日志中。 建议不要长时间开启调试日志,并在调查后恢复设置。
启用日志记录的另一种方式如下: 在构建配置或代理上添加 teamcity.agent.dotnet.debug=true
配置参数,然后运行构建。
打开
<agent home>/ 插件 / dotnetPlugin / bin
目录。制作一份
teamcity-log4net.xml
的备份副本。将
teamcity-log4net.xml
替换为teamcity-log4net-debug.xml
的内容。
远程运行问题
从IDE发送到服务器的更改可以在 远程运行 期间从服务器 .BuildServer/system/changes
目录中取回。 定位与您的更改相对应的 <change_number> . 变更
文件(您可以选择最新可用的数字,或者从网页界面推断出更改的 URL)。 该文件以二进制格式包含了补丁。 请将问题描述一起发送。
在 IntelliJ IDEA / 基于平台的 IDE 中进行日志记录
要启用 IntelliJ Platform-based IDE plugin 的调试记录功能,请在 <IDE 主页>/bin/log.xml
文件的 Log4j 配置中包含以下片段。
更改此文件后,重新启动 IDE。 TeamCity 插件的调试日志被保存到 idea-teamcity\*
文件中,并会显示在 IDE 设置 ( <IDE 设置/数据目录>/系统/log
目录)的日志目录中。
在 IDE 中打开"功能记录
在启动 IntelliJ IDEA 之前,添加以下 JVM 选项:
-Dteamcity.activation.debug=true
与 open in IDE 功能相关的日志将会在 IDE 的 console 中显示。
未找到适合远程运行的构建配置
首先,检查您在 IDEA 中的 VCS 设置是否与 TeamCity 中的 VCS 设置相对应。 如果他们不这样做,那么改变它们应该可以解决问题。
其次,检查您预期与您的 IDEA 项目相适应的构建配置是否具有 服务器端 VCS 签出模式 或 代理端签出,而不是手动 VCS 签出模式(由于 TeamCity 必须在 VCS 签出完成后应用该补丁,但它并不知道或管理执行的时间,因此无法为手动签出模式的构建应用个人补丁)。
如果设置相同,且您未使用手动签出模式,但问题仍存在,请执行以下操作:
请向我们提供您的 IDEA VCS 设置和 TeamCity VCS 设置(针对您认为适合您的 IDEA 项目的构建配置)
启用 TeamCity IntelliJ 插件的调试日志(参见 上文)
启用 TeamCity 服务器调试日志(请参见 上文)
在 TeamCity IntelliJ 插件中,尝试启动远程运行构建
请提供来自 TeamCity IntelliJ 插件和 TeamCity 服务器的调试日志。
TeamCity Visual Studio 插件问题
TeamCity 插件日志记录
要从 TeamCity 的 Visual Studio Addin 捕获日志:
定位 Visual Studio 安装目录(下面的示例中的
c:\Program Files (x86)\Microsoft Visual Studio\2017\Common7\IDE
)使用 ReSharper 相关的命令行参数,从命令行运行 Microsoft Visual Studio 可执行文件 (
INSTALLATION_DIRECTORY\Common7\IDE\devenv.exe
):对于作为 ReSharper Ultimate 的一部分的 TeamCity VS Add-in,使用
/ReSharper.LogFile <文件路径>
和/ReSharper.LogLevel <Normal|Verbose|Trace>
开关c:\Program Files (x86)\Microsoft Visual Studio\2017\Common7\IDE>devenv.exe /ReSharper.LogFile C:\Users\jetbrains\Desktop\vs.log /ReSharper.LogLevel Verbose对于 TeamCity VS Add-in 的旧版,使用
/TeamCity.LogFile <文件路径>
和/TeamCity.LogLevel <Normal|Verbose|Trace>
开关
Visual Studio 日志记录
要排查常见的 Visual Studio 问题,请运行 Microsoft Visual Studio 可执行文件 INSTALLATION_DIRECTORY\Common7\IDE\devenv.exe
,并带上 /
日志
命令行开关,然后将生成的日志文件发送给我们。
dotCover 问题
为收集由 JetBrains dotCover 生成的额外日志,将 teamcity.agent.dotCover.log
配置参数 添加到构建配置中。 此参数应存储一个绝对路径或相对路径,指向一个空的代理目录,您希望在该目录中保存 dotCover 日志。 如果您需要将这些日志作为 构建工件 发布,请将相同的目录路径添加到 产物路径 列表中。
JVM 崩溃
在极少数情况下,TeamCity 服务器或代理进程可能会毫无预警地意外终止,这可能是由于 Java 运行时崩溃引起的。
如果发生这种情况,JVM 通常会在进程的工作目录中创建一个名为 hs_err_pid*.log
的文件。 工作目录通常为 <TeamCity 服务器安装目录>/bin
或 <代理主目录>/bin
。
在 Windows 下,作为服务运行时,可能是其他目录,如 C:\Windows\SysWOW64
。 您也可以在磁盘上搜索名称中含有 "hs_err_pid" 的最近文件。 请参阅本文档中相关的致命错误日志部分。
请将此文件发送给我们进行调查,并考虑为 服务器 (或 代理)更新到最新可用的 JVM 版本。
如果您收到 "Java 运行环境无法继续,因为内存不足。 本机内存分配(malloc)未能分配..."消息与崩溃或在崩溃报告文件中,请务必切换到 64 位 JVM或将 -Xmx
设置降低至 1024m
以下,有关详细信息请参阅内存配置部分。
构建日志问题
在调查与构建日志有关的问题时,我们可能需要由 TeamCity 储存的原始二进制构建日志。 可以通过 Web UI 从构建日志构建的标签页下载:选择 "Verbose" 日志详情,并使用右上角的 "raw messages file" 链接。
IntelliJ IDEA 检查
TeamCity 构建的检查结果可能与 IntelliJ IDEA 本地运行的检查结果不匹配。
为了帮助我们调查与检查相关的问题,请执行以下操作:
将
system.teamcity.dont.delete.temp.result.dir=true
添加到 配置参数中在 Artifact paths 中添加
% \system.teamcity.build.tempDir% /inspection*result/** => inspections-reports-data-% \build.number% .zip
规则在 Artifact paths 中添加
% \system.teamcity.build.tempDir% /idea-logs/** => inspections-reports-idea-logs-%build.number%.zip
规则在运行器的 JVM 命令行参数 字段中添加
-Didea.log.path=%system.teamcity.build.tempDir%/idea-logs/
。运行一个新的构建。
向我们发送
inspections-reports-*.zip
文件。
上传大型数据档案
大小在10 MB以下的文件可以直接附加到 跟踪问题 中(如果您不希望附件被公开访问,只需将附件可见性限制为 "teamcity-developers" 用户组)。
您也可以通过电子邮件发送小文件(最大2 MB): teamcity-support@jetbrains.com 或者通过 在线表单 (最大20 MB)。 请不要忘记提及您的 TeamCity 版本和环境,并在附加前归档文件。
大型文件可以通过 https://uploads.jetbrains.com/
上传。 请在上传后告诉我们确切的文件名。
如果您无法一次性上传大文件,请尝试将文件分割成多个部分,然后分别上传。