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