Download PDF
Download page Go SDK の使用.
Go SDK の使用
Go SDKを使用してアプリケーションのインストゥルメント化を開始する前に、Go SDKの最新バージョンを入手する必要があります。「Go 言語エージェント」と「AppDynamicsソフトウェアのダウンロード」トピックでは、SDK を入手およびインストールする方法について説明します。
SDK があれば、アプリケーションをインストゥルメント化できます。SDK には、ビジネストランザクション、トランザクション スナップショット、バックエンド、終了コールの作成と管理を行うためのルーチンが用意されています。このトピックでは、これらの概念の概要について説明します。
Goアプリケーションのインストゥルメンテーションについて
次のトピックでは、Goアプリケーションでインストゥルメンテーションを実装する方法の一般的な概要を示します。
- アプリケーションへの AppDynamics API ファイルのインポート
- Initialize the Controller Configuration
- Initialize the Agent
- Create Business Transactions
- Manage Business Transaction Snapshots
- Create Backends
- Manage Exit Calls
- Correlate with Other Business Transactions
- Terminate the Agent
アプリケーションへのAppDynamicsパッケージのインポート
SDK をダウンロードすると、Go アプリケーションに AppDynamics インストゥルメンテーションを追加する準備ができます。最初のステップでは、AppDynamicsパッケージをインポートします。
import appd "appdynamics"
コントローラ構成の初期化
コントローラ情報の設定では、 SDKからコントローラへの接続が許可されています。一部の設定はすべてのアプリケーションで必須ですが、その他の設定は特定のタイプのアプリケーション環境でのみ必要です。たとえば、 SDK からネットワーク内の内部プロキシ経由でコントローラに接続する必要がある場合は、プロキシの接続設定を行います。
設定および設定が必要な情報の完全なリストについては、「Go SDK 参考資料」で「エージェントの構成設定」を参照してください。
アプリケーションで、必須の設定に値を割り当てます。コントローラの接続情報を設定する例:
cfg := appd.Config{}
cfg.AppName = "exampleapp"
cfg.TierName = "orderproc"
cfg.NodeName = "orderproc01"
cfg.Controller.Host = "my-appd-controller.example.org"
cfg.Controller.Port = 8080
cfg.Controller.UseSSL = true
cfg.Controller.Account = "customer1"
cfg.Controller.AccessKey = "secret"
cfg.InitTimeoutMs = 1000 // Wait up to 1s for initialization to finish
[InitTimeoutMs
] フィールドに注意してください。構成を初期化したら、InitSDK()
を使用してエージェントを初期化するコールに構成オブジェクトを渡します。[InitTimeoutMs
] フィールドには、次の値を設定できます。
- 0 に設定すると(デフォルト)、
InitSDK()
関数は非同期アクションとして動作するので、初期化コールはプログラムをブロックしません。 - この値を -1 に設定すると、エージェントがコントローラ構成を受信するまで無期限に待機するようにプログラムが指示されます。つまり、
InitSDK
()
メソッドは control を返します。アプリケーションの起動時に発生する短時間のビジネストランザクションをキャプチャし、コントローラから構成が送信されるまでの待機時間が延びても問題ない場合は、役に立ちます。 - または、待機する特定のミリ秒数に設定します。
マルチテナントコントローラ(SaaS またはオンプレミスマルチテナント)を使用する場合は、AddAppContextToConfig()
メソッドを使用してマルチテナント環境用のコンテキストを作成する必要があります。これによりコンテキストは、特定の操作(BT の開始やカスタムメトリックの追加など)を実行するメソッドへのパラメータとして渡すことができます。AddAppContextToConfig
()
および関連メソッドの詳細については、「Go SDK 参考資料」を参照してください。
エージェントの初期化
main 関数で、InitSDK()
に構成構造体を渡してエージェントを初期化します。
InitSDK()
が nil を返す場合、エージェントは正常に初期化されています。エラーが返ってくる場合は、エージェントがコントローラに接続できなかった可能性が高くなります。
次の例は、SDKを初期化する方法を示しています。
if err := appd.InitSDK(&cfg); err != nil {
fmt.Printf("Error initializing the AppDynamics SDK\n")
} else {
fmt.Printf("Initialized AppDynamics SDK successfully\n")
}
ビジネストランザクションの作成
StartBT()
コールと EndBT()
コールの間に、モニタ対象のリクエストで構成されるコードを囲んで、ビジネストランザクションを定義します。そのビジネストランザクションが影響を受ける後続のルーチンで使用されるハンドルが StartBT()
から返されます。
アップストリームのビジネストランザクションと相関するビジネストランザクションを作成する場合は、アップストリームのトランザクションの相関ヘッダーを渡して、作成する新しいトランザクションと関連付けることができます。「Go SDK 参考資料」の「GetExitcallCorrelationHeader()
」を参照してください。トランザクションと別のトランザクションを相関させる必要がない場合は、相関ヘッダーパラメータとして空の文字列を渡します。
オプションで、ビジネス トランザクション ハンドルを GUID とともにグローバル ハンドル レジストリに格納すると、後で StoreBT()
を使用して簡単に取得できます。using
GetBT()
によって、グローバル ハンドル レジストリからハンドルを取得します。
次に、ビジネストランザクションの設定例を示します。
// start the "Checkout" transaction
btHandle := appd.StartBT("Checkout", "")
// Optionally store the handle in the global registry
appd.StoreBT(btHandle, my_bt_guid)
...
// Retrieve a stored handle from the global registry
myBtHandle = appd.GetBT(my_bt_guid)
// end the transaction
appd.EndBT(btHandle)
トランザクションの開始と終了の間に、ビジネストランザクションへのエラーの追加、トランザクション スナップショット属性の定義、バックエンドと終了コールの追加などの操作を実行できます。
EndBT()
へのコールによってビジネストランザクションが終了すると、エージェントはビジネストランザクションのメトリックの報告を停止します。
ビジネストランザクションエラーの追加
AddBTError()
を使用してビジネストランザクションのエラーを報告します。この関数の markBTAsError
パラメータを設定すると、トランザクションはエラーが発生した際にエラートランザクションとして報告されます。
SDKでは、エラーレベルをAPPD_LEVEL_NOTICE、APPD_LEVEL_WARNING、またはAPPD_LEVEL_ERRORとして分類して定数が提供されます。
ビジネストランクションスナップショットの管理
エージェントは、ビジネストランザクションをモニタする際、特定の時点でのビジネストランザクションのインスタンスを示すトランザクションスナップショットを自動作成します。トランザクションスナップショットには多くの詳細が含まれるため、パフォーマンス低下時のトラブルシューティングに大変役立ちます。
スナップショットを作成するには、ビジネストランザクションを作成する以外に変更することは何もありませんが、以下を実行するコールを追加できます。
- スナップショットが取得されているかを確認
- スナップショットに追加データを提供
- スナップショットにURLを設定
エージェントが現在スナップショットを取得しているかを確認
スナップショットは高価なため、常にエージェントがスナップショットを収集しているとは限りません。デフォルトではスナップショットは10分ごとに収集されますが、このスケジュールは構成可能です。頻度に関する情報については、「トランザクションスナップショット」の「スナップショット定期収集頻度の構成」を参照してください。
エージェントがスナップショットを収集している場合に true
を返す IsBTSnapshotting()
を使用して、スナップショットが現在取得されているかどうかを確認できます。主に、スナップショットのユーザーデータ収集のための無駄なオーバーヘッドや、現在スナップショットが収集されていない場合にスナップショットURLを設定することを回避するために使用します。
ビジネストランザクションユーザーデータの追加
必要に応じて、トランザクション スナップショットにデータを追加できます。たとえば、多数のエラーが発生しているユーザ、応答時間が遅くなっているリージョンやどのメソッドが遅いのかを把握できます。データは、AppDynamics UI のトランザクション スナップショットの [USER DATA] タブに表示されます。
スナップショットが発生しているときは、AddUserDataToBT()
を使用してスナップショットに収集させるデータのキーと値を渡します。
スナップショットURLの追加
スナップショットが発生している場合は、SetBTURL()
を使用して現在のスナップショットに URL を設定できます。
スナップショットの設定例
func setSnapshotAttributes(bt appd.BtHandle, key, value string) {
if appd.IsBTSnapshotting(bt) {
appd.AddUserDataToBT(bt, key, value)
appd.SetBTURL(bt, "user/login")
}
}
バックエンドの作成
バックエンドは、データベースまたはアプリケーションが使用するメッセージキュー、HTTPサービス、またはキャッシュサービスなどのリモートサービスです。バックエンドコンポーネント自体はアプリケーションエージェントにより監視されませんが、エージェントはインストゥルメント化されたサーバーからの呼び出しを監視します。インストゥルメント化された環境でエージェントがバックエンドを登録するようにバックエンドを作成する必要があります。インストゥルメント化されたアプリケーションを作成し、バックエンドに追加するには、以下が必要となります。
- バックエンドの命名
- 識別プロパティの設定
- 必要に応じて、AppDynamics UIにおけるバックエンド表示方法の構成
識別プロパティ
バックエンドには識別プロパティが設定されています。これらのプロパティは、バックエンドのタイプおよび表示する情報のタイプによって異なります。コントローラでは、バックエンドのダッシュボードに識別プロパティが表示されます。追加するバックエンドのタイプに少なくとも 1 つの識別プロパティを設定する必要があります。
次に、OracleデータベースのコントローラUIのバックエンドプロパティを示します。
ティアへの転換
デフォルトでは、コントローラは検出されたバックエンドをフローマップ内の別のエンティティとして表示することはありませんが、エージェントはそのメトリックをダウンストリームティアの一部として報告します。バックエンドを個別のコンポーネントとして表示し、ティアに転換しない場合は resolve
を false
に設定します。詳細については、「リモートサービスのティアへの転換」を参照してください。
バックエンドの例
次のリストに、データベースバックエンドの設定例を示します。
backendName := "Cart Product Database"
backendType := "DB"
backendProperties := map[string]string {
"DATABASE": "sqlite3",
}
resolveBackend := false
appd.AddBackend(backendName, backendType, backendProperties, resolveBackend)
終了コールの管理
アプリケーションが別のコンポーネント(検出されたバックエンドまたは別のアプリケーションサーバなど)を呼び出すと、エージェントはこれらの呼び出しに関するメトリックを報告します。
StartExitCall()
と EndExitcall()
コールの間に終了コールを構成するコードを囲み、終了コールを定義します。StartExitcall()
はその終了コールに影響を与える後続のルーチンで使用するハンドルを返します。終了コールは、ビジネストランザクションのコンテキスト内で発生します。
オプションで、終了コールハンドルを GUID とともにグローバル ハンドル レジストリに格納すると、後で StoreExitcall()
を使用して簡単に取得できます。using
GetExitcall()
によって、グローバル ハンドル レジストリからハンドルを取得します。
必要に応じて、SetExitcallDetails()
を使用して任意の文字列として終了コールに詳細を追加できます。詳細はコントローラUIのトランザクションスナップショットの終了コール詳細に報告されます。
AddExitcallError()
を使用して終了コールにエラーを追加することもできます。エラーレベルには列挙型を使用します。また、エラーメッセージを追加することもできます。
単純な終了コールの例
// start the exit call to backendName
ecHandle := appd.StartExitcall(btHandle, backendName)
...
// optionally store the handle in the global registry
appd.StoreExitcall(ecHandle, my_ec_guid)
...
// retrieve a stored handle from the global registry
myEcHandle := appd.GetExitcall(my_ec_guid)
// set the exit call details
if err := appd.SetExitcallDetails(myEcHandle, "Exitcall Detail String"); err != nil {
log.Print(err)
}
// add an error to the exit call
appd.AddExitcallError(myEcHandle, appd.APPD_LEVEL_ERROR, "exitcall error!", true)
// end the exit call
appd.EndExitcall(myEcHandle)
他のビジネストランザクションとの相関
相関ヘッダーには、エージェントが複数のティアにわたるビジネストランザクションのフローを継続できるようにする情報が含まれています。
SDK エージェントは、他の SDK エージェントや特定のタイプのエントリポイントとイグジットポイントに対して自動で相関を実行する他の AppDynamics エージェント(Java、.NET、PHP など)と相互に関連付けることができます。
アップストリームティアとの相関
インストゥルメント化されたプロセスが、自動相関に対応するアップストリームエージェントからの継続的なトランザクションを受信したら、以下を行います。
サードパーティの
Header.Get()
関数を使用して、受信 HTTP ペイロードからAPPD_CORRELATION_HEADER_NAME
という名前のヘッダーを抽出。ヘッダーを
StartBT()
に渡す。例:hdr := req.Header.Get(appd.APPD_CORRELATION_HEADER_NAME) bt := appd.StartBT("Fraud Detection", hdr)
CPP
Header.Get()
関数で取得したヘッダーが有効な場合、StartBT()
コールにより開始したビジネストランザクションは、アップストリームサービスにより開始したビジネストランザクションを継続します。
ダウンストリームティアとの相関
ダウンストリーム エージェントは、HTTP ペイロード内にある singularityheader
という名前の相関ヘッダーをモニタしています。
SDKエージェントが、自動相関に対応するダウンストリームエージェントへの終了コールを行っている場合は、以下を実行します。
APPD_CORRELATION_HEADER_NAME
を使用して相関ヘッダーの名前を設定。- 終了コールを開始。
GetExitcallCorrelationHeader()
関数を使用して終了コールから相関ヘッダーを取得。- サードパーティのHTTP関数を使用して、HTTP POST要求を準備。
- ステップ 3 で取得した相関ヘッダーの値とともに、
APPD_CORRELATION_HEADER_NAME
という名前のヘッダーを HTTP 要求の送信ペイロードに挿入。 リクエストを実行することができます。 {{2}}は特定の属性を識別し、 {{3}} はこの属性に割り当てる新規の値を指定します。
inventoryEcHandle := appd.StartExitcall(btHandle, "Inventory DB") hdr := appd.GetExitcallCorrelationHeader(inventoryEcHandle) client := &http.Client{ CheckRedirect: redirectPolicyFunc, } req, err := http.NewRequest("POST", "https://inventory/holds/xyz", nil) // ... req.Header.Add(appd.APPD_CORRELATION_HEADER_NAME, hdr) resp, err := client.Do(req) // ... ...
CPP
エージェントの終了
アプリケーションが終了する直前にエージェントを終了します。
appd.TerminateSDK()