AppDynamics C/C++ SDK  21.3
Reference documentation for the C/C++ SDK.
appdynamics.h File Reference
#include <string>
#include <memory>
#include <map>

Go to the source code of this file.

Classes

class  appd::sdk::HandleWrapper< HandleT >
 
class  appd::sdk::BT
 
class  appd::sdk::ExitCall
 
class  appd::sdk::Frame
 
class  appd::sdk::CallGraphElement
 
class  appd::sdk::CallGraph
 
class  appd::sdk::Event
 

Namespaces

 appd
 
 appd::sdk
 

Macros

#define APPD_API   __attribute__((visibility("default")))
 
#define APPD_BACKEND_HTTP   "HTTP"
 
#define APPD_BACKEND_DB   "DB"
 
#define APPD_BACKEND_CACHE   "CACHE"
 
#define APPD_BACKEND_RABBITMQ   "RABBITMQ"
 
#define APPD_BACKEND_WEBSERVICE   "WEB_SERVICE"
 
#define APPD_BACKEND_JMS   "JMS"
 
#define APPD_BACKEND_WEBSPHEREMQ   "WEBSPHERE_MQ"
 
#define APPD_CORRELATION_HEADER_NAME   "singularityheader"
 
#define APPD_FUNCTION_NAME   "unknown"
 
#define APPD_AUTO_FRAME(bt)
 

Typedefs

typedef void * appd_bt_handle
 
typedef void * appd_exitcall_handle
 
typedef void * appd_frame_handle
 
typedef void * appd_event_handle
 

Enumerations

enum  appd_config_log_level {
  APPD_LOG_LEVEL_TRACE, APPD_LOG_LEVEL_DEBUG, APPD_LOG_LEVEL_INFO, APPD_LOG_LEVEL_WARN, APPD_LOG_LEVEL_ERROR,
  APPD_LOG_LEVEL_FATAL
}
 
enum  appd_error_level { APPD_LEVEL_NOTICE, APPD_LEVEL_WARNING, APPD_LEVEL_ERROR }
 
enum  appd_time_rollup_type { APPD_TIMEROLLUP_TYPE_AVERAGE = 1, APPD_TIMEROLLUP_TYPE_SUM, APPD_TIMEROLLUP_TYPE_CURRENT }
 
enum  appd_cluster_rollup_type { APPD_CLUSTERROLLUP_TYPE_INDIVIDUAL = 1, APPD_CLUSTERROLLUP_TYPE_COLLECTIVE }
 
enum  appd_hole_handling_type { APPD_HOLEHANDLING_TYPE_RATE_COUNTER = 1, APPD_HOLEHANDLING_TYPE_REGULAR_COUNTER }
 
enum  appd_frame_type { APPD_FRAME_TYPE_CPP = 1 }
 
enum  appd_event_severity { APPD_EVENT_SEVERITY_INFO, APPD_EVENT_SEVERITY_WARNING, APPD_EVENT_SEVERITY_ERROR }
 

Functions

APPD_API struct appd_config * appd_config_init ()
 
APPD_API struct appd_context_config * appd_context_config_init (const char *context)
 
APPD_API void appd_config_set_app_name (struct appd_config *cfg, const char *app)
 
APPD_API void appd_context_config_set_app_name (struct appd_context_config *context_cfg, const char *app)
 
APPD_API void appd_config_set_tier_name (struct appd_config *cfg, const char *tier)
 
APPD_API void appd_context_config_set_tier_name (struct appd_context_config *context_cfg, const char *tier)
 
APPD_API void appd_config_set_node_name (struct appd_config *cfg, const char *node)
 
APPD_API void appd_context_config_set_node_name (struct appd_context_config *context_cfg, const char *node)
 
APPD_API void appd_config_set_controller_host (struct appd_config *cfg, const char *host)
 
APPD_API void appd_context_config_set_controller_host (struct appd_context_config *context_cfg, const char *host)
 
APPD_API void appd_config_set_controller_port (struct appd_config *cfg, const unsigned short port)
 
APPD_API void appd_context_config_set_controller_port (struct appd_context_config *context_cfg, const unsigned short port)
 
APPD_API void appd_config_set_controller_account (struct appd_config *cfg, const char *acct)
 
APPD_API void appd_context_config_set_controller_account (struct appd_context_config *context_cfg, const char *acct)
 
APPD_API void appd_config_set_controller_access_key (struct appd_config *cfg, const char *key)
 
APPD_API void appd_context_config_set_controller_access_key (struct appd_context_config *context_cfg, const char *key)
 
APPD_API void appd_config_set_controller_use_ssl (struct appd_config *cfg, const unsigned int ssl)
 
APPD_API void appd_context_config_set_controller_use_ssl (struct appd_context_config *context_cfg, unsigned int ssl)
 
APPD_API void appd_config_set_controller_http_proxy_host (struct appd_config *cfg, const char *host)
 
APPD_API void appd_context_config_set_controller_http_proxy_host (struct appd_context_config *context_cfg, const char *host)
 
APPD_API void appd_config_set_controller_http_proxy_port (struct appd_config *cfg, const unsigned short port)
 
APPD_API void appd_context_config_set_controller_http_proxy_port (struct appd_context_config *context_cfg, const unsigned short port)
 
APPD_API void appd_config_set_controller_http_proxy_username (struct appd_config *cfg, const char *user)
 
APPD_API void appd_context_config_set_controller_http_proxy_username (struct appd_context_config *context_cfg, const char *user)
 
APPD_API void appd_config_set_controller_http_proxy_password (struct appd_config *cfg, const char *pwd)
 
APPD_API void appd_context_config_set_controller_http_proxy_password (struct appd_context_config *context_cfg, const char *pwd)
 
APPD_API void appd_config_set_controller_http_proxy_password_file (struct appd_config *cfg, const char *file)
 
APPD_API void appd_context_config_set_controller_http_proxy_password_file (struct appd_context_config *context_cfg, const char *file)
 
APPD_API void appd_config_set_controller_certificate_file (struct appd_config *cfg, const char *file)
 
APPD_API void appd_context_config_set_controller_certificate_file (struct appd_context_config *context_cfg, const char *file)
 
APPD_API void appd_config_set_controller_certificate_dir (struct appd_config *cfg, const char *dir)
 
APPD_API void appd_context_config_set_controller_certificate_dir (struct appd_context_config *context_cfg, const char *dir)
 
APPD_API void appd_config_set_analytics_host (struct appd_config *cfg, const char *host)
 
APPD_API void appd_config_set_analytics_port (struct appd_config *cfg, const unsigned short port)
 
APPD_API void appd_config_set_analytics_use_ssl (struct appd_config *cfg, const unsigned short ssl)
 
APPD_API void appd_config_set_analytics_enabled (struct appd_config *cfg, const unsigned short enable)
 
APPD_API void appd_config_set_logging_min_level (struct appd_config *cfg, enum appd_config_log_level lvl)
 
APPD_API void appd_config_set_logging_log_dir (struct appd_config *cfg, const char *dir)
 
APPD_API void appd_config_set_logging_max_num_files (struct appd_config *cfg, const unsigned int num)
 
APPD_API void appd_config_set_logging_max_file_size_bytes (struct appd_config *cfg, const unsigned int size)
 
