C/C++ SDK Reference

This page describes the functions, structures, and environment variables defined in the C/C++ SDK to instrument C/C++ applications. 

The API includes functions to create business transactions, transaction backends/exit points, and define custom metrics.

Basic Types

The C/C++ SDK defines the following opaque types:

• appd_bt_handle: A handle to an active business transaction
• appd_exitcall_handle: A handle to an active exit call
• struct appd_config*: A pointer to a configuration object

• struct appd_context_config*: A pointer to a context configuration object

appd_config_init

Initializes an empty configuration structure. Call this function before before calling appd_sdk_init().

Format 

APPD_API struct appd_config * appd_config_init ()

Parameters

• cfg: AppDynamics configuration object.

appd_config_set_analytics_enabled

Set an enable/disable flag for Analytics Agent reporting. When disabled, Analytics-related logging messages are suppressed.

Format

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

Parameters

• cfg: AppDynamics configuration structure for the C/C++ SDK.
• enable: The enable/disable flag for the Analytics Agent. If the value is non-zero, the agent is enabled. If the value is zero (default setting), then the agent is disabled.

appd_config_set_app_name

Set business application name.

Format 

appd_config_set_app_name(cfg, APP_NAME);

Parameters

• cfg: AppDynamics configuration object. 
• APP_NAME: Name of the application.

appd_config_set_tier_name

Set tier name.

Format 

appd_config_set_tier_name(cfg, TIER_NAME);

Parameters

• cfg: AppDynamics configuration object. 

• TIER_NAME: Name of the tier.

appd_config_set_node_name

Set node name.

Format 

appd_config_set_node_name(cfg, NODE_NAME);

Parameters

• cfg – AppDynamics configuration object. 
• NODE_NAME – Name of the node.

appd_config_set_controller_host

Set hostname of the Controller.

Format 

appd_config_set_controller_host(cfg, CONTROLLER_HOST);

Parameters

• cfg: AppDynamics configuration object. 

• CONTROLLER_HOST: Name of the Controller host.

appd_config_set_controller_port

Set the port number on which the Controller is listening.

Format 

appd_config_set_controller_port(cfg, CONTROLLER_PORT);

Parameters

• cfg: AppDynamics configuration object. 
• CONTROLLER_PORT: Port number that the Controller is listening on.

appd_config_set_controller_account

Set the account name for connecting to the Controller.

Format 

appd_config_set_controller_account(cfg, CONTROLLER_ACCOUNT);

Parameters

• cfg: AppDynamics configuration object. 
• CONTROLLER_ACCOUNT: Account name that the Controller is connected to.

appd_config_set_controller_access_key

Set the access key for connecting to the Controller.

Format 

appd_config_set_controller_access_key(cfg, CONTROLLER_ACCESS_KEY);

Parameters

• cfg: AppDynamics configuration object. 
• CONTROLLER_ACCESS_KEY: Access key for connecting to the Controller.

appd_config_set_controller_use_ssl

Specify whether SSL should be used to communicate with the Controller.

Format 

appd_config_set_controller_use_ssl(cfg, CONTROLLER_USE_SSL);

Parameters

• cfg: AppDynamics configuration object. 
• CONTROLLER_USE_SSL: Whether to use SSL to connect with the Controller. Set to a non-zero integer for true. Set to the integer zero for false. Note that SaaS Controllers require this to be set to non-zero.

appd_config_set_controller_http_proxy_host

Optional. Set the hostname of the HTTP proxy if using an HTTP proxy to talk to Controller. 

Format 

appd_config_set_controller_http_proxy_host(cfg, CONTROLLER_HTTP_PROXY_HOST);

Parameters

• cfg: AppDynamics configuration object. 
• CONTROLLER_HTTP_PROXY_HOST: Hostname of the HTTP proxy if using an HTTP proxy to talk to Controller. 

appd_config_set_controller_http_proxy_port

Optional. Set the port number of the HTTP proxy. Default is 80.

Format 

appd_config_set_controller_http_proxy_port(cfg, CONTROLLER_HTTP_PROXY_PORT);

Parameters

