C++ SDK Resource Management

This page describes the Resource Acquisition Is Initialization (RAII) functions defined in the C/C++ SDK to instrument C++ applications.

For C++ applications, you can use the BT and ExitCall classes to simplify your instrumentation. With these classes, you do not need to manually call appd_bt_end() and appd_exitcall_end(). When the BT or ExitCall object goes out of scope, the SDK calls its destructor and the business transaction/exit call automatically ends.

The following code example use these classes.

{
appd::sdk::BT bt("mybt");
appd::sdk::ExitCall ec(bt, "auth");
if (!make_auth_call())
{
bt.add_error(APPD_LEVEL_ERROR, "Authorization failed");
return -1;
}
issue_api_call();
}

The above code example is equivalent to this:

{
appd_bt_handle bt = appd_bt_begin("mybt", NULL);
appd_exitcall_handle ec = appd_exitcall_begin(bt, "auth");
if (!make_auth_call())
{
appd_bt_add_error(bt, APPD_LEVEL_ERROR, "Authorization failed", 0);
appd_exitcall_end(ec);
appd_bt_end(bt);
return -1;
}
issue_apI_call();
appd_exitcall_end(ec);
appd_bt_end(bt);
}

When the BT lifetime depends on the non-deterministic lifetimes of other objects, you can use a shared pointer to a BT to keep the BT alive for the lifetimes of its dependencies. In this example, the BT ends when the last reference to it ends.

{
//Initialize the BT with a shared pointer
auto bt = std::make_shared<appd::sdk::BT>("compute");
auto prod = createProducer(bt);
auto consumers = createConsumers(bt, NUM_WORKERS);
//Variable BT goes out of scope with no further references.
//BT ends automatically.
}

For managing exit calls with complex lifetimes, consider using smart pointers: std::unique_ptr<appd::sdk::ExitCall> or std::shared_ptr<appd::sdk::ExitCall>.

appd:sdk::BT

C++ アプリケーション用の RAII パターンコンストラクタ。新しいビジネストランザクションの場合、このコンストラクタはビジネス トランザクション オブジェクトとそのオブジェクトへのハンドルを作成します。この関数は既存のトランザクションを継続し、相関ヘッダーが渡された場合はそれを追加します。

ビジネス トランザクション オブジェクトが有効範囲外になると、SDK によって自動的にビジネストランザクションが終了します。ビジネス トランザクション オブジェクトはコピーできません。

形式

appd::sdk::BT(const std::string& name)
appd::sdk::BT(const std::string& name, const std::string& correlation_header)
appd::sdk::BT(const char* name, const char* correlation_header=NULL)

パラメータ

  • nameビジネストランザクション名。選択するコンストラクタに応じて、string& または char * として渡されます。有効な相関ヘッダーを含む現在のビジネスアプリケーションの継続トランザクションである場合は、ヘッダーの名前が SDK で使用されます。
  • correlation_header：オプションの相関ヘッダー。選択するコンストラクタに応じて、string& または char * として渡されます。

appd :: sdk :: Event

このクラスは、C++ でイベントを作成するために使用され、イベントを作成する便利な方法を提供します。「C/C++ SDK 参考資料」を参照してください。

形式

appd::sdk::Event::Event 
(const std::string& application_context,
enum appd_event_severity severity,
const std::string& even_sub_type,
const std::string& summary,
const std::map<std::string, std::string>& properties,
const std::map<std::string, std::string>& details)

パラメータ

  • application_context：この文字列は、マルチテナントモードで実行している複数のエージェントから 1 つのエージェントを選択します。この値が空の場合、デフォルトのエージェントが使用されます。
  • details：名前と値のペアのマップ。空のマップは有効な引数です。詳細に関連付けられた名前と値は空にできません。空にするとエラーになります。
  • event_sub_type：カスタムイベントのサブタイプを含む文字列。これは、特定のサブタイプに属するカスタムイベントをフィルタリングするためにコントローラで使用できます。
  • properties：名前と値のペアのマップ。空のマップは有効な引数です。プロパティに関連付けられた名前と値は空にできません。空にするとエラーになります。
  • severity：これは、イベントのシビラティ（重大度）を表す列挙型です。有効な値は次のとおりです。APPD_EVENT_SEVERITY_INFOAPPD_EVENT_SEVERITY_WARNINGAPPD_EVENT_SEVERITY_ERROR
  • summary：イベントの簡単な説明を含む文字列。

appd :: sdk :: Event :: report

appd_custom_event_end()Event クラスのこのメソッドは、 と同等の機能です。「C/C++ SDK 参考資料」を参照してください。

trueこの関数は、イベントの定義が成功し、（コントローラに送信する）イベントのキューイングが成功した場合は、ブール値を として返します。そうでない場合は、false を返します。

形式

appd::sdk::Event event(<arguments>); bool status = event.report();

appd:sdk::ExitCall

C++ アプリケーション用の RAII パターンコンストラクタ。ExitCall オブジェクトが作成され、そのオブジェクトへのハンドルが作成されます。バックエンドを宣言して、それを使用して ExitCall オブジェクトをインスタンス化する前に、少なくとも 1 つの識別プロパティに割り当てる必要があります。

ExitCall オブジェクトが有効範囲外になると、SDK によって自動的に ExitCall が終了します。

ExitCallオブジェクトはコピーできません。

形式

appd::sdk::ExitCall(BT& bt, const char* backend)
appd::sdk::ExitCall(BT& bt, const std::string& backend)

パラメータ

  • BT& bt終了コールを行うビジネストランザクションへのハンドル。
  • backend： 終了コールの宛先バックエンド。選択するコンストラクタに応じて、string& または char * として渡されます。

appd :: sdk :: Frame

フレームクラスを使用して、ご使用の C++ アプリケーションのコールグラフを有効にします。appd_frame_begin および appd_frame_end を呼び出す代わりに、このフレームクラスを使用して、追跡対象のメソッドをインストゥルメント化できます。次のパラメータをフレームクラスに渡す必要があります。

形式

Frame(BT& bt, appd_frame_type frame_type, const char* class_name, const char* method_name, const char* file, unsigned int line_number)

パラメータ

  • bt：この関数呼び出しを所有する BT オブジェクト。
  • frame_type：フレームのタイプ。C++ RAII コードで使用する場合は、APPD_FRAME_TYPE_CPP を使用します。
  • class_name：このメソッドがクラスのメンバーである場合はクラスの名前。それ以外の場合は NULL。
  • method_name：メソッドの名前。__FUNCTION__ または任意の使用可能なコンパイラマクロを使用できます。__PRETTY_FUNCTION__
  • file：ソースファイルのパス。__FILE__ または任意の使用可能なコンパイラマクロを使用できます。
  • line_number：ソースファイルの行番号。__LINE__ または任意の使用可能なコンパイラマクロを使用できます。