APPD_API void appd_config_set_init_timeout_ms (struct appd_config *cfg, const int time)
 
APPD_API void appd_config_set_flush_metrics_on_shutdown (struct appd_config *cfg, int enable)
 
APPD_API void appd_config_getenv (struct appd_config *cfg, const char *prefix)
 
APPD_API int appd_sdk_init (const struct appd_config *config)
 
APPD_API int appd_sdk_add_app_context (struct appd_context_config *context_cfg)
 
APPD_API void appd_backend_declare (const char *type, const char *unregistered_name)
 
APPD_API int appd_backend_set_identifying_property (const char *backend, const char *key, const char *value)
 
APPD_API int appd_backend_prevent_agent_resolution (const char *backend)
 
APPD_API int appd_backend_add (const char *backend)
 
APPD_API appd_bt_handle appd_bt_begin (const char *name, const char *correlation_header)
 
APPD_API appd_bt_handle appd_bt_begin_with_app_context (const char *context, const char *name, const char *correlation_header)
 
APPD_API void appd_bt_store (appd_bt_handle bt, const char *guid)
 
APPD_API appd_bt_handle appd_bt_get (const char *guid)
 
APPD_API void appd_bt_add_error (appd_bt_handle bt, enum appd_error_level level, const char *message, int mark_bt_as_error)
 
APPD_API char appd_bt_is_snapshotting (appd_bt_handle bt)
 
APPD_API void appd_bt_add_user_data (appd_bt_handle bt, const char *key, const char *value)
 
APPD_API void appd_bt_set_url (appd_bt_handle bt, const char *url)
 
APPD_API void appd_bt_end (appd_bt_handle bt)
 
APPD_API appd_exitcall_handle appd_exitcall_begin (appd_bt_handle bt, const char *backend)
 
APPD_API void appd_exitcall_store (appd_exitcall_handle exitcall, const char *guid)
 
APPD_API appd_exitcall_handle appd_exitcall_get (const char *guid)
 
APPD_API int appd_exitcall_set_details (appd_exitcall_handle exitcall, const char *details)
 
APPD_API const char * appd_exitcall_get_correlation_header (appd_exitcall_handle exitcall)
 
APPD_API void appd_exitcall_add_error (appd_exitcall_handle exitcall, enum appd_error_level level, const char *message, int mark_bt_as_error)
 
APPD_API void appd_exitcall_end (appd_exitcall_handle exitcall)
 
APPD_API void appd_custom_metric_add (const char *application_context, const char *metric_path, enum appd_time_rollup_type time_rollup_type, enum appd_cluster_rollup_type cluster_rollup_type, enum appd_hole_handling_type hole_handling_type)
 
APPD_API void appd_custom_metric_report (const char *application_context, const char *metric_path, long value)
 
APPD_API appd_frame_handle appd_frame_begin (appd_bt_handle bt, enum appd_frame_type frame_type, const char *class_name, const char *method_name, const char *file, int line_number)
 
APPD_API void appd_frame_end (appd_bt_handle bt, appd_frame_handle frame)
 
APPD_API const char * appd_eum_get_cookie (appd_bt_handle bt, int https, int short_form, const char *referrer_url, const char *path)
 
APPD_API int appd_bt_enable_snapshot (appd_bt_handle bt)
 
APPD_API appd_event_handle appd_custom_event_start (const char *application_context, enum appd_event_severity severity, const char *event_sub_type, const char *summary)
 
APPD_API int appd_custom_event_add_property (appd_event_handle event_handle, const char *property_name, const char *property_value)
 
APPD_API int appd_custom_event_add_detail (appd_event_handle event_handle, const char *detail_name, const char *detail_value)
 
APPD_API int appd_custom_event_end (appd_event_handle event_handle)
 
APPD_API void appd_sdk_term ()
 
APPD_API appd::sdk::CallGraphElementappd_construct_callgraph_element (const appd::sdk::CallGraph *callgraph, const std::string &class_name, const std::string &method_name, const std::string &file_path, int32_t line_number, int32_t time_msec, appd_frame_type frame_type)
 
APPD_API bool appd_callgraph_add_to_snapshot (const appd::sdk::CallGraph *callgraph)
 

Macro Definition Documentation

◆ APPD_API

#define APPD_API   __attribute__((visibility("default")))

◆ APPD_AUTO_FRAME

#define APPD_AUTO_FRAME (   bt)
Value:
appd::sdk::Frame __appd_f##__COUNTER__((bt), APPD_FRAME_TYPE_CPP, nullptr, APPD_FUNCTION_NAME, \
__FILE__, __LINE__)

◆ APPD_BACKEND_CACHE

#define APPD_BACKEND_CACHE   "CACHE"

Cache Definition.

◆ APPD_BACKEND_DB

#define APPD_BACKEND_DB   "DB"

DB Definition.

◆ APPD_BACKEND_HTTP

#define APPD_BACKEND_HTTP   "HTTP"

Built-in exit call types. HTTP Definition.

◆ APPD_BACKEND_JMS

#define APPD_BACKEND_JMS   "JMS"

JMS Definition.

◆ APPD_BACKEND_RABBITMQ

#define APPD_BACKEND_RABBITMQ   "RABBITMQ"

RabbitMQ Definition.

◆ APPD_BACKEND_WEBSERVICE

#define APPD_BACKEND_WEBSERVICE   "WEB_SERVICE"

Web_Service Definition.

◆ APPD_BACKEND_WEBSPHEREMQ

#define APPD_BACKEND_WEBSPHEREMQ   "WEBSPHERE_MQ"

WebSphere Definition.

◆ APPD_CORRELATION_HEADER_NAME

#define APPD_CORRELATION_HEADER_NAME   "singularityheader"

The default name of the correlation header.

Other AppDynamics agents perform automatic correlation for certain types of entry and exit points by looking for a correlation header in the payload with this name.

Upstream Correlation

When your SDK instrumented process receives a continuing transaction from an upstream agent that supports automatic correlation, extract the header named APPD_CORRELATION_HEADER_NAME from the incoming payload and pass it to appd_bt_begin():

const char* hdr = http_get_header(req, APPD_CORRELATION_HEADER_NAME);
appd_bt_handle bt = appd_bt_begin("fraud detection", hdr);

If the header retrieved by the third-party http_get_header() function valid, the BT started on the second line will be a continuation of the business transaction started by the upstream service.

Downstream Correlation

If you are making an exit call where a downstream agent supports automatic correlation, inject a header named APPD_CORRELATION_HEADER_NAME into the outgoing payload. The value of the header is retrieved using the appd_exitcall_get_correlation_header() function:

appd_exitcall_handle inventory = appd_exitcall_begin(bt, "inventory");
const char* hdr = appd_exitcall_get_correlation_header(inventory);
http_request req;
http_init(&req, HTTP_POST, "https://inventory/holds/%s", sku);
http_set_header(&req, APPD_CORRELATION_HEADER_NAME, hdr);
http_perform(&req);

In this example, the hypothetical third-party http_xxx functions are used to make an HTTP POST request with an HTTP header containing the correlation header as retrieved by appd_exitcall_get_correlation_header(). The header is given the name APPD_CORRELATION_HEADER_NAME. A downstream agent that supports automatic correlation for HTTP entry points will automatically extract the correlation header and perform distributed transaction tracing.

