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

When automated integrations or scripts send requests to Confluence in huge bursts, it can affect Confluence’s stability, leading to drops in performance or even downtime. With rate limiting, you can control how many external REST API requests that automations and users can make and how often they can make them, making sure that your Confluence Data Center instance remains stable.


On this page:

レート制限の仕組み

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


リクエストの制限...

レート制限は外部 REST API リクエストのみを対象とします。つまり、Jira 内でのリクエストは制限されません。ユーザーによる Confluence 内の移動、コメントの追加、およびその他の操作の完了は、制限すべきでない通常のユーザー エクスペリエンスとみなされるため、レート制限の影響を受けません。

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

  • When a user visits a space in Confluence, a number of requests are sent in the background — these requests ask Confluence for the pages, blog posts, etc. Since this traffic is internal to Confluence, it won’t be rate-limited.
  • When the same user opens up the terminal on their laptop and sends a request (like the one below) to get the contents of a space, it will be rate limited because it’s made from outside of Confluence.

    curl -u user:password http://localhost:8090/rest/api/space/SPACEKEY/content

認証メカニズム

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

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

アトラシアンでは、レート制限に利用できる多数の技術の中から、リクエストに交換可能なトークンの残数をユーザーに示すトークン バケットを採用しました。トークン バケットの仕組みの概要は次のとおりです。

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

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

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

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

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

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

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

  • Data Center:制限されません。
  • クラウド製品: クラウド製品に送受信されるリクエストにレート制限が適用される、既知の問題があります。アトラシアンではクラウド製品に対するレート制限の無効化に取り組んでおり、近日中に提供を開始する予定です。現時点では、Confluence を Jira Cloud と連携する場合、通常よりもレート制限を高く設定する必要があります。
Atlassian Marketplace のアプリ...

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

  • 内部: アプリがユーザー エクスペリエンスの強化のために内部で動作している場合、それは制限されません。このようなアプリの例として、Confluence スペースに表示される特別なバナーなどがあります。このバナーは作成されたすべてのページを確認し、このスペースの勝者、つまり、先月もっとも多くのページを作成したユーザーを表示するとします。このようなトラフィックは内部のものになり、制限されません。
  • 外部: Confluence の外部でリクエスト行うアプリは制限されます。テレビにウォールボードを表示するアプリがあるとします。このアプリは、ボード、課題、担当者などの詳細を Jira から取得し、それらを再度シャッフルし、前述のウォールボードとして独自の方法で表示します。このようなアプリは外部リクエストを送信し、ターミナルからリクエストを送信するユーザーのように動作します。

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

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

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

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

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

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

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

適切な制限を見つける

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

  1. ユーザーの作業の中断は許可されますか? ユーザーによる連携機能がミッションクリティカルな場合、代わりにハードウェアをアップグレードすることをご検討ください。連携の重要性に応じて、制限も高く設定する必要があります。算出した数を 2 倍または 3 倍にすることをご検討ください。
  2. インスタンスですでに、REST トラフィックの量による問題が発生していますか? その場合、インスタンスで問題が発生しなかった日の基本値に近い制限を選択します。顕著な問題が発生していないのであれば、基本値に 50% を追加することをご検討ください。これにより、ユーザーの作業が中断されるのを防ぎながら、十分な容量を維持できます。

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


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

レート制限をオンにするには、システム管理者グローバル権限が必要です。 

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

  1. Confluence で、[管理] > [一般設定] > [レート制限] に移動します。
  2. ステータスを [有効] に変更します。
  3. 次のオプションのうち 1 つを選択します: 無制限のリクエストを許可すべてのリクエストをブロック、またはリクエストを制限。最初のオプションと 2 番目のオプションは許可リストとブロックリストに関連します。最後のオプションの場合、実際の制限を入力する必要はありません。詳細については以下をお読みください。
  4. Select Save to save your changes.

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

リクエストの制限 - 詳細

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

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

  1. 許可されているリクエスト数: 各ユーザーは、選択した期間に特定の件数のリクエストを許可されています。1 秒あたり 10 件のリクエスト、1 時間あたり 100 件のリクエストなどの任意のの設定を選択できます。
  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 時間で再度蓄積を開始することができます。

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

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

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

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

適切な制限を見つける

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

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

適切な制限を見つける

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

  1. ユーザーの作業の中断は許可されますか? ユーザーによる連携機能がミッションクリティカルな場合、代わりにハードウェアをアップグレードすることをご検討ください。連携の重要性に応じて、制限も高く設定する必要があります。算出した数を 2 倍または 3 倍にすることをご検討ください。
  2. インスタンスですでに、REST トラフィックの量による問題が発生していますか? その場合、インスタンスで問題が発生しなかった日の基本値に近い制限を選択します。顕著な問題が発生していないのであれば、基本値に 50% を追加することをご検討ください。これにより、ユーザーの作業が中断されるのを防ぎながら、十分な容量を維持できます。

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

例外の追加

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

