f:id:khigashigashi:20190305134900j:plain — 出典： https://unsplash.com/photos/JKUTrJ4vK00

BASE BANK株式会社でソフトウェアエンジニアをやっている東口（@hgsgtk）です。即時に資金調達ができる金融サービス「YELL BANK(エールバンク)」というプロダクトを開発・運用しています。

さて、日々、ユーザーに使っていただくサービスを運営していく中で、「サービスを安定的に提供できているか」という観点において、監視する技法について関心があります。そんな折、『入門監視――モダンなモニタリングのためのデザインパターン』という書籍が最近発売され、世間的にも監視について、関心が高まっているかと思います。

今回は、この書籍の中から、実際に業務で実践していた「Health エンドポイントパターン」について、実践例と書籍の内容の深掘りを含めて紹介しようと思います。

また、Mackerel Meetup #13 Tokyoというイベントでも今回の内容を発表いたしましたので、こちらも合わせてご参照ください。

Health エンドポイントパターンとは

アプリケーションの健全性を伝えるアプリケーション内のHTTPエンドポイントを作るパターンです。カナリアエンドポイント（canary endpoint）・ステータスエンドポイント（status endpoint）とも呼ばれ、特に名前がついていることを知らずに使っている方も多いのではないでしょうか。（筆者もその一人でした。）

このエンドポイントでは、最低限「HTTPリクエストを受けてレスポンスを返せるか」という情報のみを返すこともできれば、デプロイされたバージョンや依存関係のあるDBなどのサブコンポーネントのステータスといった情報までをレスポンスに含めることもできます。

使用用途としては、次のようなケースがあげられます。

Mackerel など監視SaaSからの外形監視
ALBなどロードバランサのヘルスチェック
アプリケーション起動確認のデバッグ

実際に、実践する場合、アプリケーションの状態を伝えるHTTPエンドポイントを作成します。例えば、/healthcheckや/pingなどと言った名前になるでしょうか。そのエンドポイントは、ヘルスチェックに成功すればHTTPステータスコード200を、失敗した場合は200以外（特に503） を返すという実装になります。

BASE BANKでの実践例

BASE BANKでは、２つのエンドポイントを用途別に用意する方法をとっていて、それぞれ外形監視の対象としています。ひとつが、コンテナ単体の生存確認を主目的とした、/health、もう一つが、依存しているDB・Redisなどへの接続までを確認対象に含める、 /health/deep です。

なお、この実践例は、「Mackerel Meetup #13 Tokyo 」で山根 (@fumikony) より発表した、『BASEにおけるMackerel利用上の工夫と困りごとのご紹介』内でも事例として言及しております。Mackerel等の監視SaaSとの組み合わせという点では、合わせてこちらを一読いただけるとより良いかなと思います。

単体の生存確認: /health

Go言語で実際に実装する場合は、例えば次のようなHTTP Handlerになります。

// HTTPステータスをフィールドに含むレスポンスフォーマット
type SimpleResponse struct {
    Status  int    `json:"status"`
    Message string `json:"message,omitempty"`
    Detail  string `json:"string,omitempty"`
}

// 200レスポンスが返却される
func SimpleHealthCheck(w http.ResponseWriter, r *http.Request) {
    rs := SimpleResponse{
        Status: http.StatusOK,
    }
    respondJson(w, rs, http.StatusOK)
}

// JSON形式でレスポンスを返却する
func respondJson(w http.ResponseWriter, body interface{}, status int) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)
    if err := json.NewEncoder(w).Encode(body); err != nil {
        fmt.Fprintf(os.Stderr, "failed to encode response by error '%#v'", err)
        w.WriteHeader(http.StatusInternalServerError)
        return
    }
}

これを、/simple/.health_check に対してルーティング設定した場合は次のようなレスポンスとなります。

-> % curl -i http://localhost:8080/simple/.health_check     
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Mon, 04 Mar 2019 13:24:23 GMT
Content-Length: 15

{"status":200}

これは、ロードバランサからの外形監視などの際に利用しています。

依存サービス込みの動作確認: /health/deep

次に、DBやRedisなど依存している外部サービスに接続できているかどうかを確認対象に含めるエンドポイントです。

func SimpleDeepHealthCheck(w http.ResponseWriter, r *http.Request) {
    _, err := NewMySQL(config.DB)
    if err != nil {
        // DBへのコネクションにてエラーが発生した場合は503レスポンス
        rs := SimpleResponse{
            Status:  http.StatusServiceUnavailable,
            Message: "failed to get connection database",
            Detail:  err.Error(),
        }
        respondJson(w, rs, rs.Status)
        return
    }

    rs := SimpleResponse{
        Status:  http.StatusOK,
        Message: "success to connect server",
    }
    respondJson(w, rs, rs.Status)
}

これを、 /simple/.health_check/deep に対してルーティング設定した場合次のようなレスポンスが返却されます。

-> % curl -i http://localhost:8080/simple/.health_check/deep
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Mon, 04 Mar 2019 13:33:22 GMT
Content-Length: 53

{"status":200,"message":"success to connect server"}

例えば、データベースに対する接続が失敗した場合は、次のような503レスポンスが返却され、アプリケーションの健康状態について知ることができます。

