問題の報告

問題を報告する際のベストプラクティス

これらのガイドラインに従うことで、タイムリーな対応と効果的な問題解決が保証されます。適切な連絡方法については、フィードバックを確認してください。

サポートのリクエストを送信するときは、次の一般情報を含めてください :

• ビルド番号を含む使用中の TeamCity バージョン（これはフッターと teamcity-server.log にあります）。また、使用されているオペレーティングシステムと Java バージョンを含める価値があります。

• 問題の発生パターン（初回、繰り返しなど）を記録します。過去に緩和された場合は、最近の環境変更があったかどうかを記録します。具体的に: 正確な時間、エラーメッセージを書き留め、予想される動作と実際の動作の両方を記述します。

• 可能な限り、TeamCity UI の関連スクリーンショット (キャプチャーには常にページ全体とブラウザーの URL を含める) を含め、関連する設定ファイル、実際の値、REST API エンティティ表現の詳細を提供します。

• エラーメッセージやその他の関連テキストメッセージ (イメージではなくテキストとして) を含める場合は、完全なメッセージと、そのメッセージが表示された場所を含めます。メッセージが数行を超える場合は、ファイルとしてチケットに添付します。

• 3 つ以上のファイルを送信する場合は、ファイルを単一のアーカイブにパッケージ化します。

• 10Mb を超えるファイルを送信する場合は、大きなデータアーカイブのアップロードのガイドに従ってください。

特定の問題に関するその他の役立つヒント :

• 必要に応じて、TeamCity サーバーログを含むアーカイブを添付 / アップロードします ( 詳細を参照してください。理想的には、すべてのディレクトリを含む <server_home>\logs ディレクトリ全体。現実的でない場合は、発行時刻前後に更新されたすべてのファイル)。ビルド時間またはエージェントの動作に関連している場合は、<agent_home>\logs ディレクトリ全体を添付します。

• パフォーマンス / 速度低下 / 遅延の問題については、問題が発生している間にサーバーまたはエージェントのスレッドダンプのセット (問題発生時間にわたって 10 個以上) を取得し、関連データとともにダンプを必ず送信してください。

• YouTrack 課題トラッカー(英語)に問題が存在するかどうかを確認することを検討してください。ここでは、ほとんどのバグとエッジ条件を特定します。後の TeamCity バージョンで問題がすでに修正されている可能性があります。

• ビルドロジックに問題がある場合は、それが TeamCity 関連の問題である (つまり、TeamCity のない同じ環境では再現しない) ことを確認し、調査の詳細を含めてください。

• ビルド手順の問題を報告する場合は、同じ環境のエージェントマシンで TeamCity なしで問題を再現し、結果をお知らせください。

• 特定のビルドが影響を受ける場合は、完全なビルドログ (ビルド結果のビルドログタブから専用リンク経由でダウンロード) を含めます。

• ログ内の機密データを置換またはマスキングする場合、使用される置換パターンに注意してください。

• ウイルス対策ソフトウェアがインストールされている場合や、TeamCity サーバーの前にネットワークプロキシまたはリバースプロキシがある場合は、この情報をリクエストに含めてください。

• インストールされているバンドルされていないプラグインをリストします。

• TeamCity データディレクトリまたはデータベースの以前の変更に注意してください。

• テキストデータの大部分（10Kb を超える）をメールテキストに含めないでください。ファイルに添付してください。

投稿については次のガイドラインを考慮する :

• すでに報告された問題に関する新しい詳細を投稿する場合、新しいものを作成する代わりに、トピックに関する以前の投稿を更新します。ただし、重複したトピックを作成する必要がある場合は、作成または発見した同じトピックに関する以前の投稿をすべてメモしてください。

• 最も重要な問題を最初に、提出ごとに 1 つの問題を投稿してください。複数の提出を行う場合、それらが関連している場合、他の問題をメモします。

収集して当社に送信する一般的なケースと特定の情報については、以下のセクションを確認してください。

スローネス、ハンギング、低パフォーマンス

