📋

ALB アクセスログではカスタムヘッダーを記録できない

に公開

はじめに

フロントエンドのバージョンを追跡したいと思い、カスタムヘッダー(例: X-Build-Date)をリクエストに含めてアクセスログで分析しようとしました。

ログ記録の選択肢として ALB のアクセスログが上がったのですが、ALB のアクセスログにはカスタムリクエストヘッダーは記録されませんでした。

この記事では、なぜ記録されないのか、そもそもリクエストヘッダーとは何か、そしてカスタムヘッダーをログに残すにはどうすればよいかを解説します。

HTTPヘッダーの基礎知識

リクエストヘッダーとは

リクエストヘッダーは、HTTPリクエストで使用されるヘッダーで、メッセージ本文の内容には直接関連しないメタデータを含みます。サーバーが適切なレスポンスを生成するための「文脈情報」を提供する役割を持ちます。

GET /api/users HTTP/1.1
Host: api.example.com
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...
Accept: application/json
Accept-Language: ja,en;q=0.9
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
X-Build-Date: 2026-02-04T12:00:00Z  ← カスタムヘッダー

リクエストヘッダーの分類

種類 説明 例
コンテンツネゴシエーション用 どの形式・言語で返すか交渉 Accept, Accept-Language, Accept-Encoding
条件付きリクエスト用 キャッシュ検証など If-Modified-Since, If-None-Match
コンテキスト情報提供用 クライアント情報をサーバーに伝える User-Agent, Cookie, Referer
カスタムヘッダー アプリケーション固有の情報 X-Build-Date, X-Request-ID
条件付きリクエストとは

「この条件を満たす場合だけ、リソースを返して」とサーバーに伝えるリクエストです。

例えばIf-Modified-Sinceは「この日時以降に更新されていれば返して」という条件を指定します。更新されていなければサーバーは304 Not Modifiedを返し、ボディを転送しないため帯域を節約できます。

ALBアクセスログに記録されるフィールド

ALBのアクセスログには以下のような情報が記録されます。

こちらを見ると、ヘッダー関連で記録されるのは以下の3つのみです。

フィールド 対応するヘッダー
user_agent User-Agent
trace_id X-Amzn-Trace-Id(ALBが自動付与)
domain_name SNIドメイン名(TLS接続時のホスト名)

実際のALBアクセスログの例

h2 2026-02-04T23:55:00.865365Z app/prod-example/82ba410472a1b47f
219.98.15.205:61087 10.0.101.226:8080 0.001 0.002 0.000 200 200 374 402
"GET https://api.example.com:443/api/v2/users HTTP/2.0"
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36..."
TLS_AES_128_GCM_SHA256 TLSv1.3
arn:aws:elasticloadbalancing:ap-northeast-1:123456789012:targetgroup/example/...
"Root=1-6983dc54-0025ed68519299514162b857" "api.example.com" ...

User-Agentとtrace_idは見えますが、カスタムヘッダーを記録する場所はありません。

カスタムヘッダーをログに残す方法

ALBでは記録できないため、別の方法を検討する必要があります。

方法1: バックエンドでログ出力(推奨)

最もシンプルな方法は、バックエンドのミドルウェアでカスタムヘッダーをログ出力することです。

# FastAPIの例
from fastapi import Request
import logging

@app.middleware("http")
async def log_custom_headers(request: Request, call_next):
    build_date = request.headers.get("X-Build-Date", "unknown")
    logging.info(f"X-Build-Date: {build_date}")
    return await call_next(request)

方法2: AWS WAF ログを活用

ALB に AWS WAF をアタッチしている場合、WAF ログにはリクエストヘッダーが記録されます。

WAF ログのhttpRequest.headersフィールドには、リクエストに含まれる全てのヘッダーが配列として記録されます。

{
  "httpRequest": {
    "clientIp": "203.0.113.50",
    "country": "JP",
    "headers": [
      { "name": "Host", "value": "api.example.com" },
      { "name": "User-Agent", "value": "Mozilla/5.0 ..." },
      { "name": "X-Build-Date", "value": "2026-02-04T12:00:00Z" }
    ],
    "uri": "/api/users",
    "httpMethod": "GET"
  }
}

まとめ

ALB のアクセスログは固定フォーマットであり、カスタムヘッダーを記録できません。カスタムヘッダーを使った分析を行いたい場合は、バックエンドでのログ出力が最もシンプルです。すでに WAF を導入している場合は、WAF ログの活用も選択肢になります。

Discussion