• cfg: AppDynamics configuration object. 
• CONTROLLER_HTTP_PROXY_PORT: Port name of the HTTP proxy. Default is 80.

appd_config_set_controller_http_proxy_username

Optional. Set the username to connect to the HTTP proxy with.

Format 

appd_config_set_controller_http_proxy_username(cfg, CONTROLLER_HTTP_PROXY_USERNAME);

Parameters

• cfg: AppDynamics configuration object. 
• CONTROLLER_HTTP_PROXY_USERNAME: Username to connect to the HTTP proxy with.

appd_config_set_controller_http_proxy_password

Optional. Set the password to connect to the HTTP proxy with.

Format 

appd_config_set_controller_http_proxy_password(cfg, CONTROLLER_HTTP_PROXY_PASSWORD);

Parameters

• cfg: AppDynamics configuration object. 
• CONTROLLER_HTTP_PROXY_PASSWORD: Password to connect to the HTTP proxy with.

appd_config_set_controller_http_proxy_password_file

Optional. Set the file containing password to connect to the HTTP proxy with.

Format 

appd_config_set_controller_http_proxy_password_file(cfg, CONTROLLER_HTTP_PROXY_PASSWORD_FILE);

Parameters

• cfg: AppDynamics configuration object. 
• CONTROLLER_HTTP_PROXY_PASSWORD_FILE: File containing password to connect to the HTTP proxy with.

appd_config_set_controller_certificate_file

Optional. Set the the CA certificate file name. Set this if you choose to use your own certificate file.

Format 

appd_config_set_controller_certificate_file(cfg, CONTROLLER_HTTP_CERTIFICATE_FILE);

Parameters

• cfg:  AppDynamics configuration object. 
• CONTROLLER_CERTIFICATE_FILE: Name of the certificate file. Defaults to the included ca-bundle.crt file. 

appd_config_set_controller_certificate_dir

Optional. Set the full path to the CA certificate file. Set this if you have multiple certificate files. 

Format 

appd_config_set_controller_certificate_dir(cfg, CONTROLLER_HTTP_CERTIFICATE_DIR);

Parameters

• cfg: AppDynamics configuration object. 
• CONTROLLER_CERTIFICATE_DIR: Full path to the certificate files.

appd_config_set_flush_metrics_on_shutdown

Specify whether to collect metrics in the final minute before SDK shutdown—via appd_sdk_term. By default, metrics reported in the minute before shutdown are lost. If you enable metric flushing, then you can retain the metrics reported in the final minute before shutdown.

Format

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

Parameters

• cfg: AppDynamics configuration object.
• int: Set to a non-zero integer to enable flushing metrics to the Controller. Default is 0.

By setting this flag, the appd_sdk_term() is blocked until the underpinning agent logic has uploaded the metric data. By not using this flag, any metrics collected since the last Controller update is discarded. Depending on the load on the Controller, flushing the metrics can take anywhere between 60 and 120 seconds on average or longer. Do not use this flag if you need the termination/tear-down logic to complete immediately.

appd_config_set_logging_min_level

Set the minimum level of logging that is 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.

Format 

appd_config_set_logging_min_level(cfg, LOGGING_MIN_LEVEL);

Parameters

• cfg: AppDynamics configuration object.
• LOGGING_MIN_LEVEL: The minimum level of logging that is allowed.
• APPD_LOG_LEVEL_TRACE
• APPD_LOG_LEVEL_DEBUG
• APPD_LOG_LEVEL_INFO
• APPD_LOG_LEVEL_WARN
• APPD_LOG_LEVEL_ERROR
• APPD_LOG_LEVEL_FATAL

appd_config_set_logging_log_dir

Set the directory to log to. The process running the SDK must have permissions to create this directory, if it does not already exist, to list the files within it, and to write to the files within it.

Format 

appd_config_set_logging_log_dir(cfg, LOGGING_LOG_DIR);

Parameters

• cfg: AppDynamics configuration object. 
• LOGGING_LOG_DIR: The directory where you want to store log files. Defaults to /tmp/appd.

appd_config_set_logging_max_num_files

Set the maximum number of log files allowed per tenant. Log files are rotated when they reach this number. 

Format 