TeamCity の速度が予想よりも遅い場合は、以下の注意事項を使用して、遅いプロセスを見つけ、プロセスが TeamCity のものである場合に関連するすべての詳細を送信してください。

エージェントのスレッドとメモリダンプ

Web UI からエージェントスレッドダンプを取得することをお勧めします。エージェントページのエージェント概要タブに移動し、エージェントのスレッドをダンプするアクションやエージェントのメモリスナップショットをダンプするアクションを使用します。

UI にアクセスできない場合は、以下で説明する方法を使用してダンプスレッドを手動で取得できます。

メモリ不足の問題

TeamCity がメモリを大量に消費する問題、またはログで「OutOfMemoryError」/「Java ヒープスペース」エラーが発生する場合は、次の手順を実行します。

• エラーが発生したプロセス（実際の構築プロセス、TeamCity サーバー、TeamCity エージェント）を判別します。TeamCity Web UI の管理 | サーバー管理 | 診断ページのチャートを使用して、TeamCity によるメモリと CPU の使用量を追跡できます。

• 問題がサーバー側にある場合は、本番環境でサーバーを使用するためのデフォルトのメモリ設定からメモリ設定を増やしていることを確認してください（セクションを参照）。

• 問題がビルドプロセス側にある場合は、ビルドランナーで「JVM コマンドラインパラメーター」設定を設定します。-Xmx JVM オプションの値を増やします (例: -Xmx1200m)。Java インスペクションビルドでは、特に -Xmx 値を増やす必要がある場合があることに注意してください。

• 問題が TeamCity サーバー側にあり、メモリサイズを増やしても問題が解決しない場合は、調査のためにケースを報告してください。サーバーはメモリの消費量に高いですが、これについては、説明するように、いくつかのサーバースレッドダンプを取る上でメモリダンプを取得し、（下記参照）と threadDumps-* サブディレクトリを含むすべてのサーバーログ、結果をアーカイブし、送信するために私たちにさらなる分析。ダンプを取得する前に、-Xmx 設定が 8Gb 未満であることを確認してください。

  • メモリダンプ（hprof ファイル）が自動的に作成される場合、java_xxx.hprof ファイルはプロセス起動ディレクトリ（ <TeamCity Home>/bin または <TeamCity Agent home>/bin ）に作成されます。

  • サーバーの場合、メモリ使用量がピークに達したときに手動でメモリダンプを取得することもできます。TeamCity UI の管理 | サーバー管理 | 診断ページに移動し、ダンプメモリスナップショットをクリックします。

  • メモリダンプを手動で取得する別のアプローチは、プロセスで使用される Java と同じバージョンの完全な JVM インストールの jmap 標準 JVM コマンドラインユーティリティを使用することです。コマンドラインの例は次のとおりです。

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

サーバーおよびエージェントの JVM オプションを変更する方法を参照してください。

「開いているファイルが多すぎます」エラー

1. 発生するコンピューターを判別する

2. 多くのファイルとファイルリストを開いたプロセスを特定する (Linux では lsof を使用し、Windows ではソケットの一覧表示にハンドル(英語)または TCPView(英語) を使用できます。)

3. 数が数千未満の場合は、OS とファイルハンドルのプロセス制限 (Linux では ulimit -n を使用) を確認し、必要に応じて増やしてください。Linux のデフォルトのプロセスあたり 1024 ハンドルは、TeamCity のようなサーバーアプリケーションには少なすぎることに注意してください。少なくとも 16000 に数を増やしてください。OS にはグローバル制限とセッションごとの制限の設定が異なるため、変更後に実際のプロセス制限を確認してください。(例: 投稿(英語)を参照)

ファイルの数が多くて疑わしく、ロックプロセスが TeamCity の場合 (他の Web アプリケーションが実行されていない TeamCity エージェントまたはサーバー)、問題がまだ発生している間に、開いているハンドルのリストを数分間隔で数回取得し、関連する詳細とともに結果を調査のために弊社に送信してください。

ほとんどの場合、アプリケーションの正常な機能を回復するには、調査後にエラーでマシンを再起動する必要があることに注意してください。

