👀

CloudWatchを使用したログ管理のTips!!

に公開

1. 導入

Railsアプリケーションを本番環境で運用する際、AWSのCloudWatchを使用してエラーログを管理している開発チームは多いことでしょう。しかし、エラーログの出力方法によっては、CloudWatchでエラー情報が見にくくなる場合があります。特にバックトレース(スタックトレース)の出力方法は、その後のトラブルシューティングの効率を大きく左右します。

本記事では、バックトレースの基礎知識から、CloudWatchでの効果的な出力方法まで、実務で役立つ知識をご紹介します。

2. CloudWatchとは

CloudWatchの役割

CloudWatchはAWSが提供するログ管理・モニタリングサービスです。アプリケーションが出力するログを一元的に集約し、監視・分析・アラート機能を提供します。

Railsアプリケーションでの使用

Rails アプリケーションから CloudWatch に送られたログは、CloudWatch Logs というサービスで管理されます。各ログはログイベントとして記録され、タイムスタンプとログメッセージを含んでいます。

CloudWatchのログイベント区切り

重要な点として、CloudWatchは改行文字(\n)をログイベントの区切り文字として認識します。つまり、改行を含むテキストをログに送信すると、CloudWatch側では自動的に複数のログイベントに分割されてしまいます。この仕様が、バックトレース出力方法の選択に大きな影響を与えます。

3. バックトレースとは

バックトレースの定義

バックトレース(Stack Trace)とは、プログラムでエラーが発生した時点から、そのエラーに至るまでの関数呼び出しの履歴のことです。プログラムの実行順序を遡って記録したもので、「どのファイルの、どの行で、どの関数から呼ばれたのか」という情報が含まれます。

Rubyでは、エラーオブジェクトの backtrace メソッドで取得できます。

begin
  1 / 0  # ZeroDivisionError
rescue => e
  puts e.backtrace
end

バックトレースの役割

バックトレースの主な役割は以下の3つです。

1. エラーの原因特定
エラーがどのファイルの何行目で発生したかを特定できます。例えば、app/models/user.rb:42 という情報から、42行目に問題があることが即座にわかります。

2. エラー伝播の追跡
エラーが発生してから、どの関数を経由して上位の関数に伝播したかを追跡できます。複雑な関数呼び出しの中での問題箇所を特定する際に重要です。

3. デバッグ情報の提供
開発やトラブルシューティング時に、エラーの全体像を理解する際に不可欠な情報源となります。

バックトレースの仕組み

Rubyでエラーが発生すると、以下のような処理が行われます。

  1. エラーの発生 → 例外オブジェクトが生成される
  2. 呼び出しスタックの記録 → その時点での関数呼び出しの履歴を配列として記録
  3. バックトレース配列の形成 → 各行が文字列として ["file:line:in method", ...] の形式で格納される
  4. スタック巻き戻し → rescue ブロックなどで例外を処理するまで、呼び出し元へ遡っていく

実際のバックトレース配列は以下のような形をしています。

[
  "app/controllers/users_controller.rb:42:in `show'",
  "app/models/user.rb:10:in `find_user'",
  "lib/helper.rb:5:in `validate'",
  "config/routes.rb:1:in `load'",
  "app/services/service.rb:20:in `execute'"
]

バックトレースの使用ケース

ケース1:エラーハンドリングのログ記録
アプリケーションで予期しないエラーが発生した場合、デバッグのためにバックトレースをログに記録します。

begin
  user = User.find(params[:id])
rescue => e
  Rails.logger.error("User not found: #{e.message}")
  Rails.logger.error(e.backtrace.join("\n"))
end

ケース2:エラーモニタリング・通知
本番環境ではエラー検知サービス(Sentry、Honeybadgerなど)にバックトレース情報を送信し、リアルタイムに監視・通知します。

ケース3:トラブルシューティング
CloudWatchなどのログ管理サービスでエラーを調査する際に、バックトレース情報を参照してエラーの原因を追跡します。

4. バックトレース出力の2つの方法

Railsでエラーのバックトレースをログに記録する際、よく以下の2つの方法が使われます。

方法1:改行で結合

begin
  process_payment
rescue => e
  Rails.logger.error("Payment processing failed: #{e.message}")
  Rails.logger.error(e.backtrace.first(5).join("\n"))
end

この方法では、バックトレースの最初の5行を改行(\n)で結合します。

方法2:パイプで結合

begin
  process_payment
rescue => e
  Rails.logger.error("Payment processing failed: #{e.message}")
  Rails.logger.error(e.backtrace.first(5).join(" | "))
end

この方法では、バックトレース要素をパイプ(|)で結合します。

一見するとどちらも同じ情報を記録しているように見えますが、CloudWatchでの表示方法に大きな違いが生じます。

5. CloudWatchでの表示の違い

改行で結合した場合の表示

バックトレース配列がこのような内容だとします。

e.backtrace = [
  "app/controllers/users_controller.rb:42:in `show'",
  "app/models/user.rb:10:in `find_user'",
  "lib/helper.rb:5:in `validate'",
  "config/routes.rb:1:in `load'",
  "app/services/service.rb:20:in `execute'"
]

# .join("\n") を使用
e.backtrace.join("\n")

CloudWatchには以下のように複数の独立したログ行として記録されます。