appd_config_set_logging_max_num_files(cfg, LOGGING_MAX_NUM_FILES);

Parameters

• cfg: AppDynamics configuration object. 
• LOGGING_MAX_NUM_FILES: The maximum number of log files allowed per tenant. Default is 10.

appd_config_set_logging_max_file_size_bytes

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

Format 

appd_config_set_logging_max_file_size_bytes(cfg, LOGGING_MAX_FILE_SIZE_BYTES);

Parameters

• cfg: AppDynamics configuration object. 
• LOGGING_MAX_FILE_SIZE_BYTES: The maximum size of an individual log file, in bytes. Default is 5 * 1024 * 1024.

appd_config_set_init_timeout_ms

Set the number of milliseconds you want appd_sdk_init (an asynchronous action) to wait until it has received controller configuration and is ready to capture business transactions. Set this if you want to capture short-running business transactions that occur at application startup and you don't mind the delay of waiting for the Controller to send the configuration.

Format 

appd_config_set_init_timeout_ms(cfg, INIT_TIMEOUT_MS);

Parameters

• cfg: AppDynamics configuration object. 
• INIT_TIMEOUT_MS: The number of milliseconds you want appd_sdk_init (an asynchronous action) to wait until it has received controller configuration and is ready to capture business transactions.
  • X: Wait up to X milliseconds for Controller configuration.
  • 0: Do not Wait for Controller configuration.
  • -1: Wait indefinitely until Controller configuration is received by agent
  • Default is 0.

appd_config_getenv

Set the environment variable for configuring the SDK. Environment variables are not read by default. You must call this function to configure the SDK via environment variables.

For a list of available environment variables, see Environment Variables.

Format 

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

Parameters

• cfg: AppDynamics configuration object. 
• prefix: The prefix of the environment variable name, where the environment variable name is <prefix>.<base>. 

appd_context_config_init

Initializes and returns an empty context configuration structure.

Format

APPD_API struct appd_context_config* appd_context_config_init(const char* context_name)

Parameters

• context_name: Name for this context.

appd_context_config_set_controller_host

Add the Controller host to the application context.

Format 

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

Parameters

• context_cfg: An AppDynamics context configuration object indicating the business application, tier and node name for this context.
• host: Name of the Controller host.

appd_context_config_set_controller_port

Add the Controller port to the application context.

Format 

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

Parameters

• context_cfg: An AppDynamics context configuration object indicating the business application, tier, and node name for this context.
• port: Port number that the Controller is listening on.

appd_context_config_set_controller_account

Add the Controller port to the application context.

Format 

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

Parameters

• context_cfg: An AppDynamics context configuration object indicating the business application, tier, and node name for this context.
• account: Account name that the Controller is connected to.

appd_context_config_set_controller_access_key

Add the Controller access key to the application context.

Format 

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

Parameters

• context_cfg: An AppDynamics context configuration object indicating the business application, tier, and node name for this context.
• key: Access key for connecting to the Controller.

appd_context_config_set_controller_use_ssl

Add the Controller access key to the application context.

Format 

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

Parameters

• context_cfg: An AppDynamics context configuration object indicating the business application, tier, and node name for this context.
• ssl: Set to a non-zero integer for true. Set to the integer zero for false. Note that SaaS Controllers require this to be set to non-zero.

appd_context_config_set_controller_http_proxy_host

Optional. Set the hostname of the HTTP proxy if using an HTTP proxy to talk to controller. 

Format 

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

Parameters

• context_cfg: An AppDynamics context configuration object indicating the business application, tier, and node name for this context.
• host: Hostname of the HTTP proxy if using an HTTP proxy to talk to Controller. 

appd_context_config_set_controller_http_proxy_port

Optional. Set the hostname of the HTTP proxy if using an HTTP proxy to talk to Controller. 

Format 

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

Parameters

• context_cfg: An AppDynamics context configuration object indicating the business application, tier, and node name for this context.
• port: Port name of the HTTP proxy. Default is 80.

appd_context_config_set_controller_http_proxy_username

Optional. Set the username to connect to the HTTP proxy with.

Format 

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

Parameters

