レート制限でインスタンスの安定性を改善する

自動化された連携やスクリプトが Jira に大量のリクエストを送信すると、Jira の安定性に影響を与え、パフォーマンスの低下やダウンタイムにつながる恐れがあります。レート制限を使用すると、ユーザーや自動化機能が送信可能な外部 REST API リクエストの数と頻度を制御し、Jira インスタンスが安定した状態を保つようにできます。

レート制限は Jira Software Data Center および Jira Service Management Data Center で使用できます。

レート制限の仕組み

Jira でのレート制限の仕組みの詳細についてご説明します。

リクエストの制限

レート制限は外部 REST API リクエストのみを対象とします。つまり、Jira 内でのリクエストは制限されません。ユーザーによる、Jira ユーザー インターフェイス内での移動、プロジェクトの表示、課題のトランジション、および他のアクションの完了などの操作は、制限すべきでない通常のユーザー エクスペリエンスとみなされるため、レート制限の影響を受けません。

次の例で詳しく説明します。

  • Jira でユーザーが課題を表示すると、バックグラウンドで多数のリクエストが送信されます。これらのリクエストは Jira に対し、コメント、担当者、添付ファイルなどを要求します。このトラフィックは Jira 内部のものであるため、制限されません。

  • 同じユーザーがラップトップでターミナルを開き、次のようなリクエストを送信して課題に関する情報を取得した場合、この処理は Jira 外で行われるためレート制限の対象になります。

    wget https://jira.com/rest/api/2/issue/JRASERVER-70350

認証メカニズム

制限対象のリクエストを製品で特定する方法の詳細として、製品では次の認証メカニズムを使用した外部 HTTP リクエストを対象にしています。

  • Basic Auth
  • OAuth
  • JSESSIONID cookie
弊社で採用したレート制限技術について

アトラシアンでは、レート制限の実施に利用できる多数の技術の中から、トークン バケットを採用しました。 

トークン バケットを使用すると、リクエストに交換できるトークンの残数がユーザーに提示されます。仕組みの要約は次のとおりです。

  • ユーザーにはトークンが提供されます。これはリクエストに交換されます。1 つのトークンは 1 件のリクエストに相当します。

  • ユーザーは一定のタイミングで新しいトークンを取得するため、常に新しいリクエストを作成できます。これが、そのユーザーの許容要求数であり、10 個/1 分のように設定されます。

    • (info) 定数レートまたは間隔は、時間間隔 (秒単位) を許容要求数で割ったものです。

  • トークンは、個人用のバケットが満杯になるまで追加されます。これが、そのユーザーの最大要求数であり、トークンの使用を自分の頻度に合わせて調整できます。たとえば、通常のレートで指定された、10 件/1 分ではなく、20 件/2 分とすることができます。

  • ユーザーが、自身が保有しているトークン数を超えるリクエストを送信しようとした場合、バケットからトークンを取得できたリクエストのみが成功します。残りのリクエストには 429 エラーのメッセージ (too many requests) が返されます。ユーザーは新しいトークンの取得後にこれらのリクエストを再試行できます。

他のアトラシアン製品との連携

Jira は、Confluence、Bitbucket、Bamboo などの他のアトラシアン製品と組み合わせることで、最大のメリットを発揮できます。これらの製品は技術的には、Jira の外部であるため、制限対象になります。ただし、このユースケースにおいては、これらは同じユーザー エクスペリエンス内に所属するとみなされ、製品間でやり取りされるリクエストは制限の対象外にすることが望ましいと考えられます。

現在の状況は次のとおりです。

  • サーバー製品: 制限されません。

  • クラウド製品: クラウド製品に送受信されるリクエストにレート制限が適用される、既知の問題があります。アトラシアンではクラウド製品に対するレート制限の無効化に取り組んでおり、近日中に提供を開始する予定です。現時点では回避策を使用できます。詳しくは、「アトラシアン クラウド製品に対するレート制限の削除」を参照してください。

Atlassian Marketplace のアプリ

