Go SDK 参考資料

Google Go アプリケーションをインストゥルメント化するには、AppDynamics Go SDK を使用します。この API には、ビジネストランザクション、トランザクションバックエンド、イグジットポイントなどを作成する関数が含まれています。「Go SDK の使用」を参照してください。

基本タイプ

AppDynamics Go SDK では、次の Opaque タイプが定義されます。

BtHandle：アクティブなビジネストランザクションへのハンドル
ExitcallHandle：アクティブな終了コールへのハンドル

構成構造体

Config 構造体には、AppDynamics コントローラに接続するエージェントで使用される設定が含まれています。この構造体の機能は、「エージェントとコントローラの接続」で説明したエージェント構成ファイルと同等です。

Config 構造体は次のように定義されます。

type Config struct {
    AppName, TierName, NodeName string
    Controller Controller
    InitTimeoutMs int
    Initialized uint // a special field used by the underlying AppDynamics libraries. Do not use.
    Logging LoggingConfig
    UseConfigFromEnv bool
    EnvVarPrefix string
}

CPP

この構造体は次のフィールドで構成されています。

AppName：このノードが属するビジネスアプリケーションの名前。
TierName：このノードが属するティアの名前。ティアは、同一または類似のノードのグループです。発生元ティアは、ビジネストランザクションの最初のリクエストを受信するティアです。ダウンストリームティアは、別のティアから呼び出されたティアであり、ビジネストランザクションを継続します。
NodeName：このエージェントでモニタされるモニタ対象アプリケーションサーバ。
Controller：コントローラの接続設定。この構造体は次のように定義されます。
```
type Controller struct {
    Host string
    Port uint16
    Account, AccessKey string
    UseSSL bool
    HTTPProxy HTTPProxy
    CertificateFile
    CertificateDir
}
```
CODE
Controller 構造体には次のフィールドが含まれています。
- Host：コントローラホスト。
- Port：コントローラポート。デフォルトは 8080。
- Account：AppDynamics アカウントの名前。
- Access_key：AppDynamics アカウントのキー。アクセスキーを検索するには、AppDynamics UIの右上にある設定（歯車）アイコンをクリックし、Licenseをクリックします。
- UseSSL：コントローラとの SSL 通信を有効化。デフォルトは false。有効にするには、trueに設定します。UseSSL を true に設定すると、デフォルトの証明書である ca-bundle.crt が使用されます。独自の証明書を使用するには、証明書ファイルとディレクトリを CertificateFile および CertificateDir パラメータに指定します。
- HTTPProxy：エージェントからローカル HTTP プロキシ経由でコントローラに接続する必要がある場合は、この構造体を使用してプロキシの接続設定を指定します。
- CertificateFile：SSL 証明書のファイル名。
- CertificateDir：SSL 証明書が配置されているディレクトリ。
InitTimeoutMs：初期化関数（InitSDK）はビジネストランザクションを開始するためにコントローラ構成を参照します。初期化関数がアプリケーションをブロックしないように、この設定を使用します。これにより、コントローラ構成を待機するかどうか、待機する場合はビジネストランザクションを開始するまでの待機時間を InitSDK で指定できます。有効な値は次のとおりです。
- N：最大 N ミリ秒までコントローラ構成を待機します。
- 0：コントローラ構成を待機しません。これがデフォルトです。
- -1：エージェントでコントローラ構成が受信されるまで無期限に待機します。
Logging：コントローラのログ設定。この構造体は次のように定義されます。
```
const (
    APPD_LOG_LEVEL_DEFAULT LogLevel = iota
    APPD_LOG_LEVEL_TRACE
    APPD_LOG_LEVEL_DEBUG
    APPD_LOG_LEVEL_INFO
    APPD_LOG_LEVEL_WARN
    APPD_LOG_LEVEL_ERROR
    APPD_LOG_LEVEL_FATAL
)
type LoggingConfig struct {
    BaseDir             string
    MinimumLevel        LogLevel
    MaxNumFiles         uint
    MaxFileSizeBytes    uint
}
```
CODE
Logging 構造体には次のフィールドが含まれています。
- BaseDir:：ログファイルが書き込まれるディレクトリへの絶対パス。空のままにした場合のデフォルトは、/tmp/appd です。
- MinimumLevel：上記の APPD_LOG_LEVEL_xxx 定数のいずれか。デフォルトは APPD_LOG_LEVEL_INFO です。
- MaxNumFiles：ディスクに格納されるログファイルの最大数。この最大数に達すると、古いログがローテーションされます。
- MaxFileSizeBytes：ローテーションされるまでのログファイルの最大サイズ。
UseConfigFromEnv:SDK で任意の構成環境変数をチェックし、それらの構成値を初期化時に使用する場合は、true に設定します。これは初期化時に発生するため、プログラムで設定した構成が環境変数の設定でオーバーライドされることに注意してください。
EnvVarPrefix:UseConfigFromEnv が true に設定されている場合は、このプロパティを使用して、環境変数名で使用されるプレフィックスを指定します。デフォルトのプレフィックスは APPD_SDK です。

エージェントからローカルHTTPプロキシサーバー経由でコントローラに接続する必要がある場合は、プロキシサーバーの設定を構成する必要があります。これを行うには、次で定義する HTTPProxy 構造体を使用します。

type HTTPProxy struct {
    Host string
    Port uint16
    Username, PasswordFile string
}

CPP

HTTPProxy 構造体には次のフィールドが含まれています。

Host:HTTP プロキシサーバのホスト名または IP アドレス
Port:プロキシサーバのポート
Username:プロキシサーバのユーザ名
PasswordFile:プロキシサーバのパスワードファイル。

ContextConfig 構造体

マルチテナントコントローラ環境に適用するコールには、ContextConfig 構造体を使用します。

type ContextConfig struct {
    AppName string
    TierName string
    NodeName string
}

ContextConfig 構造体には次のフィールドが含まれています。

AppName:このノードが属するビジネスアプリケーションの名前。
TierName:このノードが属するティアの名前。ティアは、同一または類似のノードのグループです。発生元ティアは、ビジネストランザクションの最初のリクエストを受信するティアです。ダウンストリームティアは、別のティアから呼び出されたティアであり、ビジネストランザクションを継続します。
NodeName：このエージェントでモニタされるモニタ対象アプリケーションサーバ。

AddAppContextToConfig

マルチテナントコントローラのAppDynamics構成にアプリケーションコンテキストを追加します。

形式

func AddAppContextToConfig(cfg *Config, context string, contextCfg *ContextConfig) error

パラメータ

cfg：AppDynamics 構成オブジェクト。
context:このコンテキストへの参照に使用される一意の識別子。
contextCfg:このコンテキストのビジネスアプリケーション、ティア、およびノードの名前を示す AppDynamics コンテキスト構成オブジェクト。

InitSDK

AppDynamics Go SDK を初期化します。この関数は、可能であればアプリケーションの起動時にインストゥルメント化されたアプリケーションから 1 回呼び出される必要があります。

形式

func InitSDK(cfg *Config) error

パラメータ

cfg:エージェントとコントローラ間の通信を有効にする AppDynamics 構成設定。

返り値

成功の場合はゼロ、それ以外の場合はエラー値

TerminateSDK

AppDynamics Go SDK を停止します。このエージェントのアクティブなビジネストランザクションがすべて終了し、コントローラにレポートするエージェントメトリックが停止します。

形式

func TerminateSDK()

StartBT

ビジネストランザクションを開始するか、既存のトランザクションを継続します。

各アプリケーションのビジネスアプリケーション登録上限は200件、各エージェントのビジネスアプリケーション登録上限は50件であることに注意してください。他のタイプのエージェントで検出されるトランザクションとは異なり、Go SDK でレポートされる、制限を超えたビジネストランザクションはその他すべてのトラフィックのグループ化に含まれません。つまり、エージェントで過剰にビジネストランザクションが作成されないようにすることはユーザーの責任です。実装によってビジネストランザクションが爆発的に増加する可能性が生じないように注意してください。

形式

func StartBT(name, correlation_header string) BtHandle

パラメータ

name:ビジネストランザクションの名前。有効な相関ヘッダーを含む現在のビジネスアプリケーションの継続トランザクションである場合は、ヘッダーの名前が SDK で使用されます。文字「{ } [ ] | & ;」はトランザクション名に使用できません。
correlation_header:継続トランザクションの場合は相関ヘッダー、それ以外は NULL。指定した場合、相関ヘッダーは別の AppDynamics エージェントによって生成されていて、このエージェントでは文字列として使用可能です。相関ヘッダーは、このトランザクションがアップストリームトランザクションと相関するための情報を提供します。

返り値

開始したビジネストランザクションの不透明ハンドル。

StartBTWithAppContext

ビジネストランザクションを開始するか、マルチテナントコントローラ環境内の既存のトランザクションを継続します。

形式

func StartBTWithAppContext(context, name, correlation_header string) BtHandle

パラメータ

context:このビジネストランザクションが属するアプリケーションコンテキスト名。
name:ビジネストランザクションの名前。有効な相関ヘッダーを含む現在のビジネスアプリケーションの継続トランザクションである場合は、ヘッダーの名前が SDK で使用されます。文字「{ } [ ] | & ;」はトランザクション名に使用できません。
correlation_header:継続トランザクションの場合は相関ヘッダー、それ以外は NULL。指定した場合、相関ヘッダーは別の AppDynamics エージェントによって生成されていて、このエージェントでは文字列として使用可能です。相関ヘッダーは、このトランザクションがアップストリームトランザクションと相関するための情報を提供します。

EndBT

指定のビジネストランザクションを終了します。

形式

func EndBT(bt BtHandle)

パラメータ

bt:終了するビジネストランザクションへのハンドル。

GetBT

appd_bt_store で指定の GUID に関連する BT ハンドルを取得します。

形式

func GetBT(guid string) BtHandle

パラメータ

guid:appd_bt_store に渡されたグローバルな一意の識別子。

返り値

指定のGUIDに関連するビジネストランザクションへのハンドル。

以下の場合、SDKは警告を記録し他のAPI関数で安全に使用できるハンドルを返す。結果として、関数が何もせずすぐに戻り値を返す場合ことになる。

SDKによりGUIDに関連するハンドルが見つからない
SDKがハンドルを取得する前にコールが終了した

IsBTSnapshotting

エージェントが現在トランザクションスナップショットを取得しているかどうかをレポートします。スナップショットが取得されていない場合、潜在的にコストが高い関数が何もしていない可能性を調べることができるため、AddUserDataToBT または SetBTURL を呼び出す前に使用すると効果的です。

形式

func IsBTSnapshotting(bt BtHandle) bool

パラメータ

bt: スナップショットの取得をチェックするためのビジネストランザクションへのハンドル。

返り値

指定のビジネストランザクションでスナップショットが取得されている場合は true。それ以外の場合は false になります。

SetBTURL

スナップショットのURLを設定します（取得されている場合）。スナップショットが発生していないときに、この関数を呼び出すと安全です。指定のビジネストランザクションでスナップショットが取得されていないときは、この関数がすぐに戻ります。ただし、この関数に渡すデータの抽出はコストが高い場合、IsBTSnapshotting を使用して、データが抽出され、この関数が呼び出される前にビジネストランザクションでスナップショットが取得されているかどうかを確認できます。url 引数データは、7 ビット ASCII または UTF-8 である必要があります。

形式

func SetBTURL(bt BtHandle, url string)

パラメータ

bt:ユーザデータを追加するビジネストランザクション（スナップショットが取得されている場合）。
url:7 ビット ASCII または UTF-8 として取得されるスナップショットの URL 値。

StoreBT

GetBT を使用して後で取得するために、BT ハンドルをグローバルレジストリに格納します。これは、ビジネストランザクションの開始と終了を別々の場所で行う必要があり、必要なコード部分を使用してハンドルをビジネストランザクションに渡すことが困難である場合に便利です。

ビジネストランザクションが終了すると、ハンドルがグローバルレジストリから削除されます。

形式

func StoreBT(bt BtHandle, guid string)

パラメータ

bt:格納される BT。
guid:指定の BT に関連付けるグローバルな一意の識別子。

AddBTError

ビジネストランザクションにエラーを追加します。エラーはビジネストランザクションの一部としてレポートされます。ただし、ビジネストランザクションにエラーのマークを付けずにエラーを追加できます（たとえば、致命的なエラー以外の場合）。

形式

func AddBTError(bt BtHandle, level ErrorLevel, message string, mark_bt_as_error bool)

パラメータ

bt:エラーが追加されたビジネストランザクションへのハンドル。
level:エラーレベル（次のオプションから選択）：
- APPD_LEVEL_NOTICE
- APPD_LEVEL_WARNING
- APPD_LEVEL_ERROR
message:このエラーのエラーメッセージ。
mark_bt_as_error:true に設定すると、このエラーが発生したビジネストランザクションにエラートランザクションのマークが付けられます。この場合、ビジネストランザクションはエラートランザクションとしてのみカウントされます。トランザクションが遅延または停滞していた場合でも、遅い、非常に遅い、または停滞するトランザクションとしてカウントされません。false に設定すると、ビジネストランザクションにエラートランザクションのマークが付けられません。

AddUserDataToBT

特定のビジネストランザクションで生成されたトランザクションスナップショットにユーザーデータを添付。

ユーザデータはビジネストランザクションに追加されますが、トランザクションスナップショットが発生している場合にのみ報告されます。ユーザデータは、コントローラ UI のトランザクションスナップショット詳細の [USER DATA] タブに表示されます。

スナップショットが発生していないときに、この関数を呼び出すと安全です。指定のビジネストランザクションがスナップショットを取得していないときは、この関数がすぐに戻る。

この関数に渡すデータの抽出はコストが高い場合、IsBTSnapshotting を使用して、データが抽出され、この関数が呼び出される前にビジネストランザクションで実際にスナップショットが取得されているかどうかを確認できます。

value 引数のデータは、7 ビット ASCII または UTF-8 である必要があります。

形式

func AddUserDataToBT(bt BtHandle, key, value string)

パラメータ

bt ：ユーザデータを追加するビジネストランザクション（スナップショットが取得されている場合）。
key ：7 ビット ASCII または UTF-8 としてスナップショットに追加するユーザデータの名前。
value ：7 ビット ASCII または UTF-8 としてスナップショットに追加するユーザデータの値。

AddBackend

バックエンドをビジネスアプリケーションに追加します。

この関数は、追加するバックエンドのタイプに少なくとも1つの識別プロパティが存在しなければ失敗します。

形式

func AddBackend(name, backendType string, identifyingProperties map[string]string, resolve bool) error

パラメータ

name:バックエンドの名前。Go SDKインスタンスごとに一意である必要があります。
backendType:バックエンドのタイプ（次のオプションから選択）：
- APPD_BACKEND_HTTP
- APPD_BACKEND_DB
- APPD_BACKEND_CACHE
- APPD_BACKEND_RABBITMQ
- APPD_BACKEND_WEBSERVICE
- APPD_BACKEND_JMS

identifyingProperties:バックエンドの識別プロパティが含まれるキー/値ペアのマップ。バックエンドは、プロパティによって一意に識別されます。これらのプロパティは、バックエンドダッシュボードの右上にあるパネルに表示されます。ビルトイン終了コールタイプのいずれかのバックエンドを追加するときは、少なくとも1つの識別プロパティを設定する必要があります。有効なプロパティは、以下に示すように終了コールタイプごとに異なります。

終了コールタイプ	有効な識別プロパティ
`APPD_BACKEND_HTTP`	"HOST"、"PORT"、"URL"、"QUERY STRING"
`APPD_BACKEND_DB`	"HOST"、"PORT"、"DATABASE"、"VENDOR"、"VERSION"
`APPD_BACKEND_CACHE`	"SERVER POOL"、"VENDOR"
`APPD_BACKEND_RABBITMQ`	"HOST"、"PORT"、"ROUTING KEY"、"EXCHANGE"
`APPD_BACKEND_WEBSERVICE`	"SERVICE"、"URL"、"OPERATION"、"SOAP ACTION"、"VENDOR"
`APPD_BACKEND_JMS`	"DESTINATION "、" DESTINATIONTYPE "、" VENDOR "

たとえば、キー PORT の値は 3304 です。

resolve:ダウンストリームエージェントがこのバックエンドとして解決されないようにするには、このプロパティを false に設定します。
true の場合（デフォルト）、未解決のバックエンドの相関ヘッダーを検出したエージェントがそのバックエンドとして解決されます。ただし、実際にバックエンドが相関ヘッダーを通過するインストゥルメント化されていないティア（メッセージキューやプロキシなど）である場合は、ルーティングされるティアとは異なるようにバックエンドを表示させることがあります。false の場合、このバックエンドへの終了コールに生成された相関ヘッダーによって、バックエンドとは異なるようにレポートすることがダウンストリームエージェントに指示されます。
たとえば、ティアAからインストゥルメント化されていないバックエンドBに接続し、そのバックエンドBからティアCにルーティングされている場合は、この設定によってフローマップが次のような影響を受けます。
- true。フローマップは A > C になります。
- false。フローマップは A > B > C になります。

返り値

成功の場合はゼロ、それ以外の場合はエラー値

AddExitcallError

終了コールにエラーを追加します。

形式

func AddExitcallError(exitcall ExitcallHandle, level ErrorLevel, message string, mark_bt_as_error bool)

パラメータ

exitcall:終了コールへのハンドル。
level:このエラーのレベル（次のオプションから選択）。
- APPD_LEVEL_NOTICE
- APPD_LEVEL_WARNING
- APPD_LEVEL_ERROR
message:このエラーのエラーメッセージ。
mark_bt_as_error:true に設定すると、このエラーが発生した終了コールを行うビジネストランザクションにエラートランザクションのマークが付けられます。この場合、ビジネストランザクションはエラートランザクションとしてのみカウントされます。トランザクションが遅延または停滞していた場合でも、遅い、非常に遅い、または停滞するトランザクションとしてカウントされません。false に設定すると、ビジネストランザクションにエラートランザクションのマークが付けられません。

StartExitcall

ビジネストランザクションの一部として指定したバックエンドへの終了コールを開始します。

形式

func StartExitcall(bt BtHandle, backend string) ExitcallHandle

パラメータ

bt:終了コールを行うビジネストランザクションへのハンドル。
backend:終了コールの宛先バックエンド。AppDynamicsでは自動的にGoアプリケーションのバックエンドが検出されないため、宛先バックエンドを指定する必要があります。

返り値

開始した終了コールへの Opaque ハンドル。

EndExitcall

終了コールを完了します。

形式

func EndExitcall(exitcall ExitcallHandle)

パラメータ

exitcall:終了する終了コールへのハンドル。

GetCRollupType

メトリックの値を時間経過とともにロールアップする方法を指定します。

形式

func GetCRollupType(rollUp RollupType)

Parameters

rollUp:メトリックをロールアップする方法。有効なロールアップオプションは次のとおりです。
- APPD_TIMEROLLUP_TYPE_AVERAGE：ティア内の各ノードにわたるすべてのメトリック値の平均。
- APPD_TIMEROLLUP_TYPE_SUM：1 分間以内にレポートされたすべての値の合計。
- APPD_TIMEROLLUP_TYPE_CURRENT：1 分間以内で最後にレポートされたメトリック。

GetCClusterRollupType

ティア（ノードのクラスタ）のメトリック値を集計する方法を指定します。

形式

func GetCClusterRollupType(rollUp ClusterRollupType)

Parameters

rollUp:メトリックをロールアップする方法。有効なロールアップオプションは次のとおりです。
- APPD_CLUSTERROLLUP_TYPE_INDIVIDUAL：ティア内の各ノードにわたるすべてのメトリック値の平均。
- APPD_CLUSTERROLLUP_TYPE_COLLECTIVE：ティア内の全ノードのすべてのメトリック値の合計。

GetExitcall

StoreExitcall 経由で GUID に関連する終了コールへのハンドルを取得します。

形式

func GetExitcall(guid string) ExitcallHandle

パラメータ

guid:appd_exitcall_store() に渡されたグローバルな一意の識別子。

返り値

指定のGUIDに関連する終了コールへのハンドル。

以下の場合、SDKは警告を記録し他のAPI関数で安全に使用できるハンドルを返す。結果として、関数が何もせずすぐに戻り値を返す場合ことになる。

SDKによりGUIDに関連するハンドルが見つからない
SDKがハンドルを取得する前にコールが終了した

GetExitcallCorrelationHeader

ビジネストランザクションを相関させるためのヘッダーを取得します。

相関させる終了コールがビジネストランザクションで行われる場合は、この関数を使用して相関ヘッダーを取得し、それを終了コールのペイロードに挿入する必要があります。

返された文字列は、終了コールが終了すると解放されます。自分で解放しないでください。

形式

func GetExitcallCorrelationHeader(exitcall ExitcallHandle) string

パラメータ

exitcall:終了コールへのハンドル。

戻り値

成功した場合は、相関情報を含む 7 ビット ASCII 文字列が返されます。この文字列を終了コールのペイロードに挿入できます。これにより、ダウンストリームエージェントはこのペイロードからヘッダーを抽出して、ビジネストランザクションを継続できます。

エラー時は、ダウンストリームビジネストランザクションの検出が回避されるデフォルトのヘッダーが返されます。

SetExitcallDetails

終了コールの詳細文字列を設定します。たとえば、DB バックエンドで終了コールの一部として実行される SQL ステートメントを追加する場合に使用できます。このデータは、トランザクションスナップショットの終了コール詳細 UI に表示されます。

形式

func SetExitcallDetails(exitcall ExitcallHandle, details string) error

パラメータ

exitcall:終了コールへのハンドル。
details:終了コールに追加する任意の文字列。

返り値

成功の場合は Nil、それ以外の場合はエラー値

StoreExitcall

GetExitcall を使用して後で取得するために、終了コールハンドルをグローバルレジストリに格納します。これは、コールの開始と終了を別々の場所で行う必要があり、必要なコード部分を使用してハンドルを渡すことが困難である場合に便利です。

このハンドルは、終了コール（またはそれを含む BT）が終了すると削除されます。

形式

func StoreExitcall(exitcall ExitcallHandle, guid string)

パラメータ

exitcall:格納される終了コール。
guid:指定のコールに関連付けるグローバルな一意の識別子。

例

ExitcallHandle ec = StartExitcall(bt, "authdb");
StoreExitcall(ec, "login-exit");