On this page:

Related pages:

PythonエージェントAPIは、以下の機能をサポートします。

  • カスタムビジネストランザクション
  • カスタムイグジットポイント
  • カスタムデータコレクタ

API一覧

APIへのアクセス

ご使用のアプリケーションでPythonエージェントAPIにアクセスする前に、以下の方法でPythonエージェントをインストールします。

pip install appdynamics

次に、インストゥルメント化したアプリケーションの一番上に以下を追加します。

from appdynamics.agent import api as appd
PY

エージェントの開始と停止

init(environ=None, timeout_ms=NO_TIMEOUT)

Pythonエージェントを初期化します。

この関数は、インストゥルメント化したアプリケーションの最初に（できれば他のインポートや他のスレッド作成を行う前に）呼び出します。

エージェントの初期化は非同期で発生します。NO_TIMEOUT が指定されると、asynchronously. init() はすぐに戻ってきますが、エージェントがビジネストランザクションを報告できる状態にすぐにはならない可能性があります。この場合、start_bt() メソッドは None を返します。

この関数が例外を発生させることはありません。

エージェントが正しく構成されている場合はTrueを返し、正しく構成されていない場合はFalseを返します。

正しく構成するには、エージェント構成ファイルに最低限の設定のほか、ご使用の環境で必要な場合は追加の設定を行います。最低限の設定を行うには「Pythonエージェントのインストール」の「エージェントの構成」を、完全なリストを確認するには「Pythonエージェント設定」を参照してください。

environ：辞書（オプション）

指定すると、実際のOS環境変数から派生したエージェントの構成を上書きするために使用する環境変数の辞書を表示します。

timeout_ms：整数または None（オプション）

タイムアウトの間隔をミリ秒で表示します。

デフォルトでは、Python エージェントがコントローラから構成を受信していなくてもすぐに init() が返ってきます。timeout_msがNoneの場合、init()はエージェントが正しく構成されるまでブロックします。それ以外の場合、init() はエージェントが正しく構成されるまで timeout_ms の時間待機します。

shutdown(timeout_ms=None)

Pythonエージェントをシャットダウンします。エージェントはコントローラへのメトリックの報告を停止します。

この関数は、すべてのアクティブなビジネストランザクションを終了し、コントローラへの報告が終了するまで待機してから返されます。

timeout_ms：整数（オプション）

デフォルトでは、この関数は保留中のビジネストランザクションがすべて報告されるまで待機してから返されます。timeout_ms が設定されている場合、すべてのビジネストランザクションが報告されているかどうかに関わらず、この関数は timeout_ms が経過すると返されます。

ビジネストランザクションの管理

start_bt(name, correlation_header=None)

指定した名前のビジネストランザクションを開始します。

スレッドごとに1つのアクティブなビジネストランザクションのみが存在することができます。同じスレッドで次のビジネストランザクションを開始しようとすると、Noneを返します。

トランザクションの開始時にBtHandleを返し、トランザクションが開始しない場合はNoneを返します。

name：文字列

開始するビジネストランザクションの名前。以下の文字はトランザクション名に使用することができません。  { } [ ] | & ;

correlation_header：文字列（オプション）

指定した場合、別のAppDynamicsエージェントが生成し、このエージェントに文字列として渡した相関ヘッダー。相関ヘッダーは、このトランザクションとアップストリームにあるトランザクションとの相関を可能にするための情報を提供します。

end_bt(bt_handle, exc=None)

bt_handleが特定するビジネストランザクションを終了します。

bt_handle：BtHandle

終了するビジネストランザクションを特定します。ハンドルは start_bt() により返されます。

exc：例外（例外のリスト）（オプション）

try-except ブロックで取得したこのビジネストランザクションの処理中に例外が発生し、この例外をビジネストランザクションの一部として報告する場合は、例外を exc として渡します。

複数の例外が同じビジネストランザクションに含まれており、それらすべてを報告する場合は、例外のリストを exc として渡します。

add_snapshot_data(bt_handle, key, value)

bt_handle で指定するビジネストランザクション用に生成されたトランザクション スナップショットにカスタムデータを添付します。

カスタムデータは、コントローラ UI のトランザクション スナップショット詳細の [USER DATA] タブに表示されます。

カスタムデータはビジネストランザクションに追加されますが、トランザクションスナップショットが生成された場合にのみ報告されます。トランザクション スナップショットが生成されるタイミングについては、「トランザクション スナップショットを使用したビジネス トランザクション パフォーマンスのトラブルシューティング」を参照してください。

bt_handle：BtHandle

カスタムデータを追加するビジネストランザクションを識別します。ハンドルは start_bt() により返されます。

key：バイトまたは unicode

スナップショットに報告されるデータ項目の名前。