Jira インスタンスにインストールされている Marketplace アプリが Jira 内から行う内部リクエストは、制限されるべきではありません。ただし、これはほかの挙動と同様に、アプリの仕組みに依存します

  • 内部: アプリがユーザー エクスペリエンスの強化のために内部で動作している場合、それは制限されません。このようなアプリの例として、スクラム ボードに表示される特別なバナーなどがあります。このバナーは完了したすべての課題を確認し、このスプリントの勝者、つまり、このスプリントでもっとも多くの課題を完了したユーザーを表示するとします。このようなトラフィックは内部のものになり、制限されません。

  • 外部: Jira の外部でリクエスト行うアプリは制限されます。テレビにウォールボードを表示するアプリがあるとします。このアプリは、ボード、課題、担当者などの詳細を Jira から取得し、それらを再度シャッフルし、前述のウォールボードとして独自の方法で表示します。このようなアプリは外部リクエストを送信し、ターミナルからリクエストを送信するユーザーのように動作します。

アプリによって異なりますが、ほとんどのものが制限対象外であると想定しています。

クラスタでのレート制限の仕組み

レート制限は Data Center で利用可能なため、ノードのクラスタがロード バランサの背後にある可能性が高くなります。各ユーザーには、各ノードに個別の制限があります (レート制限はクラスタではなくノードごとに適用されます)。

つまり、1 つのノードで許可されたリクエスト数を使用してレート制限されている場合、別のノードで新しいセッションを開始すると、論理的にはもう一度リクエストを送信できます。ユーザーがノードを切り替えることはできませんが、これが発生する可能性があることを念頭に置いてください。

選択した制限 (例: 100 件のリクエスト/1 時間) にかかわらず、各ノードに同じ制限が適用され、個別に設定する必要はありません。つまり、各ユーザーで利用できるリクエストの送信機能は引き続き制限され、リクエストがどのノードに転送されるかにかかわらず、Jira は安定性を維持します。

管理者による制限の選択基準について

適切な制限の設定は多くの要因に依存するため、単純な回答を提供することはできません。ここではいくつかの提案をご案内させていただきます。

適切な制限を見つける

最初に、インスタンスが受信するトラフィックのサイズを理解します。アクセス ログを解析し、1 日に最大数の REST リクエストを作成したユーザーを見つけます。UI トラフィックはレート制限されないため、この数字はレート制限として必要な値よりも大きくなります。次に、これを基本値とし、以下の質問に基づいてさらに変更します。

  1. ユーザーの作業の中断は許可されますか? ユーザーによる連携機能がミッションクリティカルな場合、代わりにハードウェアをアップグレードすることをご検討ください。連携の重要性に応じて、制限も高く設定する必要があります。算出した数を 2 倍または 3 倍にすることをご検討ください。

  2. インスタンスですでに、REST トラフィックの量による問題が発生していますか? その場合、インスタンスで問題が発生しなかった日の基本値に近い制限を選択します。顕著な問題が発生していないのであれば、基本値に 50% を追加することをご検討ください。これにより、ユーザーの作業が中断されるのを防ぎながら、十分な容量を維持できます。

一般に、個別のユーザーを制御するのではなく、インスタンスを安全に保つために、制限値を選択します。レート制限は、ユーザーが作業を完了できないようにするものではなく、連携やスクリプトが壊れるのを防ぐためのものです。

レート制限を有効化する方法

レート制限を有効化するには、Jira システム管理者である必要があります。

レート制限を有効化するには、次の手順を実行します。

  1. Jira で、[管理] > [システム] > [レート制限] に移動します。

  2. ステータスを [有効] に変更します。

  3. 次のオプションのうち 1 つを選択します: 無制限のリクエストを許可すべてのリクエストをブロック、またはリクエストを制限。最初のオプションと 2 番目のオプションは許可リストとブロックリストに関連します。最後のオプションの場合、実際の制限を入力する必要はありません。詳細については以下をお読みください。

  4. 保存をクリックします。

  5. 許可リストまたはブロックリストを選択している場合は特に、追加リクエストを本当に必要とするユーザーに例外を追加するようにします。「例外の追加」を参照してください。

リクエストの制限 - 詳細

許可リストやブロックリストと同様に、グローバル設定や適用除外では、リクエスト制限のオプションを頻繁に使用することになるはずです。

Jira 管理コンソールの [レート制限] ページ。画像の下に注釈の説明があります。

