AWSサポートケースを書く際に気をつけたいポイント

AWSサービスを使用している際、予期せぬエラーや障害、不可解な挙動が合った場合等サポートケースを使用してテクニカルサポートの方に聞くことができます。これまで実際に自分がサポートケースを書いた経験や、同僚が書いたサポートケースのレビューを行った経験から、サポートケースを書く際に気をつけたいポイントを紹介します。

AWSサポートとは？

AWSサポートとは、Amazon Web Services (AWS) の利用者に対して、テクニカルサポートや運用助言、問題解決のための支援を提供するサービスです。運用中の障害発生時や開発中のトラブル、サービスの使い方の相談など、AWS使用・運用中の開発者は必ずお世話になるものです。

チェックポイント

大前提として、AWS公式から提供されている資料を参考にすることをおすすめします。こちらの資料にかかれている下記の大項目と付随する小項目の確認事項を事前に確認し、頭に入れておきましょう。

全般的な留意事項
解決したい課題を明確にする
状況を正確に共有する
経緯を共有する

aws.amazon.com

①正確な語句で書けているか？

ちょっとした語句でも使い方を誤ると、主語が変になってしまったり、文脈が意図せず変化したりと思わぬ影響を及ぼします。細部までもう一度文を見直しましょう。書き終えた文章を声に出して朗読してみることもオススメします。読むのに詰まってしまったり、読み間違えたりする箇所は怪しいです。

下記は、EC2を人が手動で起動させたのか、EC2が手動ではなにかのイベントで自動起動されたのか紛らわしくなっています。

EC2が起動しましたが

EC2を起動しましたが

②簡潔で読みやすい文章になっているか？

1文が長いと、文章にリズムが生まれず、読みながら文章の意味を読み解きずらくなります。文章を書いた後に、重複表現や不要な点がないか、見直してみましょう。 AWSリソースの情報を盛り込みたい場合は、本文の前段で先にリソース情報を定義し、本文と分離すると良いと思います。

S3 bucketに複数のファイルをアップロードして、そのイベントをトリガーにLambda関数（lambda-functions-name-hogehogefugafuga）を実行させます。Lambda関数（lambda-functions-name-hogehogefugafuga）の中でStep Functions（stepFunctions-name-hogehogefugafuga）を起動し、StepFunctionsのワークフローからGlue job（glue-job-name-hogehogefugafuga）を実行し、

対象リソース呼称
- S3 bucket (bucket-name-hogehoge)
- Lambda関数（lambda-functions-name-hogehogefugafuga）
- Step Functions（stepFunctions-name-hogehogefugafuga）
- Glue job（glue-job-name-hogehogefugafuga）

S3 bucketに複数のファイルをアップロードして、そのイベントをトリガーにLambda関数を実行させます。Lambda関数の中でStep Functionsを起動し、Step FunctionsのワークフローからGlue jobを実行し、

③実行ID・実行Arnが記載されているか？

経験上、AWSのサポートエンジニアの方から対象リソースArnやイベントの実行IDの提出を毎回求められます。事前に実行ID・実行Arnを共有しておくことで、やりとりする回数の削減につながります。

対象リソース呼称
- S3 bucket (bucket-name-hogehoge)
- Lambda関数（lambda-functions-name-hogehogefugafuga）
- Step Functions（stepFunctions-name-hogehogefugafuga）
- Glue job（glue-job-name-hogehogefugafuga）

S3 bucketに複数のファイルをアップロードして、そのイベントをトリガーにLambda関数を実行させます。Lambda関数の中でStep Functionsを起動し、Step FunctionsのワークフローからGlue jobを実行し、

対象リソース呼称
- S3 bucket (bucket-name-hogehoge Arn: arn:aws:s3:::aaaaaaaaaaaaaaaaaaaaaaa_bbbbbbbbbbbbbbb)
- Lambda関数（lambda-functions-name-hogehogefugafuga Arn: aaaaaaaaaaaaaa-dddddddddddd-ccccccccccccc）
- Step Functions（stepFunctions-name-hogehogefugafuga 実行Arn: aaaaaaaaaaaaaa-dddddddddddd-ccccccccccccc）
- Glue job（glue-job-name-hogehogefugafuga Job runs id: aa_bbbbbbbbbbbbbbbbbbbbbbb_ccccccccccccccccc）