バイトとして渡す場合、バッファは UTF-8 エンコードの文字列を表す必要があります。

value：任意

データの値。 

バイトとして渡す場合、データの文字列はUTF-8のエンコードで取り扱われます。Unicodeとして渡された場合は直接報告されます。

その他すべてのオブジェクトは、str(value) に変換されます。

get_active_bt_handle(request)

要求オブジェクトに関連付けられたビジネストランザクションへのBtHandleを返します。ビジネストランザクションが見つからない場合は、Noneを返します。

これは、ビジネストランザクションが API でなくデフォルトの Python エージェント インストゥルメンテーションによって作成された場合、start_exit_call() などの別の API 関数にビジネス トランザクション ハンドルを渡す場合に役立ちます。

request object

アクティブなビジネストランザクションに関連付けられた要求オブジェクト。ビジネストランザクションを開始したフレームワークにより異なります。

要求オブジェクトを取得する方法については、該当するフレームワークのドキュメンテーションを参照してください。

フレームワーク要求オブジェクトのドキュメンテーション
Flaskhttps://flask-cn-doc.readthedocs.io/en/latest/reqcontext.html
Djangohttps://docs.djangoproject.com/en/1.8/ref/request-response/
CherryPyhttps://cherrypy.readthedocs.io/en/latest/basics.html
WSGI environhttps://www.python.org/dev/peps/pep-0333/


終了コールの管理

start_exit_call(bt_handle, exit_type, display_name, identifying_properties, optional_properties=None)

指定したビジネストランザクションからカスタム終了コールを開始します。

ビジネストランザクションごとに1つのアクティブな終了コールのみが存在できます。次の終了コールを開始しようとすると、Noneを返します。

この終了コールを識別するExitCallHandleを返します。

bt_handle：BTHandle

終了コールを行うビジネストランザクションを特定します。ハンドルは start_bt() から返されます。

exit_type：整数

終了コールの種類。有効な値は以下のとおりです。

  • appd.EXIT_HTTP

  • appd.EXIT_DB

  • appd.EXIT_CACHE 

  • appd.EXIT_QUEUE

display_name：文字列

コントローラがこの終了コールを識別するために使用する名前。AppDynamics UI で終了コールを表示するために使用するラベルです。

identifying_properties：辞書

呼び出されているダウンストリーム コンポーネントを一意に識別する名前/値ペアの辞書。

これらのプロパティは、コントローラ UI でバックエンドダッシュボードの右上パネルに表示されます。

辞書のキーはプロパティ名です。値とは、プロパティ値を指します。

operation：文字列（オプション）

HTTPリクエストまたはSQLクエリのURLなど、実行中の操作を説明する文字列。

optional_properties：辞書（オプション）

この終了コールの追加プロパティを識別する名前/値ペアの辞書。コントローラ UI では、これらのプロパティはスナップショット ドリルダウン ペインの [Exit Calls and Async Activities] モーダルに表示されます。

end_exit_call(exit_call_handle, exc=None)

exit_call_handle で指定された終了コールを終了します。

exit_call_handle：ExitCallHandle

終了する終了コールを特定します。ハンドルは start_exit_call() から返されます。

exc：例外

try-except ブロックで取得した終了コールの処理中に例外が発生し、この例外を終了コールの一部として報告する場合は、例外を exc 引数として渡します。

make_correlation_header(bt_handle, exit_call_handle)

カスタム終了コールの相関ヘッダーを作成します。

インストゥルメント化された他のティアへカスタム終了コールを実行している場合、相関ヘッダーを追加することでダウンストリームのティアでも継続的なビジネストランザクションが可能になります。

ヘッダーの送信および反対側での解析、start_bt() に渡すことは任意です。

タプル（ヘッダー名、ヘッダー値）を返します。相関が無効の場合は None を返します。

bt_handle：BtHandle

ビジネストランザクションを特定するハンドル。

exit_call_handle：ExitCallHandle

終了コールを指定するハンドル。 

コンテキストマネージャ

bt(name, correlation_header=None)

ビジネストランザクションとして作業を報告するコンテキストマネージャ。BtHandle を生成します。

コード内の別の場所でトランザクションを開始および終了する必要がある場合は、start_bt() および end_bt() を使用します。

exit_call(bt_handle, exit_type, display_name, identifying_properties, optional_properties=None)

ビジネストランザクションに終了コールを追加するコンテキストマネージャ。ExitCallHandle を生成します。

コード内の別の場所で終了コールを開始および終了する必要がある場合は、start_exit_call() および end_exit_call() を使用します。

HTTPステータスコード

エラー検出の構成に関わらず、PythonエージェントAPIを使用してアプリケーションをインストゥルメント化した場合、HTTPステータスコードによりエラートランザクションが発生することはありません。