このオプションと仕組みについて詳しく見てみましょう。

  1. 許容要求数: 各ユーザーは、選択した時間間隔に特定の件数のリクエストが許可されています。1 秒あたり 10 件のリクエスト、1 時間あたり 100 件のリクエストなど、任意の設定を選択できます。

    選択した時間の単位 (秒、分、時間) に関係なく、Jira では常に時間間隔を秒単位に変換します。

  2. 最大要求数 (高度): リクエストが頻繁に送信されない場合は、許容要求数をユーザーごとに最大数まで蓄積できます。このオプションを使用すると、ユーザーは通常と異なる頻度 (レートで指定された 1 分あたり 10 件の代わりに 2 分あたり 20 件など) でリクエストを作成するか、時間をかけて多くのリクエストを蓄積し、一度に送信できます。最大数の設定が難しい場合は、[許容要求数] と同じ値に設定しておけば、このフィールドの影響はなく、蓄積されるリクエストもありません。

例 1: 許可されるリクエストとして 10 件/ 1 時間、最大リクエスト数 100 を設定

許可されるリクエスト: 10 件/時間 | 最大リクエスト数: 100

  • ある開発者は 1 日を通じ、1 時間あたり 10 件のリクエストを定期的に送信します。1 回にまとめて 20 件のリクエストを送信しようとすると、そのうち 10 件のみが成功します。その後の 1 時間で新しいリクエストを作成できるようになったら、残りの 10 件を再試行できます。

  • 別の開発者は過去 10 時間にリクエストを送信していません。そのため、許可されているリクエスト数は最大リクエスト数である 100 に到達するまで蓄積され続けます。これにより、一度に 100 件のリクエストを送信でき、それらすべてが成功するようになります。利用可能なすべてのリクエストを使い果たしたら、1 時間待機することで 10 件のリクエストのみが許可されます。

  • 同じ開発者が 100 件のリクエストのうち 50 件のみを送信した場合、その開発者は直ちに追加で 50 件を送信するか、次の 1 時間で再度蓄積を開始することができます。

例 1: 許可されるリクエストとして 1 件/ 1 秒、最大リクエスト数 60 を設定

許可されるリクエスト: 1 件/秒 | 最大リクエスト数: 60

  • 開発者は、1 秒あたり 1 件のリクエストまたは 毎分 60 件のリクエスト を送信するように任意の頻度を選択できます。

  • 割り当てられた 60 件のリクエストを任意の頻度で使用できるので、それらすべてを一度に使用することも、非常に短い間隔で使用することもできます。このような場合、1 秒あたり 1 件のリクエストという通常のレートを超えることになります。

適切な制限を見つける

管理者による制限の選択基準について

適切な制限の設定は多くの要因に依存するため、単純な回答を提供することはできません。ここではいくつかの提案をご案内させていただきます。

適切な制限を見つける

最初に、インスタンスが受信するトラフィックのサイズを理解します。アクセス ログを解析し、1 日に最大数の REST リクエストを作成したユーザーを見つけます。UI トラフィックはレート制限されないため、この数字はレート制限として必要な値よりも大きくなります。次に、これを基本値とし、以下の質問に基づいてさらに変更します。

  1. ユーザーの作業の中断は許可されますか? ユーザーによる連携機能がミッションクリティカルな場合、代わりにハードウェアをアップグレードすることをご検討ください。連携の重要性に応じて、制限も高く設定する必要があります。算出した数を 2 倍または 3 倍にすることをご検討ください。

  2. インスタンスですでに、REST トラフィックの量による問題が発生していますか? その場合、インスタンスで問題が発生しなかった日の基本値に近い制限を選択します。顕著な問題が発生していないのであれば、基本値に 50% を追加することをご検討ください。これにより、ユーザーの作業が中断されるのを防ぎながら、十分な容量を維持できます。

一般に、選択する制限は、個々のユーザーを制御するのではなく、インスタンスを安全に保つ必要があります。レート制限とは、ユーザーが作業を完了するのを妨げるよりも、Jira の統合やスクリプトがヘイワイアになるのを防ぐことです。

例外の追加

同様に例外は、他のユーザーよりも多くのリクエストを実際に必要とするユーザーのための特別な制限です。選択した例外は、グローバル設定よりも優先されます。

