こんにちは、Necoチームの池添(@zoetro)です。
gofailは、etcdの開発チームがつくったFailure Injectionのためのツールです。 Go言語で書かれたプログラム中に故意にエラーを発生させるポイント(failpoint)を埋め込み、任意のタイミングでプログラムの挙動を変えることができます。 公式ドキュメントに記載されていない項目が多々あるので、詳しい使い方を紹介したいと思います。
なお、本記事は2018年8月時点のソースコードを対象に解説しています。
gofailのインストール
gofail をインストールします。
$ go get -u github.com/etcd-io/gofail/...
failpointの埋め込み
プログラム中にfailpointを埋め込むためには、Go言語のプログラム中に gofail
というキーワードから始まるコメントを記述します。
なお、ブロックコメントの場合はfailpointとして認識されないため、必ず行コメントで記述する必要があります。
コメントの1行目にはトリガーとなる変数定義を記述し、2行目以降にはfailpointを有効化した時に実行されるコードを記述することができます。 複数行の処理を埋め込みたい場合は、空行をあけずにコメントを記述します。
例えば任意の値を返すようなfailpointを埋め込みたい場合は、下記のように1行目に返す値となる変数宣言、2行目にreturnを記述します。
func someFunc() string { // gofail: var SomeFuncString string // return SomeFuncString return "default" }
なお、failpointとなる変数の型は bool
, int
, string
, struct{}
のみになります。
fail発生後に任意の処理を実行する必要がない場合(panicを発生させる場合など)は、以下のように struct {}
型の変数宣言のみを記述します。
func ExampleOneLineFunc() string { // gofail: var ExampleOneLine struct{} return "abc" }
failpointを有効化した時にgotoやラベル付きcontinue文を実行したい場合は、下記のように gofail の後ろにラベル名を記述することもできます。
func ExampleRetry() { // gofail: RETRY: for i := 0; ; i++ { fmt.Println(i) time.Sleep(time.Second) // gofail: var RetryLabel struct{} // goto RETRY } }
failpointを埋め込んでビルド
failpointを埋め込んでビルドするには、まず下記のコマンドを実行します。
$ gofail enable
するとgofailから始まるコメントを記述した箇所が書き換えられ、*.fail.go
というファイルが生成されます。
あとは生成されたコードを含めて通常通りにビルドします。
書き換えられたコードをもとに戻すには、以下のコマンドを実行します。
$ gofail disable
failpointの有効化
埋め込まれたfailpointは初期状態ではoffになっているので、実際にfailさせるためにはfailpointの有効化をおこなう必要があります。 failpointを有効化させる手段としては、プログラムの起動時に環境変数で指定するかHTTP APIで有効化するか2通りの方法がありますが、ここではHTTP APIを利用した方法を紹介します。
まずgofailのエンドポイントを環境変数で指定してプログラムを起動します。
GOFAIL_HTTP="127.0.0.1:1234" ./cmd
下記のAPIを叩くと、failpointの一覧を取得することができます。
$ curl http://127.0.0.1:1234/ my/package/path/SomeFuncString= my/package/path/ExampleOneLine= my/package/path/ExampleLabels=
failpointを有効化するためには下記のAPIを実行します。
ここでは、SomeFuncString
が hello
という文字列を返すように設定しています。
$ curl http://127.0.0.1:1234/my/package/path/SomeFuncString -XPUT -d'return("hello")'
再度下記のAPIを実行すると、failpointが設定されていることが確認できます。
$ curl http://127.0.0.1:1234/ my/package/path/SomeFuncString=return("hello") my/package/path/ExampleOneLine= my/package/path/ExampleLabels=
この状態でsomeFunc()
関数が実行されると、hello
という文字列が返ってくるようになります。
failpointを無効化するには下記のAPIを実行します。
$ curl http://127.0.0.1:1234/my/package/path/SomeFuncString -XDELETE
failpointで実行可能なアクション
failpointには、下記のアクションを指定することができます。
- off: failpointの無効化
- return: 任意の値を返す(返すことのできる型は bool, int, string, struct{} のみ)
- sleep: 一定時間待つ(待ち時間はDurationフォーマットで指定可能。intで指定した場合はミリ秒になる)
- panic: panicを発生させる
- break: デバッガによるbreakを発生させる
- print: 標準出力に文字列を出力する
また、failを発生させる回数や確率を指定することもできます。
下記の例では、failpointが呼び出された最初の3回はhello
という文字列を返し、その後は通常の状態に戻ります。
$ curl http://127.0.0.1:1234/my/package/path/SomeFuncString -XPUT -d'3*return("hello")'
下記の例では、50%の確率でhello
を返すようになります。
$ curl http://127.0.0.1:1234/my/package/path/SomeFuncString -XPUT -d'50.0%return("hello")'
おわりに
gofailを利用すると任意のタイミングでソフトウェアの挙動を変えることができ、Failure Injection Testをおこなう際にはとても便利なので、ぜひ使ってみてください。
我々はgofailを利用した耐障害性試験を実施し、信頼性の高いインフラ基盤の構築を進めています。次回の記事ではそのあたりを詳しく紹介したいと思います。