Skip to content

Instantly share code, notes, and snippets.

@motoki317

motoki317/manual.md

Last active September 19, 2021 14:23
Show Gist options
  • Save motoki317/4aab0ecedf5cc150060d2e857e95895b to your computer and use it in GitHub Desktop.
Save motoki317/4aab0ecedf5cc150060d2e857e95895b to your computer and use it in GitHub Desktop.
Download ZIP
Raw
manual.md

ISUCON11 本選当日マニュアル

スケジュール

  • 10:00 競技開始
  • 17:00 リーダーボードの更新停止
  • 18:00 競技終了
  • 翌 18:00 結果発表イベント開始

課題アプリケーション ISUCHOLAR について

課題アプリケーション ISUCHOLAR の仕様については、ISUCHOLAR アプリケーションマニュアル を参照してください。

ISUCON11 ポータルサイト（ポータル）

ISUCON11 の競技では下記のウェブサイトを利用します。事前に登録した情報を用いてログインしてください。 なお、このページは競技終了後にアクセスできなくなります。

ポータルでは、負荷走行（ベンチマーク）の実行/結果確認、質問/サポート依頼（以下、質問）の送信、リーダーボードの確認ができます。

https://portal.isucon.net/contestant

リーダーボードの更新について

ポータル上のリーダーボードは、競技終了 1 時間前に他チームの情報が更新されなくなり、自チームの情報のみ更新されます。

Discord の利用について

ISUCON11 サポート Discord サーバーは競技中ならびにその前後の時間はすべてのチャンネルが発言不可となります。 競技時間中はポータルを通して質問を送信することができますので、そちらを利用してください。

ただし、選手は競技時間中も Discord の確認が可能な状態、通知が受け取れる状態を維持してください。 これは主催者が選手とリアルタイムでのチャットが必要だと判断した場合、主催者が Discord 上でプライベートチャンネルを作成しメンションの上、呼びかけを行う場合があるためです。呼びかけに応じない場合、競技に支障をきたす可能性があるため、必ず応答可能な状態を維持してください。

また、主催者からのアナウンス等も Discord で実施されます。

質問について

選手は主催者へ質問を送信することができます。質問は競技内容・マニュアル・レギュレーション等に対する疑問点の確認や、サーバー障害などのトラブル報告・サポート依頼に利用することができますが、これに限りません。

主催者は質問された内容が競技の一環である場合は、回答できない旨を返答することがあります。

競技時間中の質問について、主催者からの回答は全選手へ公開、あるいは個別に回答されます。全選手へ公開される場合、質問内容の原文、あるいは主催者による内容の要約が公開されます。未回答の質問・未公開の回答については質問した選手およびそのチームメンバー、主催者のみが確認できます。質問への回答・更新はポータル上にて選手およびそのチームへ通知されます。

主催者は競技時間中の質問への回答を、原則として全選手へ公開します。ただし、重複する質問や、選手およびチーム個別の問題に対する対応の場合、この限りではありません。

補填について

選手は主催者側の不具合（例： ベンチマーカーや参考実装、ポータル）が疑われる状況や、その他疑問点について、 速やかに質問を送信することが推奨されます。

主催者側の責によって特定のチームの競技進行に不利益が認められる場合、主催者はそのチームに対して競技時間の補填を行うことがあります。この際の補填時間は、不具合等を主催者が認識してからそれが解決されるまでにかかった時間を基準に算出します。つまり、選手は疑問点や不具合の報告を速やかに行うことで、競技進行に支障があった時間を客観的に明らかにすることができるため、主催者はこれを推奨します。

なお、全チームで確実かつ同様に発生する不具合（例： ベンチマーカーの不具合）は特定チームにおける競技進行の妨げとはならないため、基本的に補填の対象としません。補填の対象になる例としては、主催者側のミスで特定チームのみサーバーへ接続できない状態（設定不備）などが挙げられます。

サポート対象外の事項

主催者が事前に Discord サーバー等で告知していた通り、下記はサポート対象外となります。

  • スポンサー各社が提供しているサービスについての質問

競技環境について

本選では、競技に必要なすべてのサーバーを主催者が用意します。

サーバー、ネットワーク構成について

主催者はチームに対してサーバーを 3 台ずつ提供します（以下、競技用サーバー）。選手は競技用サーバーに SSH 接続し、競技に参加します。

選手はポータルのサーバーリストページで割り当てられた競技用サーバーの情報を確認できます。

競技環境の再起動あるいは初期化について

選手自らが設定変更等により競技環境を破壊するなどして、主催者による再起動あるいは初期化が必要になった場合はポータルからサポートを依頼してください。 初期化以前の競技環境上で変更を加えたソースコードや設定ファイル等の移行が必要な場合は、各チームの責任で行ってください。