• context_cfg: An AppDynamics context configuration object indicating the business application, tier, and node name for this context.
• user: Username to connect to the HTTP proxy with.

appd_context_config_set_controller_http_proxy_password

Optional. Set the password to connect to the HTTP proxy with.

Format 

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

Parameters

• context_cfg: An AppDynamics context configuration object indicating the business application, tier, and node name for this context.
• pwd: Password to connect to the HTTP proxy with.

appd_context_config_set_controller_http_proxy_password_file

Optional. Set the password to connect to the HTTP proxy with.

Format 

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

Parameters

• context_cfg: An AppDynamics context configuration object indicating the business application, tier, and node name for this context.
• file: File containing password to connect to the HTTP proxy with.

appd_context_config_set_controller_certificate_file

Optional. Set the CA certificate file name. Set this if you choose to use your own certificate file.

Format 

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

Parameters

• context_cfg: An AppDynamics context configuration object indicating the business application, tier, and node name for this context.
• file: Name of the certificate file. Defaults to the included ca-bundle.crt file. 

appd_context_config_set_controller_certificate_dir

Optional. Set the full path to the CA certificate file. Set this if you have multiple certificate files. 

Format 

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

Parameters

• context_cfg: An AppDynamics context configuration object indicating the business application, tier, and node name for this context.
• dir: Full path to the certificate files.

appd_custom_event_start

This function starts the definition of a custom event. Returns a handle to the defined event. By calling appd_custom_event_end(), the definition of the event is signaled as complete. The event handle returns null on failure.

Format

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)

Parameters

• application_context: This string picks one agent out of multiple agents running in multi-tenant mode. If the value is null, the default agent is used.
• severity: This is an enum representing the severity of the event. Valid values are APPD_EVENT_SEVERITY_INFO, APPD_EVENT_SEVERITY_WARNING, and APPD_EVENT_SEVERITY_ERROR.
• event_sub_type: The string containing the subtype of the custom event. This can be used in the Controller to filter the custom events belonging to a specific subtype.
• summary: A string with a brief description of the event.

appd_custom_event_add_detail

This function adds a detail made up of a name and a value to the definition of a custom event. Returns a non-zero value on success, otherwise zero. This call can be made between the calls of appd_custom_event_start() and appd_custom_event_end(). This function can be called multiple times to add details to the event. The event handle returned by appd_custom_event_start() identifies the right event to add the detail to. If multiple calls to this function are made with the same detail name, then the detail value from the most recent call will be used to associate that detail name.

Format

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

Parameters

• detail_name: This string contains the name of the detail that needs to be added. If the value is null or empty, the API fails and returns zero.
• detail_value: This string contains the name of the value that needs to be added. If the value is null or empty, the API fails and returns zero.
• event_handle: Refers to the event to which the detail needs to be added to. If the value is null or invalid, the API fails and returns zero.

appd_custom_event_add_property

This function adds a property made up of a name and a value to the definition of a custom event. Returns a non-zero value on successful, otherwise zero. This call can be made between the calls of appd_custom_event_start() and appd_custom_event_end(). This function can be called multiple times to add properties to the event. The event handle returned by appd_custom_event_start() identifies the right event to add the property to. This property can be used in the Controller to filter the custom events. If multiple calls to this function are made with the same property name, then the property value from the most recent call will be used to associate that property name.

Format

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

Parameters

• event_handle: Refers to the event to which the property needs to be added to. If the value is null or invalid, the API fails and returns zero.
• property_name: This string contains the name of the property to be added. If the value is null or empty, the API fails and returns zero.
• property_value: This string contains the value of the property to be added. If the value is null or empty, the API fails and returns zero.

appd_custom_event_end

Signals to the C++ SDK that the event definition is complete and queues the event to be sent to the Controller. Returns a zero value on success, otherwise a non-zero value.

Format

APPD_API int appd_custom_event_end(appd_event_handle event_handle)

Parameters

• event_handle: Used to refer to the event. If the value is null or invalid, the API fails and returns zero.

appd_eum_get_cookie

Returns an EUM–ADRUM cookie for a business transaction in an EUM-enabled browser application. You can call this function between appd_bt_begin() and appd_bt_end().