-> % curl -i http://localhost:8080/simple/.health_check/deep
HTTP/1.1 503 Service Unavailable
Content-Type: application/json; charset=utf-8
Date: Mon, 04 Mar 2019 13:35:38 GMT
Content-Length: 106

{"status":503,"message":"failed to get connection database","string":"sql: connection is already closed"}

このパターンのエンドポイントは、Mackerelからの外形監視で主に利用しています。

利点

外形監視に利用できる

APIの通信ができるかといった外形監視は特にアプリケーションを運用していると最低限関心をもつところだと思います。このパターンでは、ステータスコードで状態を判別できるため、外形監視に使いやすいかと思います。

デバッグに有効

起動したアプリケーションが正しくHTTPリクエストを処理する事ができるかを知る上で、重宝しています。さらに、依存関係のあるDBなどのサービスへのコネクションが取れるかについても最低限確認できるため、起動確認に有用です。

余談：コンテナベースアプリケーションとの親和性

運用しているYELL BANKというサービスは、以前公開した『ECS(Fargate)でコンテナアプリケーションを動かすための設定情報の扱い方』という記事でも紹介した通り、コンテナ上で動作することを前提としたアプリケーションとして機能提供しています。コンテナ内で動かすアプリケーションにおいても、外形監視は重要と感じていますが、実際このパターンはコンテナベースアプリケーションにおいてはどのように考えられるでしょうか。コンテナベースアプリケーション設計として、「Health エンドポイントパターン」をどう評価できるかを考えるにあたり、redhatが公開している『Principles of container-based application design』から参考になる原則を一つ見てみましょう。

それが、「HIGH OBSERVABILITY PRINCIPLE (HOP) 高観測可能性の原則」という設計原則です。これは、コンテナ内部をブラックボックスのように扱う設計前提を持った上で、自身のアプリケーションの活動状況や準備状況など、様々な状態チェックについてAPIを提供するという設計について言及しています。

自身の健康状態を伝える「Health エンドポイントパターン」も、観測度を上げる上で有用なパターンと言えそうですね。

ドラフト段階の共通レスポンスフォーマットについて

さて、「Health エンドポイントパターン」について、パターンと実践について見たところで、少し話を深掘りして『Health Check Response Format for HTTP APIs 』という議論中の共通レスポンスフォーマットについて見ていきたいと思います。これは、『入門監視――モダンなモニタリングのためのデザインパターン』の「付録C」という章で言及されているものです。どういったレスポンスを返すべきか、議論中のこのフォーマットについて少し深掘りしてみます。

Health Check Response Format for HTTP APIs

このフォーマットは、大きく以下の3つの特徴を持ちます。

JSONフォーマットを利用する
media-typeは、application/health+json とする
必須フィールドである status といくつかのオプショナルなフィールドを含む

必須フィールド: status

status には「次のどれかの値を設定する」とされています。

pass: healthy
- status code: 2xx-3xx range (MUST)
- その他、下記の選択肢も可能
  - Node's Terminus をサポートするための ok
  - JavaのSpringBootのための up
fail: unhealthy
- status code: 4xx-5xx range (MUST)
- その他、下記の選択肢も可能
  - Node's Terminus をサポートするための error
  - JavaのSpringBootのための down
warn: healthy, with some concerns
- status code: 2xx-3xx range (MUST)

warningレベルのタイプが設定できるのは一つ面白いところかなと思いました。

その他フォーマット一覧

必須とされている status 以外にも次のフィールドがオプショナルな項目として提示されています。

status
version (optional) - サービスの公開バージョン
releaseId (optional)
notes (optional) - 健康状態に関する記述
output (optional) - 生のエラー出力、 statusがpassのときは省略すべき
details (optional) - 依存しているサービスも含めた詳細情報、The Details Object というオブジェクトで定義
links (optional) - より詳細情報を得るための外部URLなど
serviceId (optional) - アプリケーションスコープなユニーク識別子
description (optional) - 人間に優しい説明

The Details Object

下流の依存関係やRedisなどのアプリケーションから見たサブコンポーネントの状態を伝えるためのオブジェクトとして提示されています。公式の例では、以下のようにcassandraやcpu・memory状態などアプリケーションが依存するものについての健康状態を伝える例を示しています。

  "details": {
    "cassandra:responseTime": [
      {
        "componentId": "dfd6cf2b-1b6e-4412-a0b8-f6f7797a60d2",
        "componentType": "datastore",
        "observedValue": 250,
        "observedUnit": "ms",
        "status": "pass",
        "time": "2018-01-17T03:36:48Z",
        "output": ""
      }
    ],
    "cassandra:connections": [
      {
        "componentId": "dfd6cf2b-1b6e-4412-a0b8-f6f7797a60d2",
        "type": "datastore",
        "observedValue": 75,
        "status": "warn",
        "time": "2018-01-17T03:36:48Z",
        "output": "",
        "links": {
          "self": "http://api.example.com/dbnode/dfd6cf2b/health"
        }
      }
    ],
    "uptime": [
      {
        "componentType": "system",
        "observedValue": 1209600.245,
        "observedUnit": "s",
        "status": "pass",
        "time": "2018-01-17T03:36:48Z"
      }
    ],
 },