报告问题

遵循这些指南将确保及时的响应和有效的问题解决。 请查看 Feedback 以找到合适的联系我们的方式。

note

在建议改进或功能请求时，请描述 为什么您需要该功能以及您希望实现的 原始目标。 对于您希望如何看到该功能被实现的 建议也同样受到欢迎。

提交支持请求时，请包括以下常规信息:

• 正在使用的 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 来 重现这些问题，并告知我们结果。

• 如果特定构建受到影响，请提供 包括完整的构建日志 （通过构建结果的 Build log（构建日志） 选项卡中的专用链接下载）。

• 在替换或遮蔽日志中的敏感数据时，请注意所使用的替换模式。

• 如果您的系统中安装了防病毒软件，和/或者在 TeamCity 服务器前有网络代理或反向代理，请在您的请求中包含这些信息。

• 列出所有已安装的非捆绑插件。

• 请注意之前对 TeamCity Data Directory 或数据库所做的任何修改。

• 不要在邮件正文中包含大部分（超过10Kb）的文本数据 - 建议以文件形式附加上去。

请参考以下发帖指南:

• 当发布有关已报告问题的新详情时，更新主题上的前一个帖子，而不是创建新的帖子。 然而，如果您需要创建一个重复的话题，请务必记下您所发表或发现的所有同一话题的先前帖子。

• 每次提交只发布一个问题，最重要的问题优先。 如果您确实进行了多次提交，请记下其他相关问题。

请参考下面的章节获取常见的情况和需要收集并发送给我们的特定信息。

如果 TeamCity 的运行速度比您预期的慢，请按照下面的说明来找出运行缓慢的进程，如果这个进程是 TeamCity 的进程，请把所有相关的细节发送给我们。

[mysqld]
...
log-slow-queries
long_query_time=15

如果您发现 TeamCity 占用过多内存，或者在日志中出现 "OutOfMemoryError" / "Java heap space" 错误，请执行以下操作：

• 确定哪个过程遇到了错误（实际的构建过程， TeamCity 服务器，或者 TeamCity 代理）。 您可以通过 TeamCity Web UI 的 管理 | 服务器管理 | 诊断 页面上的图表跟踪 TeamCity 的内存和 CPU 使用情况。

• 如果问题出在服务器端，请检查您是否已经从默认设置中提高了内存设置，以便在生产环境中使用服务器（请参见 部分）。

• 如果问题出在构建过程一侧，请在构建运行程序中设置 "JVM 命令行参数" 设置。 增加 -Xmx JVM 选项的值：例如， -Xmx1200m。 请注意，Java Inspections 构建可能需要特定地增加 -Xmx 值。

• 如果问题出在 TeamCity 服务器端，且增加内存大小并未解决问题，请向我们报告此情况以供我们调查。 为此，当服务器在内存消耗方面比较高时，按照 上述方法获取多个服务器线程转储，获取内存转储（见下文）和包括 threadDumps-* 子目录在内的所有服务器日志，存档结果，并 将它们发送给我们以供进一步分析。 确保在获取转储前， -Xmx 的设置少于 8Gb：

  • 如果自动创建了内存转储（hprof 文件），则 java_xxx.hprof 文件会在进程启动目录中创建（<TeamCity 安装目录>/bin或 <TeamCity Agent home>/bin）；

  • 对于服务器，您也可以在内存使用率达到峰值时手动获取内存转储。 转到 TeamCity UI 的 管理 | 服务器管理 | 诊断 页面并单击 转储内存快照。

  • 另一种手动获取内存转储的方法是使用与进程使用的 Java 相同版本的完整 JVM 安装的标准 JVM 命令行工具 jmap。 示例命令行是：

    jmap -dump:file=<file_on_disk_to_save_dump_into>.hprof <pid_of_the_process>

参考如何更改 服务器 和 代理 的 JVM 选项。

1. 确定该问题在哪台计算机上发生

2. 确定已打开大量文件的进程及文件列表（在 Linux 上使用 lsof ，在 Windows 上您可以使用 handle 或 TCPView 来列出套接字）

3. 如果数字在千以下，请检查操作系统和文件句柄的进程限制（在 Linux 使用 ulimit -n ），如有必要，请增加它们。 请注意，对于像 TeamCity 这样的服务器应用程序来说，Linux 默认的每个进程 1024 个句柄实在是太少了。 将数字增加到至少 16000。 更改后请检查实际过程限制，因为在 OS 中，全局和每次会话限制的设定存在差异（例如，请看 帖子）。

