#include <string>
#include <memory>
#include <map>

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

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::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)

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

enum 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

enum 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.

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

enum 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

enum 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

enum 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

enum 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

enum 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

type	One of the `APPD_BACKEND_xxx` constants or any string.
unregistered_name	The 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

bt	The business transaction to add the error to.
level	The error level. One of the `APPD_LEVEL_xxx` constants.
message	The error message.
mark_bt_as_error	If 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

bt	The business transaction to add the user data to if is taking a snapshot.
key	The name of the user data to add to the snapshot as 7-bit ASCII or UTF-8.
value	The 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

name	The name for the business transaction.
correlation_header	A 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

context	The application context name string for the alternate application context.
name	The name for the business transaction.
correlation_header	A 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

bt	Handle 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

bt	The 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

guid	The 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

bt	The 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

bt	The business transaction to add the user data to, if it is taking a snapshot.
url	The 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

bt	The business transaction to store.
guid	A 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

cfg	A pointer to the default application context structure created by appd_config_init().
prefix	The 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

cfg	A pointer to the default application context structure crerated by appd_config_init().
enable	If 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

cfg	A pointer to the default application context structure created by appd_config_init().
host	URL 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

cfg	A pointer to the default application context structure created by appd_config_init().
port	An 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

ssl	If 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

cfg	A pointer to the default application context structure created by appd_config_init().
app	A 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

cfg	A pointer to the default application context structure created by appd_config_init().
key	A 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

cfg	A pointer to the default application context structure created by appd_config_init().
acct	A 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

cfg	A pointer to the default application context structure created by appd_config_init().
dir	A 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

cfg	A pointer to the default application context structure created by appd_config_init().
file	A 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

cfg	A pointer to the default application context structure created by appd_config_init().
host	A 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

cfg	A pointer to the deafult application context structure crerated by appd_config_init().
host	The 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

cfg	A pointer to the default application context structure created by appd_config_init().
pwd	A 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

cfg	A pointer to the default application context structure created by appd_config_init()
file	A 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

cfg	A pointer to the default application context structure created by appd_config_init().
port	An 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

cfg	A pointer to the default application context structure created by appd_config_init().
user	A 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

cfg	A pointer to the default application context structure created by appd_config_init().
port	An 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

cfg	A pointer to the alternate application context structure created by appd_config_init().
ssl	If 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

cfg	A pointer to the default application context structure created by appd_config_init().
enable	If 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

cfg	A pointer to the default application context structure created by appd_config_init().
time	The 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

cfg	A pointer to the default application context structure created by appd_config_init().
dir	A 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

cfg	A 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

cfg	A 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

cfg	A 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

cfg	A pointer to the default application context structure created by appd_config_init().
tier	A 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

context A 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_cfg	A pointer to the alternate application context structure created by appd_context_config_init().
app	A 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_cfg	A pointer to the alternate application context structure created by appd_config_init().
key	A 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_cfg	A pointer to the alternate application context structure created by appd_config_init().
acct	A 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_cfg	A pointer to the default application context structure created by appd_context_config_init().
dir	A 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_cfg	A pointer to the default application context structure created by appd_context_config_init().
file	A 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_cfg	A pointer to the alternate application context structure created by appd_context_config_init().
host	A 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_cfg	A pointer to the alternate application context structurer created by appd_config_init().
host	The 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_cfg	A pointer to the alternate application context structure created by appd_context_config_init().
pwd	A 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_cfg	A pointer to the alternate application context structure created by appd_context_config_init().
file	A 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_cfg	A pointer to the alternate application context structure created by appd_context_config_init()
port	An 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_cfg	A pointer to the alternate application context structure created by appd_context_config_init()
user	A 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_cfg	A pointer to the default application context structure created by appd_context_config_init().
port	An 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_cfg	A pointer to the alternate application context structure created by appd_context_config_init().
ssl	If 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_cfg	A pointer to the alternate application context structure created by appd_context_config_init().
node	A 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_handle	An handle for the custom event. If this is NULL, zero, or invalid, then it is an error and zero is returned.
detail_name	A string containing the name of detail. If this is NULL, zero, or empty, then it is an error and zero is returned.
detail_value	A 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_handle	An handle for the custom event. If this is NULL, zero, or invalid, then it is an error and zero is returned.
property_name	A string containing the name of property. If this is NULL, zero, or empty, then it is an error and zero is returned.
property_value	A 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_handle An 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_context	A string contaning the application context name for this custom event.
severity	Enum representing the severity for this custom event.
event_sub_type	A string containing the custom event subtype. This subtype can be used in controller to filter the custom events belonging to a specific subtype.
summary	A 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_context	The application context for this custom metric.
metric_path	The path of the custom metric.
time_rollup_type	Specifies 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_type	Specifies how to rollup metric values for this metric across clusters.
hole_handling_type	Specifies 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_context	The application context for this custom metric.
metric_path	The path of the metric to report, as defined by `appd_custom_metric_add`.
value	The 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