At this time, appd_eum_get_cookie works only on snapshots that contain call graphs. See Correlate Business Transactions for EUM for more information.

Format

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


Parameters

• bt: The handle to the business transaction that the EUM-ADRUM cookie is generated for.
• https: When set to a non-zero value, this flag indicates that the incoming request uses the HTTPS protocol. This flag is used to make the EUM cookie secure.
• short_form: When set to a non-zero value, this flag indicates that shortened names will be used for sub-cookie names inside the EUM cookie.
• referrer_url: The URL of the page from which user made the request. This can be set to NULL or "" if the referrer URL is unknown.
• path: The URL path where the cookie will be stored. This can be set to "/" in most cases. If set to NULL or "", the default value "/" is used.

Returns

On success, the function returns a string that contains a cookie key and a cookie value separated by =. Do not free the memory associated with the returned cookie string; when you call appd_bt_end(), memory is automatically released. 

If EUM is disabled or no configuration information has been received from the Controller, then NULL is returned.

appd_sdk_add_app_context

Initialize the AppDynamics SDK.

Format 

APPD_API int appd_sdk_add_app_context (struct appd_context_config *  context_cfg) 

Parameters

• context_cfg: An AppDynamics context configuration object indicating the business application, tier, and node name for this context.

appd_sdk_init

Initialize the AppDynamics C/C++ SDK. An instrumented application must call this function once, preferably during application startup.

When using fork(), the appd_sdk_init(), and all other SDK calls, should occur only in the forked process, never in the parent, and each child should behave as its own process, and never share handles between the process itself and other SDK instrumented child processes.

Format 

APPD_API int appd_sdk_init (const struct appd_config *  config)

Parameters

• config: AppDynamics configuration settings that enable communication between the agent and the Controller.
  

Returns

Zero on success, otherwise a non-zero value. If the return value is not zero, a log message describes the error.

appd_sdk_term 

Stop the C/C++ SDK. Ends all active business transactions for this agent and stops agent metric reporting to the controller.

If you execute the agent for less than a few minutes, the agent may not have enough time to fully report to the Controller, as this action is done once every 60 seconds. To ensure that any remaining data is transmitted to the Controller, wait at least one minute before issuing the appd_sdk_term() call.

Format 

APPD_API void appd_sdk_term()

appd_bt_begin

Start a Business Transaction or continue an existing transaction. 

Keep in mind that each application is limited to 200 registered business transactions, and each agent is limited to 50 registered business transactions. Like transactions discovered by other types of agents, business transactions that exceed the limit that are reported by the C/C++ SDK are included in the "all other traffic" grouping. Ensure that your agent does not create excessive business transactions and that your implementation does not introduce the possibility of business transaction explosion.

Format 

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

Parameters

• name: The name for the business transaction. In the case of a continuing transaction in the current business application with a valid correlation header, the SDK uses the name from the header. Do not use the following characters in transaction names:  { } [ ] | & ;
• correlation_header: A correlation header if this is a continuing transaction, else NULL. If specified, the correlation header has been generated by another AppDynamics agent and made available to this agent as a string. The correlation header provides information to enable this transaction to correlate with an upstream transaction.
  

Returns

An opaque handle for the business transaction that was started.

appd_bt_begin_with_app_context

Start a business transaction or continue an existing transaction in a multi-tenant Controller environment. 

Format

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

Parameters

• context: The application context name that this business transaction belongs to.
• name: The name for the business transaction. In the case of a continuing transaction in the current business application with a valid correlation header, the SDK uses the name from the header. Do not use the following characters in transaction names:  { } [ ] | & ;
• correlation_header: A correlation header if this is a continuing transaction, else NULL. If specified, the correlation header has been generated by another AppDynamics agent and made available to this agent as a string. The correlation header provides information to enable this transaction to correlate with an upstream transaction.

appd_bt_enable_snapshot

Enables a snapshot for a given business transaction. This call can be made between the calls of appd_bt_begin() and appd_bt_end(). Returns a non-zero value if the snapshot is successfully enabled, otherwise returns a zero.

Format

APPD_API int appd_bt_enable_snapshot(appd_bt_handle bt)

