Datadog Monitor で GraphQL API のエラー数を監視する

こんにちは。STORES のエンジニアの takeuchi です。

STOERSでは、GraphQL を使用した API 開発を行っています。GraphQL のエラーは Content-Type が application/json である場合、HTTP ステータスコードを200で返しレスポンスボディでにエラー情報を含めることが推奨されています。

REST API でエラーを監視する場合、HTTP ステータスコードを利用できます。それに対して、エラーを HTTP ステータスコード 200で返す場合、HTTP ステータスコードのみによるエラーの検知ができないため、エラー数の増加を検知するには工夫が必要です。

本記事では、Datadog Monitor を活用して GraphQL エラーの発生件数を監視し、アラートを発生する仕組みを構築する方法を紹介します。

なお、STORES Advent Calendar 2024 の12日目の記事になります。

Datadog Monitor の概要

Datadog はクラウドアプリケーションのモニタリングを提供するSaaSプラットフォームです。

Datadog には、アプリケーションの異常を検知しアラートを発生させる Monitor 機能があります。特定のメトリクスやネットワークエンドポイントを監視し、あるしきい値を上回る、または下回る場合にアラートを発生させることができます。

発生したアラートは Slack やメールなどで通知できます。

Metric Monitor を利用したエラー数監視

新しい Monitor を作成する際には、まず監視対象の種類を選択します。

HTTP リクエストのエラー数を単純に監視する場合、Monitor の種類を Metric に設定し、監視するメトリクスとして trace.<SPAN_NAME>.hits.by_http_status を選択します。

ただし、HTTP ステータスコードが200であってもエラーが発生している可能性がある場合では、この方法で正確なエラー検知が難しいです。

Datadog Trace Analytics Monitor を活用する

Trace Analytics Monitor

GraphQL エラーの監視ではリクエストのより詳細な情報を必要とするため、Datadog の Datadog APM Monitor の一種である Trace Analytics Monitor を使用します。

Trace Analytics Monitor は、トレース(Trace) というリクエスト全体の処理フローを表す単位を監視します。特定の条件を設定し、その条件に合致するトレースだけを対象に監視を行うことが可能です。

トレースとスパン

トレース（Trace）: リクエスト全体の処理に費やされた時間とステータスを追跡する。1 つまたは複数のスパンから構成される
スパン（Span）: トレース内の1つの作業単位であり、複数のスパンが集まってトレースを構成する

Trace Analytics Monitor は、Trace Explorer と同じ検索クエリを使用して監視対象を設定できます。

タグを使いエラー情報をトレースに記録する

エラー発生時にアプリケーションからトレースにエラー情報を記録することで、エラーが発生したリクエストをトレースから判別することができます。

エラーの情報をトレースに記録するために、Datadog のタグ機能を活用します。トレースにタグを追加すると、タグを検索条件として設定し Trace Analytics Monitor で監視対象のトレースを絞り込むことができます。

今回この Monitor を導入した STORES のアプリケーションでは、GraphQL のエラー情報をレスポンスの errors に含めず、FieldErrorというデータ型を導入し、このスキーマに沿ったレスポンスを返すような設計になっています。そのため、エラーが発生したトレースの Datadog のタグのキーは field_errors という名前で追加し、値にはエラーの種類を設定しています。

上記の GraphQL のエラー設計については yubrot さんの記事に詳しく書かれています。

product.st.inc

以下は、Datadog の Ruby ライブラリを使用し、エラーをタグに追加する Ruby のコードです。

def add_datadog_trace_tag(error_type)
  # アクティブなトレースを取得
  active_trace = Datadog::Tracing.active_trace

  # トレースにタグを追加
  active_trace&.set_tag("field_errors", error_type)
end

上記の処理をアプリケーションでエラー発生時に呼び出すことにより、トレースにタグが設定できます。今回の Monitor を導入した STORES のアプリケーションでは、このような処理を GraphQL API の処理でエラーが発生した際に呼び出すよう実装しています。

Trace Explorer でエラー発生時に追加したタグを検索条件として指定すると、タグが設定されたトレースが出力されることが確認できます。

Trace Analytics Monitor の設定で発生した問題

トレースが検出されない

Trace Explorer ではタグの絞り込みはできていましたが、Trace Explorer と同じ絞り込みの条件を設定しても Trace Analytics Monitor でトレースが検出されませんでした。

改めてドキュメントを確認すると、Datadog でスパンを保存する設定が影響していることがわかりました。

Note: Analytics monitors can only be created based on spans retained by custom retention filters (not the intelligent retention filter).

Trace Analytics Monitor は custiom retention filter によって保存されたスパンのみを監視でき、intelligent retention filter によって保存されたスパンは監視できない旨が書いてあります。

Datadog のスパン保存の設定

トレースは複数のスパンで構成されており、トレースの監視にはそのトレースを構成するスパンが Datadog に保存されていることが前提となります。そのため、スパンの保存設定がトレースの検出に影響を与えます。

Datadog Agent から送信されたスパンが保存されるかどうかは Retention Filter によって決まります。

デフォルトでは intelligent retention filter が有効で、このフィルターは Datadog Agent から送信されたスパンから重要なスパンを自動的に選別し保存します。 Trace Analytics Monitor ではこのフィルターによって保存されたトレースを監視することはできませんが、Trace Explorer では検索・表示が可能です。

custom retention filter の作成

Trace Analytics Monitor で監視するトレースは custom retention filter によって保存されている必要があります。エラー情報がタグに記録されたトレースを保存するため、ドキュメントに従い custom retention filter を作成します。

エラー発生時に記録したタグを指定し、割合を100%に設定します。

この設定により、Trace Analytics Monitor でエラーのタグが記録されているトレースを検出できるようになります。

アラートの設定

custom retention filter を作成後、Trace Analytics Monitor を設定します。

トレースの検索のクエリとアラートの条件、メッセージの設定が完了すると Monitor が作成できます。画像の設定では直近の5分間のエラーのトレースの数が3つを超えるとワーニング、5つを超えるとアラートが発生します。

これで、GraphQL エラーを監視する Monitor が作成できます。

Slackインテグレーションを設定し、アラート発生時にSlack のチャンネルに連携することも可能です。

おわりに

今回は Datadog Monitor で GraphQL API のエラーを監視する方法について紹介しました。 REST API とは異なる部分でエラー監視には一手間が必要ですが、Datadog Monitor では柔軟に監視対象を設定することができました。安定したサービス運用を目指し、引き続き Datadog を活用していきたいと思います。