S3 bucketに複数のファイルをアップロードして、そのイベントをトリガーにLambda関数を実行させます。Lambda関数の中でStep Functionsを起動し、Step FunctionsのワークフローからGlue jobを実行し、

④現象（事実）検証・仮説を分けて書けているか？

発生している現象・検証・仮説を一気に本文でまとめてしまうと、それぞれが本当に伝えたい事柄だったとしてもそれが発生している事実なのか・仮説なのか、検証結果なのかの解読が困難になります。適切に文を区切り、それぞれの内容を分けて記載しましょう。また、この分解作業は自分自身の頭の整理にもなります。眼の前にある情報を俯瞰して見て分類することで、新たな観点や、ヌケモレなどに気づく可能性も増えます。

先日からEC2インスタンスがうまく動作しなくなりました。何回か再起動してみたけれど、まだうまくいかないです。Webアプリケーションがとても遅いですし、たまにエラーも出て困っています。ここ最近AWSのシステムに変更はありましたか？コンソールの設定値で怪しいところが無いかの確認や、インスタンスのメモリのモニタリングをしてみました。それによって影響を受けているのかもしれません。もし何か原因や解決策がわかったらすぐ教えてください。

私たちのEC2インスタンスでパフォーマンス低下とXXXエラーの発生が確認されており、解決策を教えていただきたくお問い合わせをさせて頂きます。
【現象（事実）】
• 発生日時：2022年1月1日 9:00（JST）頃から
• サービス・リソース：EC2インスタンス（インスタンスID：i-xxxxxxx）
• エラーメッセージ：XXXエラーコードが表示される
• 影響範囲：Webアプリケーションのレスポンスタイムが通常の5倍以上に低下
【検証】
以下の手順を行いましたが、問題は解決しておりません。
1. EC2インスタンスの再起動
2. AWSドキュメントに記載されているXXXエラーのトラブルシューティング手順の実施
【仮説】
AWSのシステム変更やアップデートが影響を与えた可能性が考えられます。そちらの状況に変更があった場合、教えていただけますでしょうか。また、その他可能性のある原因と解決策をご教示いただければ幸いです。

⑤（返信があった場合の回答編）質問に対して答えを適切に返せているか？

聞かれている質問に対し、過不足なく答えましょう。質問に対する回答を正確にすることで、回答に対するその後のやりとりがしやすくなります。もし、付随して情報を共有したい場合、追加情報エリアを作って、別途記載しましょう。

質問内容
Q. Lambdaの実行時間と実行後のエラーメッセージを共有してください
回答
A. 実行時間1sでエラーメッセージは `Error()`です。ランタイムはNode.js 16.xで先日バージョンアップしました。こちらのバージョンアップが悪さしているでしょうか？また、実行ログも見ましたが、原因がわかりません。

質問内容
Q. Lambdaの実行時間と実行後のエラーメッセージを共有してください
回答
A. 実行時間1sでエラーメッセージは `Error()`です。

⑥相手に対し、敬意を払った文体になっているか？

基本的なことですが、今まであげたものの中で一番大切です。もちろん、サポートケースを書いているということはなにかに悩み・困っている状況であり、時にはイライラすることもあるでしょう。しかし、そのイライラを文章に込めて、投げやりに書いてしまうのは厳禁です。サポートしてくれる方がいることに感謝し、丁寧な言葉づかいを心がけたいです。もし自分がAWS側のサポートエンジニアとして、この文章を受け取ったらどんな印象を抱くか、一度想像して見直してみましょう。

終わりに

AWSサポートケースを書く際に気をつけたいポイントとして、6点のポイントを上げました。どなたかの参考になれば幸いです。

また、問題を解決するためには、AWSの知識だけではなく、「文章を書く力・伝える力・相手を思いやる力」がとても大切だと本記事を書いていて思い直しました。