app/controllers/users_controller.rb:42:in `show'
app/models/user.rb:10:in `find_user'
lib/helper.rb:5:in `validate'
config/routes.rb:1:in `load'
app/services/service.rb:20:in `execute'

パイプで結合した場合の表示

同じバックトレース配列に対して、パイプで結合します。

# .join(" | ") を使用
e.backtrace.join(" | ")

CloudWatchには1つの統一されたログ行として記録されます。

app/controllers/users_controller.rb:42:in `show' | app/models/user.rb:10:in `find_user' | lib/helper.rb:5:in `validate' | config/routes.rb:1:in `load' | app/services/service.rb:20:in `execute'

改行が問題になる理由

CloudWatchが改行を区切り文字として認識することにより、以下の4つの問題が発生します。

1. ログが分散する
一つのエラーイベントが複数のログ行に分かれてしまい、スクロールして関連する行を探す必要があります。エラーハンドリングのログ記録ケースでは、バックトレース全体を追うのに手間がかかります。

2. タイムスタンプが異なる
各ログ行に個別のタイムスタンプが付与されるため、バックトレースの各行の時系列関係が不明確になります。エラー発生の正確な時刻特定が難しくなります。

3. フィルタリング・検索が困難
バックトレース全体を一つの単位として検索できず、部分的な検索しかできないため、関連するエラーを抽出しにくくなります。特にトラブルシューティング時に、特定の関数を含むエラーを一度に抽出したい場合に支障が出ます。

4. 視覚的に情報が散らばる
ログストリーム上でエラー情報が視覚的に分散してしまい、全体像を把握しにくくなります。ログダッシュボードで複数のエラーを追跡する際に混乱を招きます。

6. 実装例:実務での活用

基本的なエラーハンドリング

class UsersController < ApplicationController
  def show
    begin
      user = User.find(params[:id])
    rescue => e
      Rails.logger.error("User not found: #{e.message}")
      Rails.logger.error(e.backtrace.join(" | "))
      render json: { error: "User not found" }, status: :not_found
    end
  end
end

構造化ログでの出力例

CloudWatch Insights などで分析しやすいように、JSON形式で構造化ログを出力することもあります。

class PaymentService
  def self.process(user, amount)
    begin
      # 決済処理
      charge(user, amount)
    rescue => e
      error_log = {
        timestamp: Time.current.iso8601,
        error_type: e.class.name,
        error_message: e.message,
        backtrace: e.backtrace.first(10).join(" | "),
        user_id: user.id,
        amount: amount,
        request_id: RequestStore.store[:request_id]
      }
      Rails.logger.error(error_log.to_json)
      raise
    end
  end

  private

  def self.charge(user, amount)
    # 決済API呼び出しなど
  end
end

チーム内でのルール化提案

プロジェクト全体で統一するため、ロギングヘルパーメソッドを作成することも効果的です。

# app/lib/error_logger.rb
class ErrorLogger
  def self.log_error(exception, context = {})
    log_entry = {
      timestamp: Time.current.iso8601,
      error_type: exception.class.name,
      error_message: exception.message,
      backtrace: exception.backtrace.join(" | "),
      context: context
    }
    Rails.logger.error(log_entry.to_json)
  end
end

# 使用例
begin
  user.update!(email: params[:email])
rescue => e
  ErrorLogger.log_error(e, { user_id: user.id, action: "update_email" })
end

7. 推奨される実装方法

パイプ区切りを推奨する理由

CloudWatchでのログ管理を考慮するなら、バックトレースの結合にはパイプ区切り(|)を推奨します。

Rails.logger.error(e.backtrace.join(" | "))

パイプで結合することで、以下のメリットが得られます。

  • バックトレース全体が1行で完結 → 一目で全体を把握できる
  • 単一のタイムスタンプ → エラーの発生時刻が明確で、ログの時系列管理が容易
  • 効率的な検索 → バックトレース全体を一度に検索・フィルタリング可能
  • 可読性の向上 → ログストリーム上で関連情報がまとまって表示される
  • エラーモニタリングとの相性 → Sentryなどのエラー検知サービスで関連エラーをグループ化しやすい

チーム内ルール化のポイント

  1. エラーメッセージとバックトレースは別々のログ行に出力する

    Rails.logger.error("Error occurred: #{e.message}")
    Rails.logger.error(e.backtrace.join(" | "))
    
  2. バックトレースの要素結合には常にパイプ区切りを使用する

    • 改行は絶対に使わない
  3. CloudWatchでの検索性を考慮してロギング構造を設計する

    • 必要に応じて JSON 形式で構造化ログを使用
    • request_id などの追跡可能な識別子を含める

8. まとめ

バックトレースはエラーの原因特定やトラブルシューティングに欠かせない情報です。CloudWatchを使用している環境では、ログの形式がCloudWatch側でどのように解釈されるかを意識することが重要です。

CloudWatchが改行をログイベントの区切り文字として認識するという仕様を理解することで、適切なバックトレース出力方法の選択ができます。バックトレースのような多行情報でも、改行ではなく別の区切り文字(パイプなど)を使用することで、運用の効率性と可読性が大きく向上します。

特にエラーモニタリングと通知の精度が重要な本番環境では、適切なバックトレース出力方法の選択がトラブルシューティングのスピードを大きく左右します。チーム内でのログ出力ルールを統一し、CloudWatchの仕様を考慮した実装を心掛けることが、堅牢な運用体制の構築につながるでしょう。

Discussion