Google Cloud Apigee サポートケースに関するベスト プラクティス

Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントに移動。 情報

Apigee X のドキュメントが表示されています。
Apigee Edge のドキュメントを表示する。

サポートケースに必須情報を詳細を記載していただければ、Google Cloud Apigee サポートチームが迅速かつ効率的に対応できるようになります。サポートケースに重要な詳細が欠落していると、追加の情報をリクエストする必要性が生じます。こうなると、複数回のやり取りが発生する可能性があります。このやり取りは時間を要するため、問題解決が遅れてしまう可能性があります。このベスト プラクティス ガイドでは、テクニカル サポートケースを迅速に解決するために必要な情報について説明します。

問題の説明

問題には、何が発生したか（および何が発生すると想定されていたか）、いつ、どのように発生したかに関する詳細を説明する情報を含める必要があります。適切な Apigee サポートケースには、Apigee の各プロダクトに関する以下の主要な情報が記載される必要があります。

鍵情報 説明 Apigee Edge for Public Cloud Apigee Edge for Private Cloud
プロダクト 問題が発生している具体的な Apigee プロダクト（可能な場合はバージョン情報も記載）
  • バージョン
問題の詳細 問題を概説する明確で詳細な説明（ある場合はエラーメッセージの全文も記載）。
  • エラー メッセージ
  • Trace ツールの出力
  • 問題を再現する手順
  • 完全な API リクエスト / コマンド
  • エラー メッセージ
  • Trace ツールの出力
  • 問題を再現する手順
  • 完全な API リクエスト / コマンド
  • コンポーネント診断ログ
時間 問題が発生した具体的なタイムスタンプと問題の持続時間
  • 問題が発生した日時とタイムゾーン
  • 問題が発生した期間
  • 問題が発生した日時とタイムゾーン
  • 問題が発生した期間
設定 問題の発生場所に関する詳細情報
  • 組織名
  • 環境名
  • API プロキシの名前
  • リビジョン
  • ネットワーク トポロジ
  • 失敗した Edge コンポーネント

次のセクションで、これらのコンセプトについて詳しく説明します。

プロダクト

さまざまな Apigee プロダクト（Apigee Edge on Public Cloud と Apigee Edge on Private Cloud）があるため、どのプロダクトで問題が発生しているかに関する具体的な情報が必要です。

次の表はいくつかの例を示しています。DOs 列は完全な情報を、DON'Ts 列は不完全な情報を示しています。

DOs DON'Ts
Public Cloud 組織で API プロキシ OAuth2 をデプロイできませんでした...

API プロキシをデプロイできませんでした

（問題が発生している Apigee プロダクトをお知らせください。）
Edge Private Cloud バージョン 4.50.00 で次のエラーが発生し、インストールが失敗しました...

Private Cloud のセットアップでインストールに失敗しました。

（バージョン情報が欠落しています）

問題の詳細

エラー メッセージ（ある場合）、想定されていた挙動、実際に確認された挙動など、確認される問題に関する情報を正確に提供します。

次の表はいくつかの例を示しています。DOs 列は完全な情報を、DON'Ts 列は不完全な情報を示しています。

DOs DON'Ts

新しい edgemicro プロキシ edgemicro_auth が次のエラーで失敗します。

{"error":"missing_authorization","error_description":"Missing Authorization header"}

今日作成された新しい edgemicro プロキシが機能しません

（プロキシ名が不明です。また、プロキシがエラーを返しているか、予期しないレスポンスを返しているか不明瞭です。）

クライアントが、API プロキシへのリクエスト中に次のエラー メッセージで 500 エラーを受け取ります。

{"fault":{"faultstring":"Execution of JSReadResponse failed with error: Javascript runtime error: \"TypeError: Cannot read property \"content\" from undefined. (JSReadResponse.js:23)","detail":{"errorcode":"steps.javascript.ScriptExecutionFailed"}}}

クライアントが、API プロキシへのリクエスト中に 500 エラーを受け取ります。

（500 エラーを伝えるだけでは、問題を調査するために必要な情報として不十分です。実際に確認されるエラー メッセージとエラーコードを伝える必要があります。）

時間

時間は非常に重要な情報です。この問題に最初に気付いたのはいつか、問題がどの程度継続したか、まだ問題が継続中かをサポート エンジニアに知らせることが重要です。

問題を解決するサポート エンジニアがお客様と同じタイムゾーンにいない場合もあります。そのため、時間を相対的に説明してしまうと、問題の診断が難しくなります。そのため、ISO 8601 形式で日時を指定し、問題がいつ発生したかに関する情報を正確に伝えることをおすすめします。