重要事項

  • 競技に利用できる計算機資源は主催者が用意した 3 台のサーバーのみです。
    • モニタリングやテスト、開発において外部の資源を用いても構いませんが（例： メトリクス計測サービス）、スコアを向上させるいかなる効果を持つものであってはいけません。
  • 競技終了後は、主催者が追試を行います。Discord サーバーにて主催者がアナウンスをするまで、競技環境の操作をしないでください。
    • 競技終了後、別途アナウンスがあるまでに作業を行ったチームは失格となります。
  • その他、主催者による追試を妨げる変更（例： サーバー上の isucon 以外のユーザーに関する、ユーザー削除や既存の公開鍵の削除）を行ってはいけません。

アプリケーションの動作確認

ISUCHOLAR は Web ブラウザから HTTPS で利用することができます。 サーバーのポートは SSH 接続用の 22 番以外開放されていないため、ブラウザを使って動作確認する場合は SSH を使ったローカルポートフォワーディングなどを利用してください。

以下に SSH を使ってローカルポートフォワーディングする例を示します。 これは「リモートホスト 192.0.2.1 にユーザー名 isucon で SSH 接続をして」、その間は「ローカルから見た localhost:8443 への TCP 接続を」「リモートホストから見た localhost:443 へ転送する」というコマンドです。

ssh -L localhost:8443:localhost:443 isucon@192.0.2.1

サーバーへ配置されている TLS 証明書の subject name は *.t.isucon.dev となっています。 *.t.isucon.dev の DNS レコードは 127.0.0.1, ::1 が設定されているため、 t.isucon.dev のサブドメインを利用して localhost のポートへアクセスすることで、TLS 証明書検証エラーを回避することができます。

以上を踏まえると、上記のコマンドで SSH 接続している間は https://isucholar.t.isucon.dev:8443 でアプリケーションにアクセスすることができます。

ISUCHOLAR へのログイン

ISUCHOLAR には、学内コードとパスワードを使ってログインできます。

ベンチマーカーが利用する学生・教員ユーザーには S00000・T00000 が必ず含まれます。 S00000・T00000 ユーザーを用いることで、負荷走行後のアプリケーションの状態確認が可能です。 また、S99999・T99999 ユーザーには動作確認用の初期データが存在します。

学内コード パスワード
学生 S00000 isucon
教員 T00000 isucon
学生 S99999 isucon
教員 T99999 isucon

負荷走行 （ベンチマーク） の実行

負荷走行はポータル上からリクエストします。

ポータル にアクセスし、「Job Enqueue Form」から負荷走行対象のサーバーを選択、「Enqueue」をクリックすることで負荷走行をリクエストできます。

なお、負荷走行が待機中（PENDING）もしくは実行中（RUNNING）の間は追加でリクエストできません。

参考実装

下記の言語での実装が提供されています。

  • Go
  • Node.js
  • PHP
  • Ruby
  • Rust

参考実装の切り替え方法

初期状態では Go による実装が起動しています。

各参考実装は systemd で管理されています。 例えば、参考実装を Go から Ruby に切り替えるには以下のコマンドを実行します。

sudo systemctl disable --now isucholar.go.service

sudo systemctl enable --now isucholar.ruby.service

PHP への切り替え

ただし、PHP を使う場合のみ、systemd の設定変更の他に、以下のような nginx の設定変更が必要です。

sudo unlink /etc/nginx/sites-enabled/isucholar.conf
sudo ln -s /etc/nginx/sites-available/isucholar-php.conf /etc/nginx/sites-enabled/isucholar-php.conf
sudo systemctl restart nginx.service

アプリケーションのデータの初期化処理について

参考実装では、初期化処理（POST /initialize）においてデータベースを初期状態に戻します。 処理の変更・データ構造の変更などを行う場合は、動作に支障が無いように変更してください。

負荷走行について

ベンチマーカーによる負荷走行は以下のように実施されます。

  1. 初期化処理の実行 POST /initialize（最大 20 秒）
  2. アプリケーション互換性チェック（数秒～数十秒）
  3. 初期化処理の実行 POST /initialize（最大 20 秒）
  4. 負荷走行（60 秒）
  5. リトライ処理（10 秒）
  6. 整合性チェック（数秒～数十秒）

ベンチマーカーはリトライ処理で、負荷走行中にタイムアウトしたリクエストのリトライを行うことがあります。

初期化処理、アプリケーション互換性チェック、整合性チェックのいずれか 1 つでも失敗すると、負荷走行は即時失敗（fail）になります。

リダイレクトについて

ベンチマーカーは HTTP リダイレクトを処理しません。

データの更新の反映について