如果文件数量众多且看起来可疑，且锁定进程是 TeamCity 进程（没有其他网络应用正在运行的 TeamCity 代理或服务器），那么，在问题仍在发生时，隔几分钟抓取几次打开句柄的列表，并将结果连同相关详细信息一起发送给我们进行调查。

请注意，调查后，您可能需要重新启动出现错误的机器，以恢复应用程序的正常运行。

请参阅 常见问题。

TeamCity 服务器和代理会生成日志，这些日志可以用来调查问题。

note

在复制问题之前，对 TeamCity 类启用 'DEBUG' 日志级别是有意义的。 在服务器端，转到 管理 | 服务器管理 | 诊断 页面并选择日志预设（debug-all、 debug-vcs 等）。
之后，DEBUG 消息将记录到 teamcity-*.log 文件中（了解更多）。

要获取详细信息，请参考相应的章节：

• TeamCity 服务器日志

• 查看构建代理日志

<category name="jetbrains.buildServer.VCS" additivity="false">
    <appender-ref ref="ROLL.VCS"/>
    <appender-ref ref="CONSOLE-ERROR"/>
    <priority value="DEBUG"/>
</category>

<category name="jetbrains.buildServer.buildTriggers.vcs" additivity="false">
    <appender-ref ref="ROLL.VCS"/>
    <appender-ref ref="CONSOLE-ERROR"/>
    <priority value="DEBUG"/>
</category>

<param name="maxBackupIndex" value="30"/>

在使用 服务器端检出 的情况下，可以通过以下方式检索从服务器传递给代理的 "补丁"：

• 将属性 system.agent.save.patch=true 添加到构建配置中。

• 触发构建。 构建日志和代理日志将包含以下行：“Patch is saved to file $\{file.name\}”。获取该文件并附上问题描述。

要在 TeamCity 2021.1 及更高版本中收集所有构建触发器调试日志，请在 管理 | 诊断 页面上切换日志预设为 debug-triggers ，重现问题，然后收集所有 teamcity-triggers.log 文件。

在 2021.1 之前的 TeamCity 版本中，只能为在特定构建配置中定义的 VCS 触发器启用调试日志记录：

1. 获取默认日志预设文件 <TeamCity Home>/conf/teamcity-server-log4j.xml 并以其他名称保存到 <TeamCity Data Directory>/config/_logging/ 目录下。

2. 按照以下方式修改结果文件：

   • 向日志中添加一个新的 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。

3. 在 管理 | 诊断 页面上将日志预设切换为新创建的预设文件。

不需要重新启动服务器。 如果配置正确，TeamCity 将在几分钟内创建 teamcity-vcs-trigger.log 日志文件。 该文件将只包含与所选配置相关的调试日志。

为了调查与 .NET-related runners 相关的进程启动问题，您需要按照下面的描述启用调试功能。 详细信息将随后打印到构建日志中。 建议不要长时间开启调试日志，并在调查后恢复设置。

启用日志记录的另一种方法如下：在构建配置或代理上添加 teamcity.agent.dotnet.debug=true 配置参数并运行构建。

1. 打开 <agent home>/plugins/dotnetPlugin/bin 目录。

2. 制作一份 teamcity-log4net.xml 的备份副本。

3. 将 teamcity-log4net.xml 替换为 teamcity-log4net-debug.xml 的内容。

note

生成调试日志后，建议您回滚更改。 在构建代理自动升级中， teamcity-log4net.xml 的更改将被删除。

从IDE发送到服务器的更改可以在 远程运行 期间从服务器 .BuildServer/system/changes 目录中取回。 定位与您的更改相对应的 <change_number> . 变更 文件（您可以选择最新可用的数字，或者从网页界面推断出更改的 URL）。 该文件以二进制格式包含了补丁。 请将问题描述一起发送。

要启用 IntelliJ Platform-based IDE plugin 的调试记录功能，请在 <IDE 主页>/bin/log.xml 文件的 Log4j 配置中包含以下片段。

note

自平台版本 2019.3 起，此文件默认不再被加载。 考虑通过 帮助 | 诊断工具 | 调试日志设置 添加配置。 或者，您可以将此文件复制到某个位置，并通过在 帮助 | 编辑自定义属性 中添加 idea.log.config.file = /path/to/log.xml 来指定其路径。