Parameters

• bt: The handle to the business transaction for which the snapshot needs to be enabled.

appd_bt_end

End the given business transaction.

Format

APPD_API void appd_bt_end (appd_bt_handle  bt)

Parameters

• bt: The handle to the business transaction to end.
  

appd_bt_get

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

Format 

APPD_API appd_bt_handle appd_bt_get (const char *  guid)

Parameters

• guid: The globally unique identifier that was passed to appd_bt_store.

Returns

The handle to the business transaction associated with the given GUID.

In the following cases the SDK logs a warning and returns a handle that you may safely use in other API functions but that will cause these functions to immediately return without doing anything:

• The SDK does not find a handle associated with the GUID.
• The call ended before the SDK could retrieve the handle.

appd_bt_is_snapshotting

Reports whether the agent is currently taking a transaction snapshot. Useful before calling appd_add_user_data() or appd_bt_set_url(), since those potentially expensive functions would do nothing if called when a snapshot is not being taken.

Format

APPD_API char appd_bt_is_snapshotting (appd_bt_handle  bt)

Parameters

• bt: The handle to the business transaction to check for snapshotting. 

Returns

Non-zero if the given business transaction is taking a snapshot. Otherwise, zero. 

appd_bt_set_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 transaction 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.

Format 

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

Parameters

• bt: The business transaction to add the user data to, if it's taking a snapshot.
• url: The value of the URL for the snapshot as 7-bit ASCII or UTF-8.

appd_bt_override_start_time_ms

Takes a time, in milliseconds, representing the number of milliseconds elapsed since Jan 1, 1970 UTC. The time specified for this function overrides the default start time, which is the time at which the appd_bt_begin() API is called according to the system clock. By overriding the start time with a specific value, the BT internal start time is disabled, and the specified start time is reported to the Controller.

This function is located in the appdynamics_advanced.h file, and is only used in special cases.

Format 

APPD_API void appd_bt_override_start_time_ms(appd_bt_handle bt, unsigned int timeMS); 

Parameters

• bt: The business transaction to override the timing of
• timeMS : Time in milliseconds since start of epoch (midnight, Jan 1, 1970 UTC).

appd_bt_override_time_ms

Takes a time, in milliseconds, that overrides the business transaction response time as reported for this business transaction to the Controller. 

The C/C++ SDK maintains its own, internal timer for the response time for the business transaction. This timer reflects the elapsed time spent between the bt_begin and bt_end calls. In some cases, you may want to set the business transaction timer directly, overriding the default business transaction response timer. For instance, this may be useful for integrating external monitoring systems with AppDynamics.

It is important to note that when calling this function, the reported business transaction will be either the time you specify or the sum of all exit call timings for the transaction, whichever is greatest. This is because a business transaction cannot be reported to take less time than the total of the exit calls it contains.

This function is located in the appdynamics_advanced.h file, and is only used in special cases.

Format 

APPD_API void appd_bt_override_time_ms(appd_bt_handle bt, unsigned int timeMS); 

Parameters

• bt: The business transaction for which to set the response time.
• timeMS: The time the business transaction took, in milliseconds.

appd_bt_store

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.

Format

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

Parameters

• bt: The BT to store.
• guid: A globally unique identifier to associate with the given BT.

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());
    // ...
}

appd_bt_add_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).

Format 

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

Parameters

• bt: The handle to the business transaction to which the error is added.

• level: The error levels are APPD_LEVEL_NOTICE, APPD_LEVEL_WARNING, and APPD_LEVEL_ERROR.

• message: Error message for this error.
• mark_bt_as_error: If true, the business transaction experiencing this error is marked as an error transaction. In this case, the business transaction is counted only as an error transaction. It is not also counted as a slow, very slow or stalled transaction, even if the transaction was also slow or stalled. If false, the business transaction is not marked as an error transaction.

appd_bt_add_user_data

Attaches user data to transaction snapshots generated for the specified business transaction.

The user data is added to the business transaction but reported only when a transaction snapshot is occurring. In the Controller UI, the user data appears in the Business Data tab of the transaction snapshot details.