◆ APPD_FUNCTION_NAME

#define APPD_FUNCTION_NAME   "unknown"

Typedef Documentation

◆ appd_bt_handle

typedef void* appd_bt_handle

BT Handle is an opaque handle that will be returned when creating a Business Transaction. The handle is used by subsequent business transaction API calls, and must be passed as the parameter to the appd_bt_end() call when completing the transaction. See appd_bt_begin() for invocation usage.

NOTE: The user should not de-reference the handle, nor make any assumptions about its contents. AppDynamics reserves the right to modify its meaning at a later date.

◆ appd_event_handle

typedef void* appd_event_handle

Event Handle is an opaque handle that will be returned when creating a Custom Event. The handle is used by subsequent custom event API calls, and must be passed as the parameter to the appd_custom_event_end() call when completing the transaction.

NOTE: The user should not de-reference the handle, nor make any assumptions about its contents. AppDynamics reserves the right to modify its meaning at a later date.

◆ appd_exitcall_handle

typedef void* appd_exitcall_handle

Exit Call Handle is an opaque handle that will be returned when creating an Exit Call. The handle is used by subsequent exit call API calls, and must be passed as the parameter to the appd_exitcall_end() call when completing the exit call.

NOTE: The user should not de-reference the handle, nor make any assumptions about its contents. AppDynamics reserves the right to modify its meaning at a later date.

◆ appd_frame_handle

typedef void* appd_frame_handle

Frame Handle is an opaque handle that will be returned when creating a C/C++ stack frame call. The handle is used by subsequent stack frame API calls, and must be passed as the parameter to the appd_frame_end() call when completing the transaction.

NOTE: The user should not de-reference the handle, nor make any assumptions about its contents. AppDynamics reserves the right to modify its meaning at a later date.

Enumeration Type Documentation

◆ appd_cluster_rollup_type

Enumerator
APPD_CLUSTERROLLUP_TYPE_INDIVIDUAL 

Roll-up the value individually for each member of the cluster.

APPD_CLUSTERROLLUP_TYPE_COLLECTIVE 

Roll-up the value across all members of the cluster.

◆ appd_config_log_level

The SDK Logging Level sets the logging level for SDK. See appd_config_set_logging_min_level() for more details. The default is APPD_LOG_LEVEL_INFO, which should provide adequate logging to determine the cause of most issues. Setting the level higher may result in excessive disk consumption, and should be avoided unless actively diagnosing an issue. It is possible to turn off all but the most extreme debugging (effectively off) by setting it to APPD_LOG_LEVEL_FATAL, although one may also wish to constrict the number of log files created, and/or direct them to /dev/null.

See also appd_config_set_logging_log_dir(), appd_config_set_logging_max_num_files(), appd_config_set_logging_max_file_size_bytes()

Enumerator
APPD_LOG_LEVEL_TRACE 

Logs everything, including debugging and trace information.

APPD_LOG_LEVEL_DEBUG 

Logs normally, but includes additional debugging information.

APPD_LOG_LEVEL_INFO 

Logs normally (the default setting).

APPD_LOG_LEVEL_WARN 

Logs warnings only or higher.

APPD_LOG_LEVEL_ERROR 

Logs errors only.

APPD_LOG_LEVEL_FATAL 

Logs fatal errors only, otherwise it doesn't log anything. Effectively disables logging.

◆ appd_error_level

Error levels that pass to appd_bt_add_error() and appd_exitcall_add_error().

Enumerator
APPD_LEVEL_NOTICE 
APPD_LEVEL_WARNING 
APPD_LEVEL_ERROR 

◆ appd_event_severity

Represents event severity which is passed to appd_custom_event_start().

Enumerator
APPD_EVENT_SEVERITY_INFO 
APPD_EVENT_SEVERITY_WARNING 

Info

APPD_EVENT_SEVERITY_ERROR 

Warning Error

◆ appd_frame_type

This is the language of the current frame (will be expanded in the future).

Enumerator
APPD_FRAME_TYPE_CPP 

Default C/C++ Frame

◆ appd_hole_handling_type

Enumerator
APPD_HOLEHANDLING_TYPE_RATE_COUNTER 

hole handling: rate counter.

APPD_HOLEHANDLING_TYPE_REGULAR_COUNTER 

hole handling: regular counter.

◆ appd_time_rollup_type

Enumerator
APPD_TIMEROLLUP_TYPE_AVERAGE 

Compute the average value of the metric over time.

APPD_TIMEROLLUP_TYPE_SUM 

Compute the sum of the value of the metric over time.

APPD_TIMEROLLUP_TYPE_CURRENT 

Report the current value of the metric.

Function Documentation

◆ appd_backend_add()

APPD_API int appd_backend_add ( const char *  backend)

Add a declared backend.

Parameters
backend
Returns
Zero on success, otherwise non-zero. If non-zero is returned, a message is logged describing the error. The most common error is that a backend with the same identifying properties has already been added.

◆ appd_backend_declare()

APPD_API void appd_backend_declare ( const char *  type,
const char *  unregistered_name 
)

Declare the existence of a backend.

Parameters
typeOne of the APPD_BACKEND_xxx constants or any string.
unregistered_nameThe name to give the backend if it has not been registered with the Controller.

◆ appd_backend_prevent_agent_resolution()

APPD_API int appd_backend_prevent_agent_resolution ( const char *  backend)

Call to prevent a downstream agent as resolving as this backend. This must be called before appd_backend_add().

Normally, if an agent picks up a correlation header for an unresolved backend, it will resolve itself as that backend. This is usually the desired behavior.

However, if the backend is actually an uninstrumented tier that is passing through the correlation header (for example, a message queue or proxy), then you may wish the backend to show up distinct from the tier that it routes to. If you call this function, correlation headers generated for exit calls to this backend in the SDK will instruct downstream agents to report as distinct from the backend.

For example: if you have Tier A talking to uninstrumented Backend B which routes to instrumented Tier C, if you do NOT call this function, the flow map will be A --> C. If you DO call this function, the flow map will be A --> B --> C.

Parameters
backend
Returns
Zero on success, otherwise non-zero. If non-zero is returned, a message is logged describing the error.

◆ appd_backend_set_identifying_property()

APPD_API int appd_backend_set_identifying_property ( const char *  backend,
const char *  key,
const char *  value 
)

Set an identifying property of a backend. This must be called with a valid key before appd_backend_add() for well known backend types.

Parameters
backend
key
value
Returns
Zero on success, otherwise non-zero. If non-zero is returned, a message is logged describing the error.

◆ appd_bt_add_error()

APPD_API void appd_bt_add_error ( appd_bt_handle  bt,
enum appd_error_level  level,
const char *  message,
int  mark_bt_as_error 
)

Add an error to a business transaction.

Errors are reported as part of the business transaction. However, you can add an error without marking the business transaction as an error (e.g., for non-fatal errors).

Parameters
btThe business transaction to add the error to.
levelThe error level. One of the APPD_LEVEL_xxx constants.
messageThe error message.
mark_bt_as_errorIf true, the business transaction is marked as an error. Otherwise, the error is added but the transaction is not marked as an error.
Returns
void

◆ appd_bt_add_user_data()

APPD_API void appd_bt_add_user_data ( appd_bt_handle  bt,
const char *  key,
const char *  value 
)