ベンチマーカーはデータの更新が即時反映されていることを期待して検証を行います。 ただし、アプリケーションはベンチマーカーが検知しない限りは古い情報を返しても構いません。

Conditional GET のサポートについて

ベンチマーカーは一般的なブラウザの挙動を模した Conditional GET に対応しています。

アプリケーションは、 Cache-Control やその他必要なレスポンスヘッダを返すことで、ベンチマーカーから Conditional GET リクエストを受けることができます。 304 Not Modified が返された場合や、ブラウザのキャッシュ有効期限の制御によってリクエストが発生しなかった場合でも、ベンチマーカーはそれらのキャッシュを利用してレスポンスがあったものとみなします。

なお、ベンチマーカー内のユーザーは独立しているため、 Cache-Control: public 等が指定されていたとしても、ユーザー同士でキャッシュを共有することはありません。

ページングについて

アプリケーションは Link レスポンスヘッダーを送信することがありますが、ベンチマーカーは RFC8288 に準拠した解釈は行いません。URL のパス部、クエリ部の変更は許容されています。

なお、ベンチマーカーは参考実装をブラウザで閲覧した際の挙動と同様の動作をします。

お知らせのIDについて

お知らせ追加（POST /api/announcements）時に送られてくるお知らせの ID は一意であることが保証されます。

誤差について

成績確認（GET /api/users/me/grades）のレスポンスに含まれる以下の値については、0.01 以下の絶対誤差を許容します。

  • 科目の総合点の平均値（total_score_avg）・偏差値（total_score_t_score）
  • GPA の値（gpa）・最大値（gpa_max）・最小値（gpa_min）・平均値（gpa_avg）・偏差値（gpa_t_score）

UIとの整合性について

ベンチマーカーが模倣する学生ユーザーは検索結果に含まれない科目の履修を行うことがあります。これは参考実装で提供されている UI では不可能な挙動です（参考実装の UI 側の既知の不具合です）。

タイムアウトについて

負荷走行において設定されているタイムアウト値は下記の通りです。

  • POST /initialize
    • 20 秒以内にレスポンスを返す必要があります。これを超えた場合、負荷走行は即時失敗（fail）します。
  • 上記以外の HTTP リクエスト
    • 5 秒以内にレスポンスを返す必要があります。これを超えた場合、後述のスコア計算に従い減点の対象となります。

スコア計算

アプリケーション互換性チェックを通過し負荷走行が開始されると、下記の通り加点・減点が行われます。 加点対象のリクエストは、負荷走行中に送信されたリクエストのみです。（負荷走行について）

アプリケーション互換性チェックや、負荷走行後のリトライ処理で送信されたリクエストは加点・減点対象ではありません。

負荷走行時における加点について

  • 課題の提出（POST /api/courses/:courseID/classes/:classID/assignments）に成功した場合
    • 1 回あたり 3 点
  • お知らせ一覧の取得（GET /api/announcements）に成功した場合
    • 1 回あたり 1 点

負荷走行時における減点、即時失敗（fail）について

下記のエラーは減点や即時失敗（fail）となります。fail となった場合、スコアは 0 点となります。

  • 初期化処理、アプリケーション互換性チェック、整合性チェックのいずれかに失敗した場合

    • 1 回以上で fail

  • HTTP ステータスコードやレスポンス内容などに誤りがある場合

    • 1 回あたり減点 50 点
    • 100 回を超えた時点で fail

  • リクエストがタイムアウトした場合（タイムアウトについて）

    • 100 回あたり減点 100 点
    • fail は発生しない

特別賞

  • 競技中のスコアが、最初に 80,000 点に到達した 1 チームを特別賞とします。

追試と最終スコア

競技終了後、以下の手順で追試を行い最終スコアを決定します。

  1. 全チームのサーバーを再起動し、10 分以上待ちます。
    • 再起動は「主催者がサーバーに SSH 接続し sudo systemctl poweroff によるシャットダウンを行った後、AWS のインスタンス起動 API（ec2:StartInstances）で起動する」という手順で行います。
    • 確実にシステムを再起動するため、再起動手順をこのように定義していますが、競技時間中に再起動をテストする場合は sudo systemctl reboot 等で実施してください。
    • すでにシャットダウンされているなどの理由により、sudo systemctl poweroffを実行できなかったサーバーが存在する場合は失格となります。
  2. 全チームに対してベンチマークを実行します。
    • 競技時間中に最後の負荷走行の対象となったサーバーに対して 負荷走行を行います。
    • 計測は各チーム 3 回ずつ実施します。
  3. （2）で実施した最後の負荷走行が fail となっているチームに関しては、再度計測を実施します。
    • この際、再度 fail となったチームは失格となります。
  4. 全チームのサーバーを（1）と同手順で再起動し、ブラウザから動作確認を行います。
    • この際、正常な動作が確認できなかったチームは失格となります。
    • 負荷走行実行時にアプリケーションに書き込まれたデータが、サーバー再起動後にも取得できることが確認できなかった場合も失格となります。
    • 主催者の作業日程の都合上、（4）で実施する sudo systemctl poweroff 以降の作業は翌日になることが見込まれています。つまり、シャットダウンから起動までに時間が大きく経過することがあります。
  5. （2）の負荷走行で計測したスコアのうち、最も高いスコアをそのチームの最終スコアとします。
    • fail は 0 点として数えます。

