AWS Transfer Family のログ記録ロール方式から構造化された JSON ログ記録に切り替えてみた

はじめに

AWS Transfer Family のログ記録方式を、従来のログ記録ロール方式から構造化された JSON ログ記録に切り替えを試しました。切り替え手順と、注意事項、切り替え前後のログの違いを紹介します。

検証結果

既存設定からの切り替えはマネジメントコンソールから数クリックで完了します。

• ログが JSON 形式になり、CloudWatch Logs Insights でのクエリやフィルタが容易になる
• Vended Logs 方式により CreateLogStream のスロットリング問題が解消される

ただし、切り替え時には注意点があります。

構造化された JSON ログ記録とは

AWS Transfer Family には 2 つのログ記録方式があります。

ログ記録ロール方式（Legacy）は、Transfer Family が IAM ロールを使って CloudWatch Logs API を直接呼び出す方式です。ログはプレーンテキストで記録されます。セッションごとに CreateLogStream を呼び出すため、同時接続数が多い環境ではスロットリングのリスクがあります。

構造化された JSON ログ記録（Structured）は、AWS が現在推奨するログ方式です。CloudWatch Logs の Vended Logs 機能でログを配信します。CreateLogStream の呼び出しが不要になり、ログは JSON 形式で記録されます。新規サーバーをコンソールで作成する場合はデフォルトで有効です。

https://dev.classmethod.jp/articles/transfer-family-structured-json/

前提条件

• AWS アカウントと Transfer Family サーバーが作成済みであること
• 設定変更を行う IAM ユーザーまたはロールに後述の権限が付与されていること

構造化された JSON ログ記録を有効にするには、設定変更する IAM ユーザーまたはロールに以下の権限が必要です。ログ記録ロールとは異なり、サーバーに紐づけるロールではなく設定操作を行う側に付与します。 Admin 権限で作業する方は気にする必要はありません。

• logs:CreateLogDelivery
• logs:DeleteLogDelivery
• logs:DescribeLogGroups
• logs:DescribeResourcePolicies
• logs:GetLogDelivery
• logs:ListLogDeliveries
• logs:PutResourcePolicy
• logs:UpdateLogDelivery

詳細は Amazon CloudWatch logging for AWS Transfer Family servers を参照してください。

検証環境

パブリックエンドポイントの SFTP サーバーを ap-northeast-1（東京）リージョンに作成済みです。認証方式は Service Managed で、SSH 公開鍵によるユーザー認証を使用しています。ログ記録は ログ記録ロール方式（Legacy）で設定されている状態から切り替えを行います。

やってみた

CloudWatch Logs ロググループの作成

構造化された JSON ログ記録では、ログの出力先ロググループを事前に作成する必要があります。Legacy 方式では /aws/transfer/{server_id} が自動作成されましたが、Structured 方式では自動作成されません。

CloudWatch コンソールからロググループを作成します。名前は任意ですが、用途がわかる名前にしておくとよいでしょう。今回は sftp-logging-test-structured-logs としました。保持期間は要件に応じて設定してください。

Transfer Family コンソールでログ記録方式を切り替え

以下の手順でログ記録方式を切り替えます。

1. Transfer Family コンソールを開く
2. 左ナビゲーションの「サーバー」を選択し、対象サーバーの Server ID をクリック
3. 「その他の詳細」セクションの右上にある「編集」をクリック

4. 「ログ記録」パネルで「構造化された JSON ログ記録」を選択
5. 「ロググループ」ドロップダウンから先ほど作成した sftp-logging-test-structured-logs を選択

6. ページ下部の「保存」をクリック

保存後に再度設定を確認したら、ログ記録ロールは削除されグレーアウトしました。

コンソールから構造化された JSON ログ記録を有効にすると、既存のログ記録ロール方式は自動的に無効化されました。これは二重課金を防ぐための仕様です。

Enabling structured JSON logging through the console disables the existing logging method, so as to not double charge customers. The exception is if a workflow is attached to the server.

— Creating, updating, and viewing logging for servers - AWS Transfer Family

動作確認

設定変更後、SFTP でファイルをアップロードしてログの記録を確認します。

# テスト用ファイルを作成
echo "test" > test-upload-structured.txt

# SFTP で接続（SSH 秘密鍵を指定）
sftp -i ~/.ssh/<秘密鍵ファイル名> testuser@<サーバーエンドポイント>
sftp> put test-upload-structured.txt
sftp> exit

CloudWatch コンソールの「ロググループ」から sftp-logging-test-structured-logs を開き、ログストリームが作成されていることを確認します。

ログストリーム名は {server_id}/{user_name} 形式で確認できました。Legacy 方式の {user_name}.{session_id} 形式とは異なります。

ログストリームを開くと、"activity-type": "CONNECTED" を含む JSON 形式のログエントリが記録されています。

切り替え時の注意事項

ログドロップの可能性あり

公式ドキュメントに以下の記載があります。

切り替え直後、まれに最大 1 時間程度ログのドロップが発生し得ます。 シビアな環境ではメンテナンスウィンドウでの切り替えを推奨します。