Add user data to a snapshot (if one is being taken) or for Analytics (if Analytics is enabled for this business transaction).

Data should be either 7-bit ASCII or UTF-8.

It is safe to call this function when a snapshot is not occurring or Analytics is not enabled.

When the data is for snapshotting only and if extracting the data to pass to this function is expensive, you can use appd_bt_is_snapshotting to check if the business transaction is snapshotting before extracting the data and calling this function.

Parameters
btThe business transaction to add the user data to if is taking a snapshot.
keyThe name of the user data to add to the snapshot as 7-bit ASCII or UTF-8.
valueThe value of the user data to add to the snapshot as 7-bit ASCII or UTF-8.
Returns
void

◆ appd_bt_begin()

APPD_API appd_bt_handle appd_bt_begin ( const char *  name,
const char *  correlation_header 
)

This function starts a business transaction. The function begins a business transaction with the supplied name. Do not call the function again until the business transaction in question is complete.

When you generate the business transaction name, do not exceed more than 50 unique names (the default limit for any given tier/node) if more than 200 unique names have been generated within the application (the default limit).

Parameters
nameThe name for the business transaction.
correlation_headerA correlation string passed from an upstream node/tier if this is a continuing transaction, else NULL.
Returns
An opaque handle for the business transaction that was started.

◆ appd_bt_begin_with_app_context()

APPD_API appd_bt_handle appd_bt_begin_with_app_context ( const char *  context,
const char *  name,
const char *  correlation_header 
)

Create a business transaction for an alternate context. The context is the null application terminated application context name string established by the appd_context_config_init() call.

Parameters
contextThe application context name string for the alternate application context.
nameThe name for the business transaction.
correlation_headerA correlation header if this is a continuing transaction, else NULL.
Returns
An opaque handle for the business transaction that was started.

◆ appd_bt_enable_snapshot()

APPD_API int appd_bt_enable_snapshot ( appd_bt_handle  bt)

Manually enable snapshot for the business transaction.

Parameters
btHandle for the relevant business transaction.
Returns
Returns non-zero if snapshot is enabled. Otherwise a zero value is returned.

◆ appd_bt_end()

APPD_API void appd_bt_end ( appd_bt_handle  bt)

End the given business transaction.

Parameters
btThe handle to the business transaction to end.
Returns
void

◆ appd_bt_get()

APPD_API appd_bt_handle appd_bt_get ( const char *  guid)

Get a BT handle associated with the given GUID by appd_bt_store.

Parameters
guidThe globally unique identifier that was passed to appd_bt_store.
Returns
The BT handle associated with the given GUID. If no BT handle was associated with the GUID, or if the BT ended prior to getting it, a warning is logged and the returned handle may be safely used in other API functions but will cause these functions to immediately return without doing anything.

◆ appd_bt_is_snapshotting()

APPD_API char appd_bt_is_snapshotting ( appd_bt_handle  bt)

Return non-zero if the business transaction is taking a snapshot.

Parameters
btThe business transaction to check for snapshotting.
Returns
char indicating snapshot status Non-zero if the given business transaction is taking a snapshot. Otherwise, zero.

◆ appd_bt_set_url()

APPD_API void appd_bt_set_url ( appd_bt_handle  bt,
const char *  url 
)

Set URL for a snapshot (if one is being taken).

URL is set for a snapshot if one is occurring. Data should be either 7-bit ASCII or UTF-8.

It is safe to call this function when a snapshot is not occurring. When the given business transcation is NOT snapshotting, this function immediately returns. However, if extracting the data to pass to this function is expensive, you can use appd_bt_is_snapshotting to check if the business transaction is snapshotting before extracting the data and calling this function.

Parameters
btThe business transaction to add the user data to, if it is taking a snapshot.
urlThe value of the URL for the snapshot as 7-bit ASCII or UTF-8.
Returns
void

◆ appd_bt_store()

APPD_API void appd_bt_store ( appd_bt_handle  bt,
const char *  guid 
)

Store a BT handle for retrieval with appd_bt_get.

This function allows you to store a BT in a global registry to retrieve later. This is convenient when you need to start and end a BT in separate places, and it is difficult to pass the handle to the BT through the parts of the code that need it.

When the BT is ended, the handle is removed from the global registry.

Example

int begin_transaction(uint64_t txid, uint64_t sku, float price)
{
    appd_bt_handle bt = appd_bt_begin("payment-processing", NULL);
    appd_bt_store(bt, std::to_string(txid).c_str());
    // ...
}
Parameters
btThe business transaction to store.
guidA globally unique identifier to associate with the given business transaction.

◆ appd_callgraph_add_to_snapshot()

APPD_API bool appd_callgraph_add_to_snapshot ( const appd::sdk::CallGraph callgraph)

◆ appd_config_getenv()

APPD_API void appd_config_getenv ( struct appd_config *  cfg,
const char *  prefix 
)

Read configuration from environment variables.

Environment variables are named like <prefix>_<base> where <base> is:

  • APP_NAME for appd_config.app_name
  • TIER_NAME for appd_config.tier_name
  • NODE_NAME for appd_config.node_name
  • CONTROLLER_HOST for appd_config.controller.host
  • CONTROLLER_PORT for appd_config.controller.port
  • ANALYTICS_HOST for appd_condif.analytics_agent.host
  • ANALYTICS_PORT for appd_condif.analytics_agent.port
  • CONTROLLER_ACCOUNT for appd_config.controller.account
  • CONTROLLER_ACCESS_KEY for appd_config.controller.access_key
  • CONTROLLER_USE_SSL for appd_config.controller.use_ssl
  • CONTROLLER_HTTP_PROXY_HOST for appd_config.http_proxy.host
  • CONTROLLER_HTTP_PROXY_PORT for appd_config.http_proxy.port
  • CONTROLLER_HTTP_PROXY_USERNAME for appd_config.http_proxy.username
  • CONTROLLER_HTTP_PROXY_PASSWORD_FILE for appd_config.http_proxy.password_file
  • INIT_TIMEOUT_MS for appd_config.init_timeout_ms
  • FLUSH_METRICS_ON_SHUTDOWN for appd_config_set_flush_metrics_on_shutdown

The <prefix> is the value of the prefix argument to this function. If the passed prefix is NULL or empty, then "`APPD_SDK`" is used.

For the CONTROLLER_USE_SSL environment variable, values of "off", "0", "f", and "false" (case insensitive) set use_ssl to false. Any other value sets use_ssl to true.

Environment variables are not read by default. Call this function to configure the SDK via environment variables.

There is no built-in way to add multiple app contexts via environment variables. You will have to build your own way of doing that.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
prefixThe null terminated string to prepend to the environment variables list above.

◆ appd_config_init()

APPD_API struct appd_config* appd_config_init ( )

Creates an empty configuration structure and returns a pointer to the initialized configuration object. Do not free this structure, it will be released when appd_sdk_term() is called.

Call this function and set values in it with the following methods:

At a minimum, the host, port, SSL, account, access key, application name, tier name, and node name must all be set for the SDK to properly connect to the Controller. Once the structure contains the correct configuration settings, call appd_sdk_init() to initialize the SDK.

Use the appd_sdk_init() function to initialize the default context within the SDK.

NOTE: Do not call appd_config_init() a second time, as it will reinitialize the structure and zero out any previous configuration settings.