エージェントはサーバーに接続しません

よくある問題を参照してください。

イベントのログ

TeamCity サーバーとエージェントは、問題の調査に使用できるログを作成します。

詳細については、対応するセクションを参照してください。

• TeamCity サーバーログ

• ビルドエージェントログの表示

パッチ適用の問題

サーバー側のチェックアウトを使用する場合、サーバーからエージェントに渡される「パッチ」は次の方法で取得できます。

• プロパティ system.agent.save.patch=true をビルド構成に追加します。

• ビルドをトリガーします。ビルドログとエージェントログには、「パッチがファイル $\{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. 結果のファイルを次のように変更します。

   • 新しいトリガーを追加して、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_<build configuration 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 ランナーのロギング

.NET 関連のランナーのプロセス起動の問題を調査するには、以下の説明に従ってデバッグを有効にします。その後、詳細情報がビルドログに出力されます。デバッグログを長時間保持せず、調査後に設定を元に戻すことをお勧めします。

ログ記録を有効にする別の方法は次のとおりです。ビルド構成またはエージェントに teamcity.agent.dotnet.debug=true 構成パラメーターを追加し、ビルドを実行します。

1. <agent home> /plugins/dotnetPlugin/bin ディレクトリを開きます。

2. teamcity-log4net.xml のバックアップコピーを作成します。

3. teamcity-log4net.xml を teamcity-log4net-debug.xml のコンテンツに置き換えます。

リモート実行の問題

リモート実行時に IDE からサーバーに送信される変更は、サーバーの .BuildServer/system/changes ディレクトリから取得できます。変更に対応する <change_number>.changes ファイルを見つけます (使用可能な最新の番号を選択するか、Web UI から変更の URL を推測できます)。ファイルにはバイナリ形式のパッチが含まれています。問題の説明とともに送信してください。

IntelliJ IDEA/ プラットフォームベースの IDE へのログイン

IntelliJ プラットフォームベースの IDE プラグインのデバッグログを有効にするには、<IDE home>/bin/log.xml ファイルの Log4j 構成に次のフラグメントを含めます。

このファイルを変更した後、IDE を再起動します。TeamCity プラグインのデバッグログは idea-teamcity\* ファイルに保存され、IDE 設定のログディレクトリ（<IDE settings/Data Directory>/system/log ディレクトリ）に表示されます。

TeamCity Visual Studio アドインの問題

dotCover の問題

JetBrains dotCover によって生成された追加のログを収集するには、ビルド構成に teamcity.agent.dotCover.log 構成パラメーターを追加します。このパラメーターには、dotCover ログを保持する空のエージェントディレクトリへの絶対パスまたは相対パスを格納する必要があります。これらのログをビルドアーティファクトとして公開する必要がある場合は、同じディレクトリパスをアーティファクトパスのリストに追加します。

JVM クラッシュ

まれに、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 を介してダウンロードできます。「詳細」ログ詳細を選択し、右上隅の「生のメッセージファイル」リンクを使用します。

IntelliJ IDEA インスペクション

TeamCity ビルドのインスペクション結果は、IntelliJ IDEA でのローカル実行のインスペクションと一致しない場合があります。

インスペクションの問題を調査するには、次の手順を実行します。

1. 構成パラメーターに system.teamcity.dont.delete.temp.result.dir=true を追加する

2. %system.teamcity.build.tempDir%/inspection*result/** => inspections-reports-data-%build.number%.zip ルールをアーティファクトパスに追加します

3. %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」ユーザーグループのみに制限します)。
小さなファイル（最大 2MB）をメールで送信することもできます: teamcity-support@jetbrains.com またはオンラインフォーム (英語)(最大 20 MB) 経由で送信してください。添付する前に、必ず TeamCity のバージョンと環境を明記し、ファイルをアーカイブしてください。

大きなファイルは https://uploads.jetbrains.com/ (英語) を介してアップロードできます。アップロード後、正確なファイル名をお知らせください。

大きなファイルを一度にアップロードできない場合は、ファイルを部分に分割して、個別にアップロードしてみてください。