その他

POST /initialize での実装言語の出力

POST /initialize のレスポンスにて、本競技で利用した言語を出力してください。 参考実装はそのようになっています。 この情報は集計し ISUCON 公式Blog で公表する他、今後の運営の参考情報として利用させていただきます。

POST /initialize のレスポンスは以下のような JSON となります。

{
  "language": "実装言語"
}

language の値が実装に利用した言語となります。 language が空の場合は初期化処理が失敗と見なされます。

レギュレーション

ソフトウェア事項

選手には主催者から Web アプリケーション（問題）が与えられ、競技時間内にその Web アプリケーションの高速化を行う。選手は高速化された実装（回答）を作成する時、主催者より与えられたソフトウェア（参考実装）をベースに実装しても良いし、しなくても良い。 各参考実装の性能が一致することは保証されない。

環境

本選では OS として Ubuntu、初期実装として Go, Node.js, PHP, Ruby, Rust での実装を提供する。

高速化の際、主催者より問題として与えられた Web アプリケーションから、以下の部分は変更しないこと。

  • アクセス先の URI
    • サーバー側で生成する部分（ID など）は文字種（[0-9] や [0-9a-zA-Z_] など）を変えない範囲で自由に生成しても良い
  • レスポンス（JSON オブジェクト等）の構造
  • HTML/JavaScript/CSS ファイルの内容
  • 画像および動画等のメディアファイルの内容

各サーバーにおけるソフトウェアの入れ替え、設定の変更、アプリケーションコードの変更および入れ替えなどは一切禁止しない。 ベンチマーク中にポータル・マニュアル・レギュレーションといった、主催者の指示以外で利用が認められたサーバー以外の外部リソースを使用する行為（他のサーバーに処理を委譲するなど）は禁止する。 ただしモニタリングやテスト、開発などにおいては、PC や外部のサーバーを利用しても構わない。

許可される事項には、例として以下のような作業が含まれる。

  • 複数台あるサーバーの役割の変更
  • データベーススキーマの変更やインデックスの作成・削除
  • データベースに利用するミドルウェアの変更
  • キャッシュ機構の追加、ジョブキュー機構の追加による遅延書き込み
  • 他の言語による再実装

ただし以下の事項に留意すること。

  • コンテスト進行用のメンテナンスコマンドが正常に動作するよう互換性を保つこと
  • サーバー起動後にすべてのアプリケーションコードが正常動作する状態を維持すること
  • ベンチマーク実行時にアプリケーションに書き込まれたデータは再起動後にも取得できること

禁止事項

以下の行為を特に禁止する。

  • 競技終了時間までに、競技の内容に関するあらゆる事項（問題内容・計測ツールの計測方法など）を公開・共有すること（内容を推察できる発言も含む）
    • 不特定多数への公開はもちろん、他チームの選手と連絡を取り、問題内容等を共有する事（結託行為）も禁止とする。
    • ただし主催者が Twitter, Web サイトにおいて公開している情報は除く。ポータルでログインを要するページ（選手が参加する Discord を含む）において記載されている内容は公開情報でない旨留意すること。
  • 競技時間中、チーム外の人物と ISUCON11 問題にまつわる事項のやりとり（ISUCON11 選手であるかどうかを問わない、SNS での発言も含む）
  • 主催者の指示以外で利用が認められたサーバー以外の外部リソースを使用する行為（他のサーバーに処理を委譲するなど）は禁止する。
    • ただしモニタリングやテスト、開発などにおいては、PC や外部のサーバーを利用しても構わない。
  • 選手が主催者からその選手が属するチームへ提供されていないサーバーについて直接のアクセスを試みる行為や、外部への不正アクセスを試みる行為。具体的にはベンチマーカーへのログイン試行等。（なお、例示のため、これに限らない）
  • 他チームと結託する行為（程度を問わず）
  • 主催者が他チームへの妨害、競技への支障となるとみなす全ての行為

本マニュアルやポータルにおいて禁止とされた行為（禁止事項）への違反は、失格となる。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment