PHPエージェントAPI参考資料

関連ページ：

PHPエージェントAPIユーザーガイド

PHP エージェント API は、カスタムビジネストランザクションの定義と相関をサポートしています。単一の PHP 要求で複数のビジネストランザクションを生成する方法を提供します。

また、PHPエージェントが自動検出しない終了コールをモニタリングできます。

API参考資料の概要

APIでのオペレーションは、ビジネストランザクションの管理と終了コールの管理の2つのカテゴリに分かれます。

ビジネストランザクションの管理方法は次のとおりです。

bool appdynamics_start_transaction($transaction_name, $entry_point_type)
bool appdynamics_continue_transaction($correlation_header, $entry_point_type)
bool appdynamics_end_transaction()

終了コールの管理方法は次のとおりです。

ADExitCall appdynamics_begin_exit_call($type, $label, $properties, $exclusive=true)
void appdynamics_end_exit_call(ADExitCall $exitCall, $exception = null)
string ADExitCall::getCorrelationHeader()
void ADExitCall::setSQLQueryInfo($querystring, $boundparams)

以下のセクションでは API 内のメソッドについて詳しく説明します。

トランザクションの開始

カスタムビジネストランザクションを開始します。

形式

bool appdynamics_start_transaction($transaction_name, $entry_point_type)

説明

このコールによって開始されたビジネストランザクションがappdynamics_end_transaction()コールと一致しない場合、トランザクションはリクエストまたはスクリプトの完了時に終了します。

カスタムビジネストランザクションはネスト化できません。appdynamics_end_transaction() を呼び出す前に appdynamics_start_transaction() を複数回呼び出すと、最後の appdynamics_start_transaction() が使用され、それ以前のコールは破棄されます。

パラメータ

$transaction_name：コントローラでのトランザクションに使用される名前。文字「{ } [ ] | & ;」はトランザクション名に使用できません。

$entry_point_type：エントリポイントのフレームワークまたはプロトコルを示します。有効なエントリポイントタイプは、以下のようにPHP extension定数として提供されます。

AD_WEB
AD_MVC
AD_DRUPAL
AD_WORDPRESS
AD_CLI
AD_WEBSERVICE

エントリポイントタイプは大文字と小文字を区別します。

返り値

成功の場合はtrue、失敗の場合はfalse。

障害状態はApacheログで報告されます。失敗の理由には以下のものが挙げられます。

無効なトランザクション名（使用禁止文字が含まれている）
無効なエントリポイントタイプ
エージェントが初期化されていない
EUM ヘッダーが appdynamics_start_transaction() コールの前に送信された
相関ヘッダーが appdynamics_start_transaction() コールの前に送信された

トランザクションの続行

カスタムビジネストランザクションをアップストリームサービスと関連付けます。

形式

bool appdynamics_continue_transaction($correlation_header, $entry_point_type)

説明

PHP エージェントによりサポートされているエントリポイントではないサービスと関連付けるために、ダウンストリームティアが使用します。

パラメータ

$correlation_header：関連付けるアップストリームサービスの相関ヘッダー。

$correlation_headerを提供するためにサービスから相関情報を抽出するのは、開発者の担当です。「getCorrelationHeader()」を参照してください。

$entry_point_type：続行しているトランザクションのエントリポイントの、フレームワークまたはプロトコルを示すオプションのパラメータ。デフォルトでは、アプリケーションがCLIモードで実行されている場合は値は自動的にAD_CLIに設定され、それ以外の場合はAD_WEBに設定されます。

このパラメータを使用して、PHP Web アプリケーションから開始されるトランザクション（トランザクションの PHP CLI レグにこのアプリケーションが渡される）など、PHP タイプを渡す続行中トランザクション用に別の発信元 PHP アプリケーションタイプを示します。

有効なエントリポイントタイプは、PHP extension定数として提供されます。

AD_WEB
AD_MVC
AD_DRUPAL
AD_WORDPRESS
AD_CLI
AD_WEBSERVICE

エントリポイントタイプは大文字と小文字を区別します。

返り値

成功の場合は true、失敗の場合は false を返します。

トランザクションの終了

前の appdynamics_begin_transaction() のコールで作成された、または appdynamics_continue_transaction() で継続されたトランザクションを終了します。

形式

bool appdynamics_end_transaction()

説明

appdynamics_continue_transaction() call と組み合わせると、このコールはティア上の継続中のトランザクションを終了しますが、分散トランザクションの一部で、そのティアのダウンストリームであるこれ以降のコールは終了しません。

ビジネストランザクションが無効な場合、または要求/スクリプトで以前に appdynamics_begin_transaction() や appdynamics_continue_transaction() コールがなかった場合、この関数は false を返し、アプリケーションによってキャプチャされ、例外として報告される警告メッセージをスローします。

アプリケーションの例外としてログに記録されないように、アプリケーションでは appdynamics_begin_transaction() をラップして、考えられる例外を処理することをお勧めします。

終了コールの開始

終了コールの開始をマークします。

形式

ADExitCall appdynamics_begin_exit_call($type, $label, $properties, $exclusive=true)

パラメータ

$type: 終了コールの種類。以下のいずれかである必要があります。

AD_EXIT_HTTP
AD_EXIT_DB
AD_EXIT_CACHE
AD_EXIT_RABBITMQ
AD_EXIT_WEBSERVICE

$label

コントローラ UI の exit コールのラベル。40文字以下のラベルを使用すると、フローマップに収まります。

$properties

終了コールの識別プロパティの関連配列（名前/値のペア）。プロパティ名と値は文字列である必要があります。

各終了コールのタイプは独自のプロパティを持っています。プロパティ名の検証はありませんが、各終了タイプは伝統的に以下の名前を使用します。

タイプ
`AD_EXIT_HTTP`	`"HOST"`	`"PORT"`	`"URL"`	`"QUERY_STRING"`
`AD_EXIT_DB`	`"HOST"`	`"PORT"`	`"DATABASE"`	`"VENDOR"`	`"URL"`
`AD_EXIT_CACHE`	`"SERVER POOL"`	`"VENDOR"`
`AD_EXIT_RABBITMQ`	`"HOST"`	`"PORT"`	`"EXCHANGE"`	`"ROUTING KEY"`
`AD_EXIT_WEBSERVICE`	`"SERVICE"`	`"OPERATION"`	`"SOAP ACTION"`	`"VENDOR"`	`"URL"`

AD_EXIT_DB exit コールタイプについては、少なくとも HOST、PORT、VENDOR を指定することをお勧めします（これらのプロパティは Splunk AppDynamics DB 統合で使用されるため）。AD_EXIT_DB バックエンドの VENDOR プロパティは以下のいずれかに該当している必要があります。

MYSQL
POSTGRESQL
SQLSERVER
ORACLE
SYBASE
DB2

$exclusive：終了コールが排他的であるかどうかを示すブール型。

一度に実行できる排他的終了コールは1つのみです。たとえば、この API を使用して HTTP 終了コールを開始し、その直後に mysql_connect() コールが発生した場合、その HTTP コールが実行されている間は Mysql コールは検出されません。次の終了コールを検出または開始するには、排他的な終了コールが明示的に終了している必要があります。

終了コールはデフォルトで排他的なものになっていますが、このパラメータをfalseに設定することで包括的なものにできます。

このフラグを false に設定して、ネスト化された終了コールをサポートする方法の例については、『PHPエージェントAPIユーザーガイド』の「シナリオ：アプリケーションによるソケットベースの HTTP コールの作成」にある最後のコードサンプルを参照してください。

返り値

成功の場合は ADExitCall クラスのインスタンスを返し、エラーの場合は NULL を返します。

終了コールの終了

終了コールの終了をマークします。

形式

void appdynamics_end_exit_call(ADExitCall $exitCall, $exception = null)

パラメータ

$exitCall： appdynamics_begin_exit_call() から返された、終了させる終了コールを表すオブジェクト。

$exception：終了コール中にエラーが発生したかどうかを指定する例外オブジェクト（例外クラスまたはオブジェクトに由来するクラスのいずれか）。

相関ヘッダの取得

この終了コールの相関ヘッダーを返します。返された相関ヘッダーは appdynamics_continue_transaction に渡され、この終了コールと関連付けできます。

相関ヘッダーを HTTP ペイロードに挿入する例については、『PHPエージェントAPIユーザーガイド』の「シナリオ：アプリケーションによるソケットベースの HTTP コールの作成」も参照してください。

形式

string ADExitCall::getCorrelationHeader()

SQLクエリ情報の設定

この終了カスタムコールのSQLクエリを設定します。

形式

void ADExitCall::setSQLQueryInfo($querystring, $boundparams)

パラメータ

$querystring：SQL クエリを含む文字列。疑問符を使用してバインドされたパラメータを示します。

$boundparams：引用符で囲んだ文字列である、バインドパラメータのカンマ区切り配列（オプション）。

例

$exitCall-&gt;setSQLQueryInfo("SELECT * FROM mytable where id1=? and id2=?;", ('Susie', '12345'));

CODE