When you opt into structured JSON logging, there can be a delay, in rare cases (...).
you should be careful transferring files during the first hour after changing your logging method, as logs could be dropped.

— Creating, updating, and viewing logging for servers - AWS Transfer Family

コンソールからの構造化された JSON ログ記録の無効化は不可

構造化された JSON ログ記録を有効にした後、コンソールから無効化する手段はありません。API または SDK であれば UpdateServer で構造化ログの無効化と ログ記録ロールの再設定が可能です。

詳細は Creating, updating, and viewing logging for servers を参照してください。

マネージドワークフロー、コネクタとの併用

マネージドワークフローとコネクタのログは構造化された JSON ログ記録に対応していません。これらを使用している場合、ログは引き続きログ記録ロール経由で記録されます。

• ワークフロー付きサーバーで構造化ログを有効にしても、ログ記録ロールは自動的に残る

Enabling structured JSON logging through the console disables the existing logging method (...). The exception is if a workflow is attached to the server.

— Creating, updating, and viewing logging for servers - AWS Transfer Family

ログ解析スクリプトの改修

ログ形式がプレーンテキストから JSON に変わるため、既存のログ解析スクリプトや CloudWatch Logs のメトリクスフィルタ、アラーム設定の改修が必要です。切り替え前に影響範囲を洗い出してください。

切り替え前後のログ比較

実際に同じ操作（SFTP でのファイルアップロード）を行い、Legacy と Structured のログを比較しました。

ログ出力先と形式

フィールド比較

構造化された JSON 形式になったことで、各フィールドを独立したキーとしてクエリやフィルタできるようになりました。

https://dev.classmethod.jp/articles/202307-transfer-family-log-insights-01/

ログの実例

Legacy 方式の接続時ログは、以下のようにプレーンテキストで記録されます。

testuser.02855649a7329629ec00 CONNECTED SourceIP=203.0.113.1 User=testuser HomeDir=/sftp-logging-test-20260317025327385700000001 Client=SSH-2.0-OpenSSH_10.2 Role=arn:aws:iam::123456789012:role/sftp-logging-test-sftp-user Kex=ecdh-sha2-nistp256 Ciphers=aes128-gcm@openssh.com,aes128-gcm@openssh.com MACs=<implicit>,<implicit> SshPublicKeyFingerprint=SHA256:CiZHKgYO4H3qBNu5FLA5LGC5oK1+hQ4kOT5I1nfuv2I SshPublicKeyType=ssh-ed25519 SshPublicKey=AAAAC3NzaC1lZDI1NTE5AAAAIEKtl5fg8bbzwC01Ctfwr0FfAoDvYLNtM8O4Qbuxw/qs

Structured 方式では、同じ操作が JSON で記録されます。

{
  "role": "arn:aws:iam::123456789012:role/sftp-logging-test-sftp-user",
  "activity-type": "CONNECTED",
  "ssh-public-key-fingerprint": "SHA256:CiZHKgYO4H3qBNu5FLA5LGC5oK1+hQ4kOT5I1nfuv2I",
  "home-dir": "/sftp-logging-test-20260317025327385700000001",
  "ssh-public-key": "AAAAC3NzaC1lZDI1NTE5AAAAIEKtl5fg8bbzwC01Ctfwr0FfAoDvYLNtM8O4Qbuxw/qs",
  "ssh-public-key-type": "ssh-ed25519",
  "macs": "<implicit>,<implicit>",
  "ciphers": "aes128-gcm@openssh.com,aes128-gcm@openssh.com",
  "client": "SSH-2.0-OpenSSH_10.2",
  "source-ip": "203.0.113.1",
  "resource-arn": "arn:aws:transfer:ap-northeast-1:123456789012:server/s-1234567890abcdef0",
  "user": "testuser",
  "kex": "ecdh-sha2-nistp256",
  "session-id": "03646995f446c0a7fdb6"
}

ログ配信方式

まとめ

AWS Transfer Family のログ記録をログ記録ロール方式から構造化された JSON ログ記録に切り替えました。切り替え作業はコンソールから数クリックで完了します。

切り替えにより、ログが JSON 形式になりクエリしやすくなるだけでなく、Vended Logs 方式で CreateLogStream のスロットリング問題も解消されます。大量同時接続のある環境では積極的に切り替えを検討してください。

切り替え時は以下の点に注意が必要です。

• 切り替え直後、まれに最大 1 時間のログドロップの可能性があるためメンテナンスウィンドウでの作業を推奨
• コンソールからは無効化できないため、切り戻しには API/SDK が必要
• ワークフロー/コネクタのログは引き続きログ記録ロール方式が必要
• ログ形式変更に伴う解析スクリプトや監視設定の改修を事前に計画する

おわりに

ドキュメントを読んでもわかりにくかった部分があったので手を動かしてみました。設定切り替えへの参考になれば幸いです。

参考

• Amazon CloudWatch logging for AWS Transfer Family servers
• Creating, updating, and viewing logging for servers - AWS Transfer Family
• Configure CloudWatch logging role - AWS Transfer Family
• CloudWatch Logs vended logs - Amazon CloudWatch Logs