<appender name="TC-FILE" class="org.apache.log4j.RollingFileAppender">
  <param name="MaxFileSize" value="10Mb"/>
  <param name="MaxBackupIndex" value="10"/>
  <param name="file" value="$LOG_DIR$/idea-teamcity.log"/>
  <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="%d [%7r] %6p - %30.30c - %m \n"/>
  </layout>
</appender>

<appender name="TC-XMLRPC-FILE" class="org.apache.log4j.RollingFileAppender">
  <param name="MaxFileSize" value="10Mb"/>
  <param name="MaxBackupIndex" value="10"/>
  <param name="file" value="$LOG_DIR$/idea-teamcity-xmlrpc.log"/>
  <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="%d [%7r] %6p - %30.30c - %m \n"/>
  </layout>
</appender>

<category name="jetbrains.buildServer.XMLRPC" additivity="false">
  <priority value="DEBUG"/>
  <appender-ref ref="TC-XMLRPC-FILE"/>
</category>

<category name="jetbrains.buildServer" additivity="false">
  <priority value="DEBUG"/>
  <appender-ref ref="TC-FILE"/>
</category>

更改此文件后，重新启动 IDE。 TeamCity 插件的调试日志被保存到 idea-teamcity\* 文件中，并会显示在 IDE 设置 （<IDE 设置/数据目录>/系统/log 目录）的日志目录中。

为收集由 JetBrains dotCover 生成的额外日志，将 teamcity.agent.dotCover.log 配置参数 添加到构建配置中。 此参数应存储一个绝对路径或相对路径，指向一个空的代理目录，您希望在该目录中保存 dotCover 日志。 如果您需要将这些日志作为 构建工件 发布，请将相同的目录路径添加到 产物路径 列表中。

在极少数情况下，TeamCity 服务器或代理进程可能会毫无预警地意外终止，这可能是由于 Java 运行时崩溃引起的。
如果发生这种情况，JVM 通常会在进程的工作目录中创建一个名为 hs_err_pid*.log 的文件。 工作目录通常是 <TeamCity server home>/bin 或 <agent home>/bin。
在 Windows 下作为服务运行时，可能是其他目录，如 C:\Windows\SysWOW64。 您也可以在磁盘上搜索名称中含有 "hs_err_pid" 的最近文件。 请参阅本 文档中相关的致命错误日志部分。

请将此文件发送给我们进行调查，并考虑为 服务器 （或 代理 ）更新到最新可用的 JVM 版本。

如果您收到 "Java 运行环境无法继续，因为内存不足。 本机内存分配（malloc）未能分配..."消息与崩溃或在崩溃报告文件中，请务必 切换到 64 位 JVM或将 -Xmx 设置降低至 1024m 以下，有关详细信息请参阅 内存配置部分。

在调查与构建日志有关的问题时，我们可能需要由 TeamCity 储存的原始二进制构建日志。 可以通过 Web UI 从构建日志构建的标签页下载：选择 "Verbose" 日志详情，并使用右上角的 "raw messages file" 链接。

TeamCity 构建的检查结果可能与 IntelliJ IDEA 本地运行的检查结果不匹配。

为了帮助我们调查与检查相关的问题，请执行以下操作：

1. 将 system.teamcity.dont.delete.temp.result.dir=true 添加到 配置参数中

2. 在 Artifact paths 中添加 % \system.teamcity.build.tempDir% /inspection*result/** => inspections-reports-data-% \build.number% .zip 规则

3. 在 Artifact paths 中添加 % \system.teamcity.build.tempDir% /idea-logs/** => inspections-reports-idea-logs-%build.number%.zip 规则

4. 在运行器的 JVM 命令行参数 字段中添加 -Didea.log.path=%system.teamcity.build.tempDir%/idea-logs/。

5. 运行一个新的构建。

6. 向我们发送 inspections-reports-*.zip 文件。

大小在10 MB以下的文件可以直接附加到 跟踪问题 中（如果您不希望附件被公开访问，只需将附件可见性限制为 "teamcity-developers" 用户组）。
您也可以通过电子邮件发送小文件（最大2 MB）： teamcity-support@jetbrains.com 或者通过 在线表单 （最大20 MB）。 请不要忘记提及您的 TeamCity 版本和环境，并在附加前归档文件。

大型文件可以通过 https://uploads.jetbrains.com/ 上传。 请在上传后告诉我们确切的文件名。

如果您无法一次性上传大文件，请尝试将文件分割成多个部分，然后分别上传。