It is safe to call this function when a snapshot is not occurring. When the specified business transaction is not taking a snapshot, this function immediately returns.

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 actually taking a snapshot before extracting the data and calling this function.

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

Format

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

Parameters

• bt: The business transaction to add the user data to, if it's 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.

appd_backend_add

Add a declared backend to the current business application. Use appd_backend_declare to declare a backend before adding it.

This function fails if the type of the backend being added does not have at least one identifying property.

Format

APPD_API int appd_backend_add (const char *  backend)

Parameters

• backend: Pointer to the backend.

Returns

Zero on success, otherwise a non-zero value. If the return value is not zero, a log message describes the error.

appd_backend_declare

Declare the existence of a backend. Call this only if the backend is not already registered with the C++ SDK instance.

Format

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

Parameters

• type: The type of the backend, from these options: 

  • APPD_BACKEND_HTTP 

  • APPD_BACKEND_DB 

  • APPD_BACKEND_CACHE 

  • APPD_BACKEND_RABBITMQ 

  • APPD_BACKEND_WEBSERVICE

  • APPD_BACKEND_JMS 

• unregistered_name: The name of the backend. Must be unique to the C++ SDK instance.

appd_backend_prevent_agent_resolution

Call to prevent a downstream agent from resolving as this backend. If used, 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.

Format

APPD_API int appd_backend_prevent_agent_resolution (const char *  backend)

Parameters

• backend: Pointer to the declared backend.

Returns

Zero on success, otherwise a non-zero value. If the return value is not zero, a log message describes the error. 

appd_backend_set_identifying_property

Sets an identifying property of a backend. Call once for every identifying property that you want to set. Call this function after appd_backend_declare() and before appd_backend_add(). 

A backend's identifying properties uniquely identify the downstream component being called. In the Controller UI, these properties are visible in the upper right panel of the backend dashboards.

You must set at least one identifying property when you add a backend of one of the built-in exit call types. The valid properties vary by the following exit call type.

Format 

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

Parameters

• backend: Pointer to the backend.
• key: Name of the property. For example, DESTINATION or PORT.
• value: Value of the property. For example, Order Queue or 3304 

Returns

Zero on success, otherwise a non-zero value. If the return value is not zero, a log message describes the error.

appd_custom_metric_add

Report a custom metric.

Format 

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)

Parameters

• application_context: The application context for this custom metric.
• metric_path: The path of the custom metric. This path defines where the custom metric appears in the Metric Browser. Use a pipe character to separate branches in the path. For example, Custom Metrics|MyCustomMetric defines MyCustomMetric as a top-level metric in the tree.
• time_rollup_type: Specifies how to rollup metric values for this metric over time, from the following: 

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

• cluster_rollup_type: Specifies how to rollup metric values for this metric across clusters, from the following:

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

• hole_handling_type: Specifies how to handle holes—gaps where no value has been reported from this metric, from the following: 

  • APPD_HOLEHANDLING_TYPE_RATE_COUNTER: Considers the gap or 0 value to be meaningful in the aggregation of the metric.    

  • APPD_HOLEHANDLING_TYPE_REGULAR_COUNTER: Does not consider the gap or 0 value to be meaningful in the aggregation of the metric.

 For additional information on these parameters, see Create Custom Metrics. 

appd_custom_metric_report

Report a value for a given metric.

Format 

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

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.

appd_exitcall_add_error

Add an error to the exit call.

Format 

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

Parameters

• exitcall: Handle to the exit call.

• level: The level of this error are APPD_LEVEL_NOTICE, APPD_LEVEL_WARNING, and APPD_LEVEL_ERROR.

• message: Error message for this error.
• mark_bt_as_error: If true, the business transaction making the exit call that is experiencing this error is marked as an error transaction. In this case, the business transaction is counted only as an error transaction. It is not also counted as a slow, very slow or stalled transaction, even if the transaction was also slow or stalled. If false, the business transaction is not marked as an error transaction.

appd_exitcall_begin

Start an exit call to the specified backend as part of a business transaction.

Format

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

Parameters

• bt: Handle to the business transaction making the exit call.
• backend: The destination backend of the exit call. AppDynamics does not automatically detect backends for Go applications, so you must specify the destination backend.