Returns
returns a pointer to an initialized appd_config structure.

◆ appd_config_set_analytics_enabled()

APPD_API void appd_config_set_analytics_enabled ( struct appd_config *  cfg,
const unsigned short  enable 
)

Set the enable/disable flag for the Analytics Agent.

Parameters
cfgA pointer to the default application context structure crerated by appd_config_init().
enableIf non-zero, then the Analytics Agent is enabled. If zero, then the Analytics Agent is disabled (default behavior).
Returns
void

◆ appd_config_set_analytics_host()

APPD_API void appd_config_set_analytics_host ( struct appd_config *  cfg,
const char *  host 
)

Host for the Analytics Agent. Defaults to "localhost".

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
hostURL The host URL.

◆ appd_config_set_analytics_port()

APPD_API void appd_config_set_analytics_port ( struct appd_config *  cfg,
const unsigned short  port 
)

Port on which the Analytics Agent is listening. Defaults to 9090.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
portAn unsigned short that contains the Analytics port.
Returns
void

◆ appd_config_set_analytics_use_ssl()

APPD_API void appd_config_set_analytics_use_ssl ( struct appd_config *  cfg,
const unsigned short  ssl 
)

Sets the flag that indicates whether or not the Analytics Host connection uses SSL. By default, SSL is deactivated.

Parameters
sslIf non-zero, then SSL will activate. If zero, then SSL will not activate (by default).
Returns
void

◆ appd_config_set_app_name()

APPD_API void appd_config_set_app_name ( struct appd_config *  cfg,
const char *  app 
)

The default application name sets the default application context's application name. This will be used for all the (default) application context metrics.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
appA NULL terminated string that contains the application name.
Returns
void

◆ appd_config_set_controller_access_key()

APPD_API void appd_config_set_controller_access_key ( struct appd_config *  cfg,
const char *  key 
)

Sets the default application context's Controller access key. This value should match the key shown in the account tab of the license page off the Controller's Gear icon.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
keyA NULL terminated string that describes the access key for this context.
Returns
void

◆ appd_config_set_controller_account()

APPD_API void appd_config_set_controller_account ( struct appd_config *  cfg,
const char *  acct 
)

Sets the default business transaction's Controller account name.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
acctA NULL terminated string that describes the account name.
Returns
void

◆ appd_config_set_controller_certificate_dir()

APPD_API void appd_config_set_controller_certificate_dir ( struct appd_config *  cfg,
const char *  dir 
)

CA certificate directory.

Set this if you have multiple certificate files located in a single directory.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
dirA null terminated string that contains the certificate directory.
Returns
void

◆ appd_config_set_controller_certificate_file()

APPD_API void appd_config_set_controller_certificate_file ( struct appd_config *  cfg,
const char *  file 
)

CA certificate file (full path).

Defaults to the included ca-bundle.crt file. Set this to use your own certificate file.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
fileA null terminated string that contains the certificate file.
Returns
void

◆ appd_config_set_controller_host()

APPD_API void appd_config_set_controller_host ( struct appd_config *  cfg,
const char *  host 
)

Sets the default application context's Controller host name. This will be used for all the default application context metrics.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
hostA NULL terminated string that contains the host URL string or IPADDR.
Returns
void

◆ appd_config_set_controller_http_proxy_host()

APPD_API void appd_config_set_controller_http_proxy_host ( struct appd_config *  cfg,
const char *  host 
)

(Optional) The HTTP proxy host name if you are using an HTTP proxy to talk to the Controller. The HTTP proxy config options are optional and only necessary if a proxy is required to connect to the Controller.

Parameters
cfgA pointer to the deafult application context structure crerated by appd_config_init().
hostThe NULL terminated string that contains the HTTP proxy host name.
Returns
void

◆ appd_config_set_controller_http_proxy_password()

APPD_API void appd_config_set_controller_http_proxy_password ( struct appd_config *  cfg,
const char *  pwd 
)

(Optional) The password to connect to the HTTP proxy with. The HTTP proxy config options are optional, and only necessary if a proxy is required to connect the SDK host to the Controller.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
pwdA null terminated string that contains the password used to connect to the HTTP proxy.
Returns
void

◆ appd_config_set_controller_http_proxy_password_file()

APPD_API void appd_config_set_controller_http_proxy_password_file ( struct appd_config *  cfg,
const char *  file 
)

(Optional) The file that contains the password to connect to the HTTP proxy with. The HTTP proxy config options are optional, and only necessary if a proxy is required to connect the SDK host to the Controller.

Parameters
cfgA pointer to the default application context structure created by appd_config_init()
fileA null terminated string that contains the password file. The file is written in clear text.
Returns
void

◆ appd_config_set_controller_http_proxy_port()

APPD_API void appd_config_set_controller_http_proxy_port ( struct appd_config *  cfg,
const unsigned short  port 
)

(Optional) The port number of the HTTP proxy. (Default: 80) The HTTP proxy config options are optional, and only necessary if a proxy is required to connect the SDK host to the Controller.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
portAn unsigned short that contains the HTTP proxy host port.
Returns
void

◆ appd_config_set_controller_http_proxy_username()

APPD_API void appd_config_set_controller_http_proxy_username ( struct appd_config *  cfg,
const char *  user 
)

(Optional) Username to connect to the HTTP proxy with. The HTTP proxy config options are optional, and only necessary if a proxy is required to connect the SDK host to the Controller.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
userA null terminated string that contains the user name.
Returns
void

◆ appd_config_set_controller_port()

APPD_API void appd_config_set_controller_port ( struct appd_config *  cfg,
const unsigned short  port 
)

Sets the port on which the default application context the Controller is expected to be listening.

If not specifed, defaults to 80 when use_ssl is false and 443 when use_ssl is true.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
portAn unsigned short that contains the port number.
Returns
void

◆ appd_config_set_controller_use_ssl()

APPD_API void appd_config_set_controller_use_ssl ( struct appd_config *  cfg,
const unsigned int  ssl 
)

Flag that specifies if SSL should be used to talk to the Controller.

Set to a non-zero integer for true. Set to the integer zero for false.

This value must be non-zero for SaaS Controllers.

Parameters
cfgA pointer to the alternate application context structure created by appd_config_init().
sslIf zero, do not use SSL, if non-zero, use SSL.
Returns
void

◆ appd_config_set_flush_metrics_on_shutdown()

APPD_API void appd_config_set_flush_metrics_on_shutdown ( struct appd_config *  cfg,
int  enable 
)

This function controls the behavior of the SDK shutdown when the appd_sdk_term() call is made. By default, any metrics not reported to the Controller in the minute before shutdown will be lost. Enabling flush_metrics_on_shutdown will cause appd_sdk_term() to block for up to one minute to allow the reporting of the final minute's metrics that have been captured but not yet reported. This call applies to all application contexts.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
enableIf non-zero, will enable flushing. Zero will disable flushing (the default behavior).
Returns
void

◆ appd_config_set_init_timeout_ms()

APPD_API void appd_config_set_init_timeout_ms ( struct appd_config *  cfg,
const int  time 
)

