C++ SDK RAII (Resource Management Is Initialization)

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

A RAII pattern constructor for C++ applications. For a new Business Transaction, this constructor creates the business transaction object and a handle to that object. This function continuous existing transactions and adds the correlation header if one is passed.

When the business transaction object goes out of scope, the SDK automatically ends the business transaction. A business transaction object cannot be copied.

Format 

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)


Parameters 

• name: Business transaction name, passed as either a string& or  char *, depending on which constructor you choose. In the case of a continuing transaction in the current business application with a valid correlation header, the SDK uses the name from the header. 
• correlation_header: Optional correlation header, passed as either a string& or  char *, depending on which constructor you choose. 

appd::sdk::Event

This class is used to create an event in C++ and provides a convenient way of creating events. See C/C++ SDK Reference.

Format

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)

Parameters

• application_context: This string picks an agent out of multiple agents running in multi-tenant mode. If this value is empty, then the default agent is used.
• details: A map of name and value pairs. An empty map is a valid argument. The name and value associated with a detail cannot be empty; that is an error.
• event_sub_type: The string containing the subtype of the custom event. This can be used in the Controller to filter the custom events belonging to a specific subtype.
• properties: A map of name and value pairs. An empty map is a valid argument. The name and value associated with a property cannot be empty; that is an error.
• severity: This is an enum representing the severity of the event. Valid values are APPD_EVENT_SEVERITY_INFO, APPD_EVENT_SEVERITY_WARNING and APPD_EVENT_SEVERITY_ERROR.
• summary: A string giving a brief description about the event.

appd::sdk::Event::report

This method in Event class is equivalent to appd_custom_event_end() in functionality. See C/C++ SDK Reference. 

This function returns boolean value as true if the definition of the event is successful and queuing of the event (to send to the Controller) is successful. Otherwise, returns false.

Format

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

appd:sdk::ExitCall

A RAII pattern constructors for C++ applications. Constructs an ExitCall object and creates a handle to that object. You must declare a backend and assign it at least one identifying property before you use the backend to instantiate the ExitCall object.

When the ExitCall object goes out of scope, the SDK automatically ends the ExitCall. 

An ExitCall object cannot be copied.

Format 

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

Parameters 

• BT& bt: Handle to the business transaction making the exit call.
• backend: The destination backend of the exit call. Passed as either a string& or  char *, depending on which constructor you choose.

appd::sdk::Frame

Use the Frame class to enable call graphs for your C++ application. You can use the Frame class to instrument the methods that you want to track, as an alternative to calling appd_frame_begin and appd_frame_end. You must pass the following parameters into the Frame class:

Format 

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

Parameters

• bt: The BT object that owns this function call.
• frame_type: The type of the frame. When used in C++ RAII code, use APPD_FRAME_TYPE_CPP.
• class_name: The name of the class if this method is a member of the class, else NULL.
• method_name: The name of the method. You can use __FUNCTION__ or __PRETTY_FUNCTION__; any available compiler macro.
• file: The path of the source file. You can use __FILE__ or any available compiler macro.
• line_number: The line number in the source file. You can use __LINE__ or any available compiler macro.