Returns

An opaque handle to the exit call that was started. 

appd_exitcall_end

Complete the exit call.

Format 

APPD_API void appd_exitcall_end (appd_exitcall_handle  exitcall) 

Parameters

• exitcall: Handle to the exit call being ended.

appd_exitcall_get

Get a handle to an exit call associated with a GUID via appd_exitcall_store().

Format 

APPD_API appd_exitcall_handle appd_exitcall_get (const char * guid) 

Parameters

• guid: The globally unique identifier that was passed to appd_exitcall_store().

Returns

The handle to the exit call associated with the given GUID.

In the following cases, the SDK logs a warning and returns a handle that you may safely use in other API functions but that will cause these functions to immediately return without doing anything:

• The SDK doesn't find a handle associated with the GUID.
• The call ended before the SDK could retrieve the handle.

appd_exitcall_get_correlation_header

Get the header for correlating a business transaction. 

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

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

Format 

APPD_API const char* appd_exitcall_get_correlation_header (appd_exitcall_handle  exitcall) 

Parameters

• exitcall: Handle to the exit call.

Returns

On success returns a 7-bit ASCII string containing the correlation information. You can inject this string into the exit call's payload. A downstream agent can then extract the header from that payload and continue the business transaction.

On error, returns the default header that prevents downstream business transaction detection. 

appd_exitcall_override_start_time_ms

Takes a time, in milliseconds, representing the number of milliseconds elapsed since Jan 1, 1970 UTC. The time specified for this function overrides the default start time, which is the time at which the appd_exitcall_begin() API is called according to the system clock. By overriding the start time with a specific value, the exit call's internal start time is disabled, and the specified start time is reported to the Controller.

 This function is located in the appdynamics_advanced.h file, and is only used in special cases.

Format 

 APPD_API void appd_exitcall_override_time_ms(appd_exitcall_handle exitCall, int64_t timeMS);

Parameters

• exitCall: The exit call for which to override the start time
• timeMS: The time that you want to override the exit call start time

appd_exitcall_override_time_ms

Takes a time, in milliseconds, that overrides the exit call time reported to the Controller. 

The C/C++ SDK maintains its own internal timer for the time it takes to complete the exit call. In some cases, you may want to disable the exit call's internal timer. For instance, this can be useful for reporting exit calls that are recorded in external monitoring systems and read into an SDK program.

This function is located in the appdynamics_advanced.h file, and is only used in special cases.

Format 

APPD_API void appd_exitcall_override_time_ms(appd_exitcall_handle exitCall, int64_t timeMS);

Parameters

• exitCall: The exit call for which to set the completion time
• timeMS: The time that you want to override the exit call time.

appd_exitcall_set_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. This data is then visible in the exit calls details UI for the transaction snapshot.

Format 

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

Parameters

• exitcall: Handle to the exit call.
• details: An arbitrary string to add to the exit call.

Returns

Zero on success, otherwise a non-zero value. If the return value is not zero, a log message describes the error.

appd_exitcall_store

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 BT containing it) ends.

Format 

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

Parameters

• exitcall: The exit call to store.
• guid: A globally unique identifier to associate with the given call.

Example 

appd_exitcall_handle ec = appd_exitcall_begin(bt, "authdb");
appd_exitcall_store(ec, "login-exit");

appd_frame_begin

Records the start of a method call in the call stack. To track the duration of your method call, you must call appd_frame_begin near the start of the method code, and appd_frame_end when the method returns.

Format 

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, unsigned int line_number); 

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. This value cannot be NULL.
• method_name: The name of the method. This value cannot be NULL.
• 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 occurred.

appd_frame_end

Records the end of a method call in the call stack. To track the duration of your method call, you must call appd_frame_begin near the start of the method code, and appd_frame_end when the method returns.

Format 

APPD_API void appd_frame_end(appd_bt_handle bt, appd_frame_handle frame); 

Parameters

• bt: The business transaction for the call graph.
• frame: The handle of returned by the corresponding appd_frame_begin call.

Environment Variables

You can configure the following environment variables for the C/C++ SDK.