appd_sdk_init relies on the Controller configuration to start business transactions. This is an asynchronous action so that appd_sdk_init does not block your program. This appd_config field allows you to instruct appd_sdk_init to wait for up to init_timeout_ms milliseconds until it has received the Controller configuration and is ready to capture business transactions. If a valid configurate is not received in that amount of time, the function will return and allow normal application processing to proceed, but no metrics will be recorded. The SDK will continue to (asynchronously) attempt to retrieve a configuration. Once it does, the SDK will begin recording metrics.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
timeThe time (in milliseconds) to wait for the Controller configuration before proceeding. X: Wait up to x milliseconds for the Controller configuration. 0: Do not wait for the Controller configuration. -1: Wait indefinitely until the Controller configuration is received by the agent.
Returns
void

◆ appd_config_set_logging_log_dir()

APPD_API void appd_config_set_logging_log_dir ( struct appd_config *  cfg,
const char *  dir 
)

The directory to log to. If not set, defaults to "/tmp/appd". The process running the SDK must have permissions to create this directory (if it doesn't already exist), to list the files within it, and to write to the files within it.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
dirA null terminated string that contains the certificate directory.
Returns
void

◆ appd_config_set_logging_max_file_size_bytes()

APPD_API void appd_config_set_logging_max_file_size_bytes ( struct appd_config *  cfg,
const unsigned int  size 
)

The maximum size of an individual log file, in bytes. Log files are rotated when they reach this size.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
size
Returns
void

◆ appd_config_set_logging_max_num_files()

APPD_API void appd_config_set_logging_max_num_files ( struct appd_config *  cfg,
const unsigned int  num 
)

The maximum number of log files allowed per tenant. Once this is hit, the logs are rotated.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
num
Returns
void

◆ appd_config_set_logging_min_level()

APPD_API void appd_config_set_logging_min_level ( struct appd_config *  cfg,
enum appd_config_log_level  lvl 
)

The minimum level of logging allowed. If APPD_LOG_LEVEL_TRACE, all log messages are allowed. If APPD_LOG_LEVEL_FATAL, only the most severe errors are logged. The default is APPD_LOG_LEVEL_INFO.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
lvl
Returns
void

◆ appd_config_set_node_name()

APPD_API void appd_config_set_node_name ( struct appd_config *  cfg,
const char *  node 
)

The default node name sets the default application context's node name. This will be used for all the default application context metrics.

Parameters
cfg- a pointer to the default application context structure created by appd_config_init()
node- a NULL terminated string that contains the node name.
Returns
void

◆ appd_config_set_tier_name()

APPD_API void appd_config_set_tier_name ( struct appd_config *  cfg,
const char *  tier 
)

The default tier name sets the default application context's tier name. This will be used for all the default application context metrics.

Parameters
cfgA pointer to the default application context structure created by appd_config_init().
tierA NULL terminated string that contains the tier name.
Returns
void

◆ appd_construct_callgraph_element()

APPD_API appd::sdk::CallGraphElement* appd_construct_callgraph_element ( const appd::sdk::CallGraph callgraph,
const std::string &  class_name,
const std::string &  method_name,
const std::string &  file_path,
int32_t  line_number,
int32_t  time_msec,
appd_frame_type  frame_type 
)

< namespace appd

◆ appd_context_config_init()

APPD_API struct appd_context_config* appd_context_config_init ( const char *  context)

Creates an empty alternate application context (for multi-node or multi-controller implementations) configuration structure and returns a pointer to the initialized structure. Do not free this structure, it will be released when appd_sdk_term() is called.

Call the function (passing the name of the alternate application context) then set values within it using the pointer returned from the call and the following methods:

appd_context_config_set_analytics_enabled()
appd_context_config_set_app_name()
appd_context_config_set_tier_name()
appd_context_config_set_node_name()
appd_context_config_set_controller_host()
appd_context_config_set_controller_port()
appd_context_config_set_controller_account()
appd_context_config_set_controller_access_key()
appd_context_config_set_controller_use_ssl()
appd_context_config_set_controller_http_proxy_host()
appd_context_config_set_controller_http_proxy_port()
appd_context_config_set_controller_http_proxy_username()
appd_context_config_set_controller_http_proxy_password()
appd_context_config_set_controller_http_proxy_password_file()
appd_context_config_set_controller_certificate_file()
appd_context_config_set_controller_certificate_dir()

At a minimum, the host, port, SSL, account, access key, application name, tier name, and node name must all be set for the SDK to properly connect to the Controller. Once the structure contains the correct configuration settings, call appd_sdk_add_app_context() to initialized the alternate context within the SDK.

Use the appd_context_config_init() function to initialize the alternate context within the SDK, only after the appd_sdk_init() call has been made.

NOTE: Do not call appd_context_config_init() a second time, as it will reinitialize the structure and zero out any previous configuration settintgs.

Parameters
contextA null terminated string that names the application context, similiar to appd_config_init() for the default context.
Returns
A pointer to an initialized appd_config structure.

◆ appd_context_config_set_app_name()

APPD_API void appd_context_config_set_app_name ( struct appd_context_config *  context_cfg,
const char *  app 
)

An alternate application context application name sets the application name for an alternate application context.

Parameters
context_cfgA pointer to the alternate application context structure created by appd_context_config_init().
appA NULL terminated string that contains the application name.
Returns
void

◆ appd_context_config_set_controller_access_key()

APPD_API void appd_context_config_set_controller_access_key ( struct appd_context_config *  context_cfg,
const char *  key 
)

Sets the alternate application context's Controller access key. This value should match the key shown in the account tab of the license page off the Controller's Gear icon.

Parameters
context_cfgA pointer to the alternate application context structure created by appd_config_init().
keyA null terminated string that describes the account name.
Returns
void

◆ appd_context_config_set_controller_account()

APPD_API void appd_context_config_set_controller_account ( struct appd_context_config *  context_cfg,
const char *  acct 
)

Sets the alternate application context's Controller accountt name for an alternate application context.

Parameters
context_cfgA pointer to the alternate application context structure created by appd_config_init().
acctA NULL terminated string that describes the account name.
Returns
void

◆ appd_context_config_set_controller_certificate_dir()

APPD_API void appd_context_config_set_controller_certificate_dir ( struct appd_context_config *  context_cfg,
const char *  dir 
)

CA certificate directory for an alternate application context.

Set this if you have multiple certificate files located in a single directory.

Parameters
context_cfgA pointer to the default application context structure created by appd_context_config_init().
dirA null terminated string that contains the certificate directory.
Returns
void

◆ appd_context_config_set_controller_certificate_file()

APPD_API void appd_context_config_set_controller_certificate_file ( struct appd_context_config *  context_cfg,
const char *  file 
)

CA certificate file (full path) for an alternate application context. Defaults to the included ca-bundle.crt file. Set this to use your own certificate file.

Parameters
context_cfgA pointer to the default application context structure created by appd_context_config_init().
fileA null terminated string that contains the certificate file.
Returns
void

◆ appd_context_config_set_controller_host()

APPD_API void appd_context_config_set_controller_host ( struct appd_context_config *  context_cfg,
const char *  host 
)

Sets the context's Controller host name for alternate application contexts.

Parameters
context_cfgA pointer to the alternate application context structure created by appd_context_config_init().
hostA NULL terminated string that contains the host URL string or IPADDR.
Returns
void

◆ appd_context_config_set_controller_http_proxy_host()

APPD_API void appd_context_config_set_controller_http_proxy_host ( struct appd_context_config *  context_cfg,
const char *  host 
)

(Optional) The HTTP proxy host name if you are using an HTTP proxy to talk to the Controller for an alternate application context. The HTTP proxy config options are optional and only necessary if a proxy is required to connect to the Controller.

Parameters
context_cfgA pointer to the alternate application context structurer created by appd_config_init().
hostThe NULL terminated string that conttains the HTTP proxy host name.
Returns
void

◆ appd_context_config_set_controller_http_proxy_password()

APPD_API void appd_context_config_set_controller_http_proxy_password ( struct appd_context_config *  context_cfg,
const char *  pwd 
)

(Optional) The password to connect to the HTTP proxy for an alternate application context. The HTTP proxy config options are optional, and only necessary if a proxy is required to connect the SDK host to the Controller.

Parameters
context_cfgA pointer to the alternate application context structure created by appd_context_config_init().
pwdA null terminated string that contains the password used to connect to the HTTP proxy.
Returns
void

◆ appd_context_config_set_controller_http_proxy_password_file()

APPD_API void appd_context_config_set_controller_http_proxy_password_file ( struct appd_context_config *  context_cfg,
const char *  file 
)

(Optional) The file that contains the password to connect to the HTTP proxy in an alternate application context. The HTTP proxy config options are optional, and only necessary if a proxy is required to connect the SDK host to the Controller.

Parameters
context_cfgA pointer to the alternate application context structure created by appd_context_config_init().
fileA null terminated string that contains the password file. The file is written in clear text.
Returns
void

◆ appd_context_config_set_controller_http_proxy_port()

APPD_API void appd_context_config_set_controller_http_proxy_port ( struct appd_context_config *  context_cfg,
const unsigned short  port 
)

(Optional) The port name of the HTTP proxy for an alternate application context. (Default: 80) The HTTP proxy config options are optional, and only necessary if a proxy is required to connect the SDK host to the Controller.

Parameters
context_cfgA pointer to the alternate application context structure created by appd_context_config_init()
portAn unsigned short that contains the HTTP proxy host port.
Returns
void

◆ appd_context_config_set_controller_http_proxy_username()

APPD_API void appd_context_config_set_controller_http_proxy_username ( struct appd_context_config *  context_cfg,
const char *  user 
)

(Optional) The username to connect to the HTTP proxy for an alternate application context. The HTTP proxy config options are optional, and only necessary if a proxy is required to connect the SDK host to the Controller.

Parameters
context_cfgA pointer to the alternate application context structure created by appd_context_config_init()
userA null terminated string that contains the user name.
Returns
void

◆ appd_context_config_set_controller_port()

APPD_API void appd_context_config_set_controller_port ( struct appd_context_config *  context_cfg,
const unsigned short  port 
)

Sets the port on which the alternate application context the Controller is expected to be listening.

If not specifed, defaults to 80 when use_ssl is false and 443 when use_ssl is true.

Parameters
context_cfgA pointer to the default application context structure created by appd_context_config_init().
portAn unsigned short that contains the port number.
Returns
void

◆ appd_context_config_set_controller_use_ssl()

APPD_API void appd_context_config_set_controller_use_ssl ( struct appd_context_config *  context_cfg,
unsigned int  ssl 
)

Flag that specifies if SSL should be used to talk to the Controller for an alternate application context.

Set to a non-zero integer for true. Set to the integer zero for false.

This value must be non-zero for SaaS Controllers.

Parameters
context_cfgA pointer to the alternate application context structure created by appd_context_config_init().
sslIf zero, do not use SSL, if non-zero, use SSL.
Returns
void

◆ appd_context_config_set_node_name()

APPD_API void appd_context_config_set_node_name ( struct appd_context_config *  context_cfg,
const char *  node 
)

The alternate application context node name sets the default business transaction's node name for an alternate application context.

Parameters
context_cfgA pointer to the alternate application context structure created by appd_context_config_init().
nodeA NULL terminated string that contains the node name.
Returns
void

◆ appd_context_config_set_tier_name()

APPD_API void appd_context_config_set_tier_name ( struct appd_context_config *  context_cfg,
const char *  tier 
)

Alernate application context tier name sets the tier name for an alternate application context.

Parameters
context_cfg- a pointer to the alternate application context structure created by appd_context_config_init()
tier- a NULL terminated string that contains the tier name.
Returns
void

◆ appd_custom_event_add_detail()

APPD_API int appd_custom_event_add_detail ( appd_event_handle  event_handle,
const char *  detail_name,
const char *  detail_value 
)

Add detail name and value for custom event. This detail name and value are used to tag additional details to the custom event.

Parameters
event_handleAn handle for the custom event. If this is NULL, zero, or invalid, then it is an error and zero is returned.
detail_nameA string containing the name of detail. If this is NULL, zero, or empty, then it is an error and zero is returned.
detail_valueA string containing the value of detail. If this is NULL, zero, or empty, then it is an error and zero is returned.
Returns
Returns non-zero if the detail was successfully added to custom event definition. Otherwise, zero is returned.

◆ appd_custom_event_add_property()

APPD_API int appd_custom_event_add_property ( appd_event_handle  event_handle,
const char *  property_name,
const char *  property_value 
)

Add property name and value for custom event. This property name and value are used to filter the custom events in the Controller.

Parameters
event_handleAn handle for the custom event. If this is NULL, zero, or invalid, then it is an error and zero is returned.
property_nameA string containing the name of property. If this is NULL, zero, or empty, then it is an error and zero is returned.
property_valueA string containing the value of property. If this is NULL, zero, or empty, then it is an error and zero is returned.
Returns
An integer indicating the success of operation. Returns non-zero if the property was successfully added to the custom event definition. Otherwise, zero is returned.

◆ appd_custom_event_end()

APPD_API int appd_custom_event_end ( appd_event_handle  event_handle)

End the definition of custom event and report it.

If appd_custom_event_start() is called and appd_custom_event_end() is NOT called for the corresponding event_handle, then the event will never be reported to the Controller. Also the memory holding the even data will be kept alive until appd_sdk_term() is called.

Parameters
event_handleAn handle for the custom event. If this is NULL, zero, or invalid, then it is an error and zero is returned.
Returns
Returns non-zero if custom event definition is completed and reported. Otherwise zero is returned.

◆ appd_custom_event_start()

APPD_API appd_event_handle appd_custom_event_start ( const char *  application_context,
enum appd_event_severity  severity,
const char *  event_sub_type,
const char *  summary 
)

Start to define a custom event. The definition of custom event will complete when appd_custom_event_end() is called and event will be reported.

Parameters
application_contextA string contaning the application context name for this custom event.
severityEnum representing the severity for this custom event.
event_sub_typeA string containing the custom event subtype. This subtype can be used in controller to filter the custom events belonging to a specific subtype.
summaryA string containing the summary of what this custom event is about.
Returns
An event handle for the custom event that is being defined. It will be NULL if failed to start the custom event definition.

◆ appd_custom_metric_add()

APPD_API void appd_custom_metric_add ( const char *  application_context,
const char *  metric_path,
enum appd_time_rollup_type  time_rollup_type,
enum appd_cluster_rollup_type  cluster_rollup_type,
enum appd_hole_handling_type  hole_handling_type 
)

Define a custom metric.

Parameters
application_contextThe application context for this custom metric.
metric_pathThe path of the custom metric.
time_rollup_typeSpecifies how to rollup metric values for this metric over time, e.g., to compute the average over time, pass APPD_TIMEROLLUP_TYPE_AVERAGE.
cluster_rollup_typeSpecifies how to rollup metric values for this metric across clusters.
hole_handling_typeSpecifies how to handle holes (gaps where no value has been reported from this metric).
Returns
void

◆ appd_custom_metric_report()

APPD_API void appd_custom_metric_report ( const char *  application_context,
const char *  metric_path,
long  value 
)

Report a value for a given metric.

Parameters
application_contextThe application context for this custom metric.
metric_pathThe path of the metric to report, as defined by appd_custom_metric_add.
valueThe value to report for the metric. The way the value is aggregated is specified by the roll-up parameters to appd_custom_metric_add.
Returns
void

◆ appd_eum_get_cookie()

APPD_API const char* appd_eum_get_cookie ( appd_bt_handle  bt,
int  https,
int  short_form,
const char *  referrer_url,
const char *  path 
)

Return a cookie for the request related to Business Transaction

Parameters
btThe business transaction for the cookie.
httpsThis, when non-zero, indicates https protocol is used for request. This is used to add "Secure" field in cookie.
short_formThis, when non-zero, indicates shortened names will be used for cookie fields.
referrer_urlThe address of the webpage where a person clicked a link that sent them to your page. This can be set to "" if there is no referrer url.
pathThe path parameter specifies a document location for the cookie. This is used to add "Path" field in cookie. This can be set to "/" in most cases.
Returns
A string containing the cookie key and value. Release of memory is handled by appdynamics code, user should not try to free this string. The memory of this cookie is valid until business transaction associated with this cookie is stopped. Once the business transaction is stopped, memory associated with this cookie is automatically released. If EUM is disabled or if no configuration information is received yet from controller, then nullptr is returned.

◆ appd_exitcall_add_error()

APPD_API void appd_exitcall_add_error ( appd_exitcall_handle  exitcall,
enum appd_error_level  level,
const char *  message,
int  mark_bt_as_error 
)

Add an error to the exit call.

Parameters
exitcall
level
message
mark_bt_as_error
Returns
void

◆ appd_exitcall_begin()

APPD_API appd_exitcall_handle appd_exitcall_begin ( appd_bt_handle  bt,
const char *  backend 
)

Start an exit call as part of a business transaction.

Parameters
bt
backend
Returns
An opaque handle to the exit call that was started. NULL if the call fails.

◆ appd_exitcall_end()

APPD_API void appd_exitcall_end ( appd_exitcall_handle  exitcall)

Complete the exit call.

Parameters
exitcall

◆ appd_exitcall_get()

APPD_API appd_exitcall_handle appd_exitcall_get ( const char *  guid)

Get an exit call associated with a guid via appd_exitcall_store.

Parameters
guidThe globally unique identifier that was passed to appd_exitcall_store.
Returns
The handle associated with the given guid. If no handle was associated with the guid, or if the call ended prior to getting it, a warning is logged and the returned handle may be safely used in other API functions but will cause these functions to immediately return without doing anything.

◆ appd_exitcall_get_correlation_header()

APPD_API const char* appd_exitcall_get_correlation_header ( appd_exitcall_handle  exitcall)

Get the header to correlate a business transaction.

If a business transaction makes exit calls that you wish to correlate across, you should retrieve the correlation header and inject that into your exit call's payload.

The returned string is freed when the exit call ends. Do not free it yourself.

Parameters
exitcall
Returns
A 7-bit ASCII string containing the correlation information. You can inject this into your payload for an exit call. An agent on the other end can then extract the header from your payload and continue the business transaction. On error, a message is logged and the default header that prevents downstream bt detection is returned.

◆ appd_exitcall_set_details()

APPD_API int appd_exitcall_set_details ( appd_exitcall_handle  exitcall,
const char *  details 
)

Set the details string for an exit call.

This can be used, for example, to add the SQL statement that a DB backend has executed as part of the exit call.

Parameters
exitcall
detailsAn arbitrary detail string to add to the exit call.
Returns
Zero on success. Non-zero on error. On error, a message is logged.

◆ appd_exitcall_store()

APPD_API void appd_exitcall_store ( appd_exitcall_handle  exitcall,
const char *  guid 
)

Store an exit call handle for retrieval with appd_exitcall_get.

This function allows you to store an exit call in a global registry to retrieve later. This is convenient when you need to start and end the call in separate places, and it is difficult to pass the handle through the parts of the code that need it.

The handle is removed when the exit call (or the business transaction containing it) ends.

Example

appd_exitcall_handle ec = appd_exitcall_begin(bt, "authdb");
appd_exitcall_store(ec, "login-exit");
Parameters
exitcallThe exit call to store.
guidA globally unique identifier to associate with the given call.
Returns
void

◆ appd_frame_begin()

APPD_API appd_frame_handle appd_frame_begin ( appd_bt_handle  bt,
enum appd_frame_type  frame_type,
const char *  class_name,
const char *  method_name,
const char *  file,
int  line_number 
)

Record start of a frame in a call graph that can be reported with a BT. The info is collected only if the BT is snapshotting. This should be called near the start of the method code and must be paired with appd_frame_end when returning from the method. In C++ code please use the Frame class (below). The current implementation collects only frames from one thread for a BT. Subsequent calls from a different thread will be dropped.

Parameters
btThe business transaction for the call graph.
frame_typeThe type of the frame. When used in C or C++ code, use APPD_FRAME_TYPE_CPP.
class_nameThe name of the class if this method is a member of the class, else NULL.
method_nameThe name of the method.
fileThe path of the source file.
line_numberThe line number in the source file.
Returns
An opaque handle for the frame. NULL if an error happened.

◆ appd_frame_end()

APPD_API void appd_frame_end ( appd_bt_handle  bt,
appd_frame_handle  frame 
)

Record the end of a frame. Must match a corresponding appd_frame_begin. Call this before returning from the method. Note that if exceptions are thrown, you must handle this in your code, otherwise this part of the call graph will be discarded.

Parameters
btThe business transaction for the call graph.
frameThe handle of returned by the corresponding appd_frame_begin.
Returns
void

◆ appd_sdk_add_app_context()

APPD_API int appd_sdk_add_app_context ( struct appd_context_config *  context_cfg)

Add application context to AppDynamics SDK for multi-tenancy.

Parameters
context_cfgA pointer to the alternate application context structure created by appd_context_config_init().

◆ appd_sdk_init()

APPD_API int appd_sdk_init ( const struct appd_config *  config)

Initialize the AppDynamics SDK.

Parameters
configAppDynamics configuration object.
Returns
On success, zero is returned. Otherwise, a non-zero value is returned.

◆ appd_sdk_term()

APPD_API void appd_sdk_term ( )

Terminate the AppDynamics SDK.

APPD_FRAME_TYPE_CPP
@ APPD_FRAME_TYPE_CPP
Definition: appdynamics.h:1151
appd::sdk::Frame
Definition: appdynamics.h:1685
APPD_FUNCTION_NAME
#define APPD_FUNCTION_NAME
Definition: appdynamics.h:1928