tip/resting Created with Sketch.

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

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

  1. [例外] タブに移動します。
  2. [適用除外を追加] をクリックします。
  3. ユーザーを見つけ、そのユーザーのための新しい設定を選択します。グループを選択することはできませんが、複数のユーザーを選択できます。
  4. ここで利用可能なオプションはグローバルな設定の場合と同じです: "無制限のリクエストを許可"、"すべてのリクエストをブロック "、"カスタム制限を割り当て"。
  5. Select Save to save your changes.

If you want to edit an exemption later, just select Edit next to a user’s name in the Exemptions tab.

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

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

Identifying users who have been rate-limited

When a user is rate-limited, they’ll know immediately as they’ll receive an HTTP 429 error message (too many requests). You can identify users that have been rate-limited by opening the List of limited accounts tab on the rate limiting settings page. The list shows all users from the whole cluster.

tip/resting Created with Sketch.

When a user is rate-limited, it takes up to 5 minutes to show it in the table.


異常なアカウント

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

  • Unknown: That’s a user that has been deleted in Confluence. They shouldn’t appear on the list for more than 24 hours (as they can’t be rate-limited anymore), but you might see them in the list of exemptions. Just delete any settings for them, they don’t need rate limiting anymore.
  • Anonymous: このエントリは、認証されていないアカウントから行われたすべてのリクエストを収集します。1 人のユーザーで匿名アクセスの制限までのリクエスト数を簡単に使用できてしまうことがあるため、匿名トラフィックに例外を追加して、高い制限値を追加することをおすすめします。

Confluence のログ ファイルで制限付きのリクエストを表示する

You can also view information about rate-limited users and requests in the Confluence log file. This is useful if you want to get more details about the URLs that requests targeted or originated from.

When a request has been rate-limited you’ll see a log entry similar to this one:

2019-12-24 10:18:23,265 WARN [http-nio-8090-exec-7] [ratelimiting.internal.filter.RateLimitFilter] lambda$userHasBeenRateLimited$0 User [2c9d88986ee7cdaa016ee7d40bd20002] has been rate limited
 -- url: /rest/api/space/DS/content | traceId: 30c0edcb94620c83 | userName: exampleuser

Getting rate-limited — user’s perspective

When users make authenticated requests, they’ll see rate limiting headers in the response. These headers are added to every response, not just when you’re rate-limited.

ヘッダー

説明

X-RateLimit-Limit保有できるリクエスト (トークン) の最大数。この制限に到達した後は、新しいトークンがバケットに追加されません。管理者はこれを最大リクエスト数として設定します。
X-RateLimit-Remainingトークンの残りの数。この値はリクエストの実行時には非常に正確ですが、常に正確であるとは限りません。
X-RateLimit-Interval-Seconds

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

X-RateLimit-FillRate

時間間隔ごとに取得するトークンの数。管理者は、これを許可されるリクエスト数として設定します。

retry-after

新しいトークンを取得するまでに待機する必要がある時間。まだトークンが残っている場合は 0 を示し、すぐに追加でリクエストを実行できることを意味します。

When you’re rate-limited and your request doesn’t go through, you’ll see the HTTP 429 error message (too many requests). You can use these headers to adjust scripts and automation to your limits, making them send requests at a reasonable frequency.

その他のタスク

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

We’ve also added a way to allow whole URLs and resources on your Confluence instance using a system property. This should be used as quick fix for something that gets rate-limited, but shouldn’t.

使用すべきタイミング

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

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

特定の URL をレート制限から除外することを許可するには、次の手順を実行します。

  1. Confluence を停止します。
  2. com.atlassian.ratelimiting.whitelisted-url-patterns システム プロパティを追加し、値を URL のカンマ区切りリストに設定します。例:

    -Dcom.atlassian.ratelimiting.whitelisted-url-patterns=/**/rest/applinks/**,/**/rest/capabilities,/**/rest/someapi


    システム プロパティの追加方法は、Confluence の実行方法によって異なります。詳細については、「システム プロパティを設定する」を参照してください。

  3. Confluence を再起動します。

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

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

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

Confluence を他のアトラシアン製品と連携する場合、それらのトラフィックは制限されないため、許可リストに追加する必要はありません。


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

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

    2. Find your application, and select Edit.

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

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

    1. Confluence を停止します。

    2. com.atlassian.ratelimiting.whitelisted-oauth-consumers システム プロパティを追加し、値をコンシューマー キーのカンマ区切りリストに設定します。例: 

      -Dcom.atlassian.ratelimiting.whitelisted-oauth-consumers=app-connector-for-confluence-server

      システム プロパティの追加方法は、Confluence の実行方法によって異なります。詳細については、「システム プロパティを設定する」を参照してください。

    3. Confluence を再起動します。

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

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

コード (スクリプト、連携、アプリ) に適用してレート制限で使用できる、一連の戦略を作成しました。

詳細は、「レート制限用にコードを調整する」を参照してください。

最終更新日: 2024 年 12 月 6 日

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

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

このセクションの項目

Powered by Confluence and Scroll Viewport.