tip/resting Created with Sketch.

例外を追加または編集した後、変更はすぐに反映されますが、新しい設定がユーザーに適用されるには最大で 1 分かかります。

レート制限から除外されたユーザーが表示された [例外] タブ

例外を追加するには、次の手順を実行します。

  1. [例外] タブを開きます。

  2. [例外の追加] をクリックします。

  3. ユーザーを見つけ、そのユーザーのための新しい設定を選択します。

    • グループを選択することはできませんが、複数のユーザーを選択できます。

    • ここで利用可能なオプションはグローバルな設定の場合と同じです: "無制限のリクエストを許可"、"すべてのリクエストをブロック "、"カスタム制限を割り当て"。

  4. 保存をクリックします。

後から例外を編集したい場合は、[例外] タブでユーザー名の横にある [編集] をクリックします。

推奨: 匿名アクセスへの例外を追加

Jira では、すべての匿名トラフィックが "Anonymous" という 1 人のユーザーによるものであるとみなします。レート制限が十分に高くない場合、1 人のユーザーが匿名ユーザーに割り当てられた制限を使い果たす可能性があります。このアカウントに高い制限値を割り当てた例外を追加し、さらなる追加が必要かどうかを確認することをおすすめします。 

レート制限されているユーザーの特定

ユーザーがレート制限を受けている場合、HTTP 429 エラー メッセージ (too many requests) が表示されるため、ユーザーはすぐにそのことを確認できます。管理者はレート制限設定ページの [制限を受けているアカウントの一覧] を開いて、レート制限を受けているユーザーを特定できます。一覧には、クラスタ全体のすべてのユーザーが表示されます。

tip/resting Created with Sketch.

ユーザーがレート制限を受けている場合、表に表示されるには最大で 5 分かかります。

制限されたアカウントの一覧。

異常なアカウント

ユーザーは一覧にユーザー名で表示されます。ただし一覧には、いくつかの異常なアカウントが表示される場合があります。以下に例を示します。

  • Unknown: Jira で削除されたユーザーです。これらのユーザーは 24 時間を経過すると一覧には表示されませんが (ユーザーをレート制限することはできなくなっているため)、例外の一覧には表示される場合があります。これらのユーザーにはレート制限は不要なため、設定を削除してかまいません。

  • Anonymous: このエントリは、認証されていないアカウントから行われたすべてのリクエストを収集します。1 人のユーザーで匿名アクセスの制限までのリクエスト数を簡単に使用できてしまうことがあるため、匿名トラフィックに例外を追加して、高い制限値を追加することをおすすめします。

制限付きのリクエストをログ ファイルに追加する

Jira のログ ファイルでレート制限されているユーザーやリクエスト数の情報を表示することもできます。これは、リクエストの宛先 URL やリクエスト元の URL の詳細を知りたい場合に便利です。

手順について