次の表で例をいくつか示します。DOs 列は問題が発生した正確な時刻と期間を、DON'Ts 列には問題が発生した時間に関するあいまいで不正確な情報を示しています。

DOs DON'Ts
昨日の 2020-11-06 17:30 PDT から 2020-11-06 17:35 PDT の間に、多数の 503s が確認されました。

昨日午後 5 時 30 分に多数の 503s が 5 分間確認されました。

（暗示的に指定されたこの日付形式を使用せざるを得なくなります。また、この問題が確認された時刻のタイムゾーンが不明瞭です。）
2020-11-09 15:30 IST から 2020-11-09 18:10 IST までの間に、以下の API プロキシで高いレイテンシが確認されました。

先週、一部の API プロキシで高いレイテンシが確認されました。

（この問題が先週のどの日付で確認されたか、どの程度持続したかが不明瞭です。）

設定

問題が発生している場所に関する詳細をお知らせください。使用しているプロダクトに応じて、次の情報が必要です。

  • Apigee Cloud を使用している場合は、複数の組織が存在する可能性があるため、問題が発生している組織やその他の詳細を具体的に把握する必要があります。
    • 組織名と環境名
    • API プロキシ名とリビジョン番号（API リクエストの失敗の場合）
  • Private Cloud を使用している場合、サポートされている数多くのインストール トポロジのうちのいずれかを使用している可能性があります。そのため、データセンターとノードの数など、使用しているトポロジについて説明する必要があります。

次の表はいくつかの例を示しています。DOs 列は完全な情報を、DON'Ts 列は不完全な情報を示しています。

DOs DON'Ts

2020-11-06 09:30 CST 以降、Edge Public Cloud での 401 エラーの数が増えています。

Edge の設定に関する詳細:

失敗した API の詳細は以下のとおりです。
  組織名: myorg
  環境名: test
  API プロキシ名: myproxy
  リビジョン番号: 3

エラー:

{"fault":{"faultstring":"Failed to resolve API Key variable request.header.X-APP-API_KEY","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

401 エラーの数が増えています。

（使用されているプロダクト、問題がいつから確認されるか、設定の詳細に関する情報が何もありません。）

ゲートウェイ ノードの追加後、Edge Private Cloud バージョン 4.19.06 で Message Processor を起動できません。

診断ログ:
Message Processor のログを添付しました。

ネットワーク トポロジ:
追加のノードを含むファイル network-topology.png を添付しました。

ゲートウェイ ノードの追加後、Edge Private Cloud バージョン 4.19.06 で Message Processor を起動できません。

（Message Processor のログとネットワーク トポロジがありません。）

有用な資料

問題に関連するアーティファクトを提供していただければ、確認される挙動をより正確に把握して、分析情報をより多く引き出せるため、問題の解決をスピードアップできます。

このセクションでは、すべての Apigee プロダクトの場合で役立つ有用なアーティファクトについて説明します。

すべての Apigee プロダクトに共通のアーティファクト

次のアーティファクトは、すべての Apigee プロダクト（Apigee Edge on Public Cloud と Apigee Edge on Private Cloud）で有用です。

アーティファクト 説明
Trace ツールの出力 Trace ツールの出力には、Apigee プロダクトを通過する API リクエストに関する詳細情報が含まれます。これは、4XX、5XX、レイテンシの問題などのランタイム エラーに対して有用です。
スクリーンショット スクリーンショットは、確認される実際の挙動やエラーのコンテキストを伝達するために活用できます。UI やアナリティクスなどで確認されるエラーや問題に対して有用です。
HAR（Http ARchive） HAR は、UI 関連の問題をデバッグするために HTTP セッション ツールによってキャプチャされるファイルです。Chrome、Firefox、Internet Explorer などのブラウザを使用してキャプチャできます。
tcpdumps tcpdump ツールは、ネットワーク経由で送受信された TCP/IP パケットをキャプチャします。これは、TLS handshake エラー、502 エラー、レイテンシの問題など、ネットワーク関連のあらゆる問題に対して有用です。

Apigee Edge for Private Cloud の追加アーティファクト

Apigee Edge for Private Cloud では、問題の診断を迅速に行うために、追加のアーティファクトが必要になる場合があります。

アーティファクト 説明
ネットワーク トポロジ すべてのデータセンター、ノード、各ノードにインストールされているコンポーネントを含む、Private Cloud のセットアップを説明する Edge インストール トポロジ図。
Edge のコンポーネント診断ログ Message Processor、Router、Cassandra など、特定の Apigee Edge コンポーネントに関連する診断ログ。
インストール構成ファイル Apigee Edge のインストールやアップグレード時に使用するサイレント構成ファイル。

このファイルは、インストールや移行の問題が発生したときに、すべての設定が正しいことを検証する際に有用です。
ヒープダンプ ヒープダンプは、Java メモリプロセスのスナップショットです。これは、特定の Edge コンポーネントで高いメモリ使用率や OutOfMemory エラーが発生した場合に有用です。
スレッドダンプ スレッドダンプは、実行中の Java プロセスのすべてのスレッドのスナップショットです。

これは、特定の Edge コンポーネントで高い CPU 使用率や高負荷が発生した場合に有用です。

ケース テンプレートとサンプルケース

このセクションでは、このドキュメントで説明されるベスト プラクティスに基づいた、さまざまなプロダクトのケース テンプレートとサンプルケースを示します。

Apigee Edge on Public Cloud

テンプレート

このセクションでは、Apigee Edge on Public Cloud のサンプル テンプレートを示します。

問題:

<問題の詳細な説明や、お客様側で確認される挙動の説明を記載します。可能な場合は、プロダクト名とバージョンを記載します。>

エラー メッセージ:

<表示されたエラー メッセージ全体を記載します（ある場合）>

問題の開始時刻（ISO 8601 形式）

問題の終了時刻（ISO 8601 形式）

Apigee の設定の詳細:
  組織名:
  環境名:
  API プロキシ名:
  リビジョン番号:

再現するための手順:

<問題を再現するための手順を記載します（可能な場合）>

診断情報:

<添付ファイルの一覧>

サンプルケース

このセクションでは、Apigee Cloud（Apigee on Google Cloud / Apigee Edge on Public Cloud）のサンプルケースを示します。

問題:

Public Cloud 組織で 503 サービス利用不可エラーが多数発生しています。問題を確認して解決いただくか、その解決方法を教えていただけますでしょうか。

エラー メッセージ:

{"fault":{"faultstring":"The Service is temporarily available", "detail":{"errorcode":"messaging.adaptors.http.flow.ServiceUnavailable"}}}

問題の開始時刻（ISO 8601 形式）: 2020-10-04 06:30 IST

問題の終了時刻（ISO 8601 形式）: 引き続き発生中。

Apigee Cloud の設定の詳細:
  組織名: myorg
  環境名: dev
  API プロキシ名: myproxy
  リビジョン番号: 3

再現するための手順:

次の curl コマンドを実行すると問題を再現できます。

curl -X GET 'https://myorg-dev.apigee.net/v1/myproxy'

診断情報:

Trace ツールの出力（trace-503.xml）

Apigee Edge for Private Cloud

テンプレート

このセクションでは、Apigee Edge for Private Cloud のサンプル テンプレートを示します。

問題:

<問題の詳細な説明や、お客様側で確認される挙動の説明を記載します。可能な場合は、プロダクト名とバージョンを記載します。>

エラー メッセージ:

<表示されたエラー メッセージ全体を記載します（ある場合）>

問題の開始時刻（ISO 8601 形式）

問題の終了時刻（ISO 8601 形式）

Edge Private Cloud の設定の詳細:

<データセンターやノードなど、Private Cloud のセットアップを説明するネットワーク トポロジを添付します>

再現するための手順:

<問題を再現するための手順を記載します（可能な場合）>

診断情報

<添付ファイルの一覧>

サンプルケース

このセクションでは、Apigee Edge for Private Cloud のサンプルケースを示します。

問題:

Linux RHEL 7.6 の Edge Private Cloud 4.19.06 の一部としてノード #10 に Apigee Management Server をインストールしているときに、以下のエラーが発生します。

エラー メッセージ:

<snipped as the output is too long>
Checking for management-server uuid ................................................
Unable to get uuid for management-server.
Error: setup.sh: /opt/apigee/apigee-service/bin/apigee-service exited with unexpected status 1

問題の開始時刻（ISO 8601 形式）: インストールするたびに発生

問題の終了時刻（ISO 8601 形式）: 該当なし

Edge Private Cloud の設定の詳細:

ファイル network-topology.png を添付しました

再現するための手順:

以下は、上記のエラーが発生したコマンドです。

/opt/apigee/apigee-setup/bin/setup.sh -p ms -f /app/NonProdConfig.txt

診断情報:

以下のファイルを添付しました。

  • エラー メッセージを含め、上記コマンドの完全な出力が記載された output.txt
  • 管理サーバーのログ
  • 構成ファイル NonProdConfig.txt