bt	The business transaction for the cookie.
https	This, when non-zero, indicates https protocol is used for request. This is used to add "Secure" field in cookie.
short_form	This, when non-zero, indicates shortened names will be used for cookie fields.
referrer_url	The 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.
path	The 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

guid	The 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
details	An 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

exitcall	The exit call to store.
guid	A 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

bt	The business transaction for the call graph.
frame_type	The type of the frame. When used in C or C++ 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.
file	The path of the source file.
line_number	The 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

bt	The business transaction for the call graph.
frame	The 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_cfg A 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

config AppDynamics 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.

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 }

Classes

Namespaces

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ APPD_API

◆ APPD_AUTO_FRAME

◆ APPD_BACKEND_CACHE

◆ APPD_BACKEND_DB

◆ APPD_BACKEND_HTTP

◆ APPD_BACKEND_JMS

◆ APPD_BACKEND_RABBITMQ

◆ APPD_BACKEND_WEBSERVICE

◆ APPD_BACKEND_WEBSPHEREMQ

◆ APPD_CORRELATION_HEADER_NAME

Upstream Correlation

Downstream Correlation

◆ APPD_FUNCTION_NAME

Typedef Documentation

◆ appd_bt_handle

◆ appd_event_handle

◆ appd_exitcall_handle

◆ appd_frame_handle

Enumeration Type Documentation

◆ appd_cluster_rollup_type

◆ appd_config_log_level

◆ appd_error_level

◆ appd_event_severity

◆ appd_frame_type

◆ appd_hole_handling_type

◆ appd_time_rollup_type

Function Documentation

◆ appd_backend_add()

◆ appd_backend_declare()

◆ appd_backend_prevent_agent_resolution()

◆ appd_backend_set_identifying_property()

◆ appd_bt_add_error()

◆ appd_bt_add_user_data()

◆ appd_bt_begin()

◆ appd_bt_begin_with_app_context()

◆ appd_bt_enable_snapshot()

◆ appd_bt_end()

◆ appd_bt_get()

◆ appd_bt_is_snapshotting()

◆ appd_bt_set_url()

◆ appd_bt_store()

Example

◆ appd_callgraph_add_to_snapshot()

◆ appd_config_getenv()

◆ appd_config_init()

◆ appd_config_set_analytics_enabled()

◆ appd_config_set_analytics_host()

◆ appd_config_set_analytics_port()

◆ appd_config_set_analytics_use_ssl()

◆ appd_config_set_app_name()

◆ appd_config_set_controller_access_key()

◆ appd_config_set_controller_account()

◆ appd_config_set_controller_certificate_dir()

◆ appd_config_set_controller_certificate_file()

◆ appd_config_set_controller_host()

◆ appd_config_set_controller_http_proxy_host()

◆ appd_config_set_controller_http_proxy_password()

◆ appd_config_set_controller_http_proxy_password_file()

◆ appd_config_set_controller_http_proxy_port()

◆ appd_config_set_controller_http_proxy_username()

◆ appd_config_set_controller_port()

◆ appd_config_set_controller_use_ssl()

◆ appd_config_set_flush_metrics_on_shutdown()

◆ appd_config_set_init_timeout_ms()

◆ appd_config_set_logging_log_dir()

◆ appd_config_set_logging_max_file_size_bytes()

◆ appd_config_set_logging_max_num_files()

◆ appd_config_set_logging_min_level()

◆ appd_config_set_node_name()

◆ appd_config_set_tier_name()

◆ appd_construct_callgraph_element()

◆ appd_context_config_init()

◆ appd_context_config_set_app_name()