課題の報告

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

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

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

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

• 課題の発生パターン (初回、再発など)、過去に軽減されたかどうか、最近環境の変更があったかどうかを記録してください。 具体的に記載する: 正確な時刻とエラーメッセージを記録し、期待される動作と実際の動作の両方を説明してください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• TeamCity データディレクトリまたはデータベースに対する過去の変更を記載してください。

• 大量のテキスト形式データ (10Kb 超) をメール本文に含めないでください。代わりにファイルとして添付してください。

投稿については次のガイドラインを参考にしてください は:

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

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

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

遅延、ハング、低パフォーマンス

TeamCity の実行が予想より遅い場合は、以下のメモを使用して遅いプロセスを特定し、そのプロセスが TeamCity のものである場合は関連するすべての詳細をお送りください。

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

ウェブ UI からエージェントスレッドダンプを取得することをおすすめします。エージェントページの エージェントの概要 タブに移動し、 エージェント上のスレッドをダンプ および/または エージェントでメモリスナップショットをダンプ アクションを使用してください。

UI にアクセスできない場合、またはエージェントが 承認済みでない場合 (この場合、TeamCity はこれらのアクションを非表示にします) は、 以下で説明する方法を使用して、ダンプスレッドを手動で取得できます。

OutOfMemory の問題

TeamCity がメモリを過剰に消費する問題、またはログに "OutOfMemoryError"/"Java ヒープ領域" エラーが発生する場合は、次の操作を行ってください：

• どのプロセスでエラーが発生しているかを特定してください (実際のビルドプロセス、TeamCity サーバー、または TeamCity エージェント)。 TeamCity ウェブ UI の 管理 | サーバー管理 | 診断 ページにあるチャートで、TeamCity によるメモリと CPU の使用量を確認できます。

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

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

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

  • メモリダンプ（hprof ファイル）が自動的に作成される場合、 java_xxx.hprof ファイルはプロセス起動ディレクトリ（<TeamCity ホーム>/bin または <TeamCity Agent ホーム>/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 のもの (他のウェブアプリケーションが実行されていない TeamCity エージェントまたはサーバー) である場合は、課題がまだ発生している間に、開いているハンドルのリストを数分間隔で複数回取得し、関連する詳細とともに結果を調査用にお送りください。

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

エージェントがサーバーに接続しない

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

イベントのログ記録

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

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

• TeamCity サーバーログ

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

パッチアプリケーションの問題

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

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

• ビルドをトリガーします。 ビルドログとエージェントログには "Patch is saved to file $\{file.name\}" という行が含まれます。ファイルを取得し、問題の説明と一緒に提供してください。

ビルドトリガーのデバッグログ

TeamCity 2021.1 以降ですべてのビルドトリガーのデバッグログを収集するには、 管理 | 診断 ページのログプリセットを debug-triggers に切り替え、問題を再現してから、すべての TeamCity トリガー.ログ ファイルを収集します。

TeamCity 2021.1 より前のバージョンでは、特定のビルド構成で定義された VCS トリガーのデバッグログを有効化することのみが可能です：

1. デフォルトのログプリセットファイル <TeamCity ホーム>/conf/teamcity-server-log4j.xml を取得し、 <TeamCity データディレクトリ>/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_<ビルド構成 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. <エージェントホーム>/plugins/dotnetPlugin/bin ディレクトリを開きます。

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

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

リモート実行の問題

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

IntelliJ IDEA/Platform ベースの IDE でのログイン

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

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

TeamCity Visual Studio アドインの課題

dotCover の課題

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

JVM クラッシュ

まれに、TeamCity サーバーまたはエージェントプロセスが明らかな理由なく予期せず終了する場合、Java ランタイムクラッシュが原因であることがあります。
この場合、JVM は通常、プロセスの作業ディレクトリに hs_err_pid*.log という名前のファイルを作成します。 作業ディレクトリは通常、 <TeamCity サーバーホーム>/バイナリ または <エージェントホーム>/バイナリ です。
Windows でサービスとして実行している場合は、 C:\Windows\SysWOW64 など別の場所になることがあります。 名前に "hs_err_pid" を含む最近のファイルをディスク上で検索することもできます。 この ドキュメント の関連する Fatal Error ログセクションも参照してください。

調査のためこのファイルを弊社まで送信し、 サーバー (または エージェント) の JVM を最新バージョンに更新することを検討してください。

「Java ランタイム環境を続行するためのメモリが不足しています。 ネイティブメモリの割り当て (malloc) に失敗しました..." というメッセージがクラッシュ時またはクラッシュレポートファイルに表示される場合は、必ず 64 ビット JVM に切り替えるか、 -Xmx 設定を 1024m 未満に下げてください。詳細は メモリ構成セクションを参照してください。

ビルドログの課題

ビルドログに関連する課題を調査する際、TeamCity によって保存されている生のバイナリビルドログが必要になる場合があります。 ウェブ 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" ユーザーグループのみに制限してください)。
小さいファイル (最大 2 MB) はメール teamcity-support@jetbrains.com または オンラインフォーム (最大 20 MB) で送信することもできます。 添付する前に、TeamCity バージョンと環境を記載し、ファイルをアーカイブすることを忘れないでください。

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

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