制限付きのリクエストをログ ファイルに追加するには、次の手順を実行します。

  1. [管理] > [システム] > [ロギングとプロファイリング] に移動します。

  2. [別のパッケージ用にログ レベルを設定する] をクリックします。

  3. パッケージ名を次のように設定します。 

    com.atlassian.ratelimiting.internal.requesthandler.logging
  4. ロギング レベルを [DEBUG] に設定して [追加] をクリックします。

  5. レート制限されたすべてのリクエストが、Jira のログ ファイルに表示されるようになります。 

    [INFO] [talledLocalContainer] 2019-11-27 16:21:01,610 http-nio-2990-exec-6 DEBUG [internal.requesthandler.logging.RateLimitedRequestLogger] User [admin] has been rate limited for URL [http://localhost:2990/jira/rest/rate-limiting/latest/admin/rate-limit/settings]
    [INFO] [talledLocalContainer] 2019-11-27 16:24:29,014 http-nio-2990-exec-5 DEBUG [internal.requesthandler.logging.RateLimitedRequestLogger] User [admin] has been rate limited for URL [http://localhost:2990/jira/rest/rate-limiting/latest/admin/rate-limit/settings], pre-auth

レート制限とは - ユーザーの観点から

ユーザーが認証済みのリクエストを作成すると、レスポンスにレート制限のヘッダーが表示されます。これらのヘッダーはレート制限されているときだけでなく、すべてのレスポンスに追加されます。

ヘッダー説明

X-RateLimit-Limit

これまでに持つことができるリクエスト (トークン) の最大数。この制限に到達した後は、新しいトークンがバケットに追加されません。管理者はこれを [最大要求数] として設定します。

X-RateLimit-Remaining

トークンの残りの数。自身が現在保有していて、すぐに使用できるトークン数です。

X-RateLimit-Interval-Seconds

時間間隔 (秒単位)。この間隔ごとに新しいトークンのバッチを取得できます。

X-RateLimit-FillRate

時間間隔ごとに取得するトークンの数。管理者は、これを [許容要求数] として設定します。

retry-after

新しいトークンを取得するまでに待機する必要がある時間。

HTTP ステータス コード 429 で何度か失敗した後に、retry-after ヘッダーが 0 に設定されていれば、リクエストを正常に送信できます

ユーザーがレート制限を受けていてリクエストが処理されない場合、HTTP 429 エラー メッセージ (too many requests) が返されます。ユーザーはこのヘッダーを使用して、スクリプトや自動化を制限に合わせて調整し、妥当な頻度でリクエストを送信できます。

URL と外部アプリケーションの許可リスト

URL とリソースを許可リストに追加する

Jira インスタンスで URL 全体およびリソースを許可リストに登録する方法を追加しました。これを使用することで、レート制限されているが、制限されるべきではないものを、素早く修正できます。

使用すべきタイミング

たとえば、Marketplace アプリが新しい API を Jira に追加しました。アプリ自体は UI から使用されるため制限されるべきではありませんが、Jira がこのトラフィックを外部とみなし、レート制限を適用する可能性があります。その場合、アプリを無効化するかレート制限を増やすことができますが、これは複雑さを増すことになります。

このような問題を回避するには、アプリによって追加されたリソース全体を許可リストに追加し、それらが制限なしで動作するようにできます。

  1. [管理] > [システム] > [一般設定] に移動します。

  2. [高度な設定] をクリックします。

  3. com.atlassian.ratelimiting.whitelisted-url-patterns プロパティを見つけ、カンマ区切りリストの形式で URL を入力します。例: 

    /**/rest/applinks/**,/**/rest/capabilities,/**/rest/someapi

URL パターンの作成方法の詳細については「AntPathMatcher: URL patterns」を参照してください。

外部アプリケーションを許可リストに追加する

コンシューマー キーを許可リストに追加して、アプリケーション リンクを通じて連携された外部アプリケーションのレート制限を削除できます。

アトラシアン クラウド製品の場合、コンシューマー キーの取得方法は異なります。クラウド製品のレート制限を削除したい場合、「アトラシアン クラウド製品に対するレート制限の削除」を参照してください。

  1. アプリケーションのコンシューマー キーを見つけます。

    1. [管理] > [アプリケーション] > [アプリケーション リンク] に移動します。

    2. アプリケーションを見つけて [編集] をクリックします。

    3. [受信認証] を開き、コンシューマー キーをコピーします。

  2. コンシューマー キーを許可リストに追加します。

    1. [管理] > [システム] > [一般設定] に移動します。

    2. [高度な設定] をクリックします。

    3. com.atlassian.ratelimiting.whitelisted-oauth-consumers の値としてコンシューマー キーを入力します。コンマ区切りリストの形式で複数のコンシューマー キーを入力できます。

コンシューマー キーを入力すると、関連するアプリケーションからのトラフィックは制限されなくなります。

レート制限用にコードを調整する

コード (スクリプト、連携、アプリ) に適用してレート制限で使用できる、一連の戦略を作成しました。詳しくは、「レート制限用にコードを調整する」を参照してください。

既知の問題

Jira のレート制限設定が期待どおりに機能しない場合は、このナレッジ ベース記事で解決策をご確認ください

課題がリクエストのクッキーまたはヘッダーによるものかどうかを確認するには、このナレッジ ベース記事で修正についてご確認ください。

最終更新日 2023 年 4 月 19 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する

このセクションの項目

Powered by Confluence and Scroll Viewport.