On this page:

Related pages:

Your Rating:
Results:
PatheticBadOKGoodOutstanding!
16 rates

To instrument C and C++ applications, you use the C/C++ Agent API. The API includes functions for creating business transactions, transaction backends and exit points, and defining custom metrics. 

This page describes the functions and structures defined in the API. 

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_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, APP_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: Host name 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
  • cfgAppDynamics configuration object.
  • int: Set to a non-zero integer to enable flushing metrics to the Controller. Default is 0.

Setting this flag means the appd_sdk_term() blocks until the underpinning agent logic has completely uploaded the metric data. Not using this flag means that any metrics collected since the last Controller update will be discarded. Flushing the metrics can take anywhere between 60 and 120 seconds (on an average), and under certain circumstances longer, depending on the load on the Controller. 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
  • cfgAppDynamics configuration object
  • LOGGING_MIN_LEVEL – Minimum level of logging that's 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
  • cfgAppDynamics 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

  • cfgAppDynamics 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
  • cfgAppDynamics 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
  • cfgAppDynamics 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
  • cfgAppDynamics 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_cfgAn 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_cfgAn 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_cfgAn 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_cfgAn 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 host name 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_cfgAn 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 host name 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_cfgAn 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_cfgAn 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_cfgAn 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_cfgAn 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_cfgAn 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_cfgAn AppDynamics context configuration object indicating the business application, tier and node name for this context.
  • dir: Full path to the certificate files.

appd_sdk_init

Initialize the AppDynamics C/C++ agent. 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 AppDynamics C/C++ agent. 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. This means that it's up to you to ensure that your agent does not create excessive business transactions. Use care to ensure 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_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 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.

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++ Agent 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 level, from the following: 
    • APPD_LEVEL_NOTICE

    • APPD_LEVEL_WARNING

    • 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 per exit call type as indicated below.

Exit Call TypeValid Identifying Properties

APPD_BACKEND_HTTP

"HOST", "PORT", "URL", "QUERY STRING"
APPD_BACKEND_DB"HOST", "PORT", "DATABASE", "VENDOR", "VERSION"
APPD_BACKEND_CACHE"SERVER POOL", "VENDOR"
APPD_BACKEND_RABBITMQ"HOST", "PORT", "ROUTING KEY", "EXCHANGE"
APPD_BACKEND_WEBSERVICE"SERVICE", "URL", "OPERATION", "SOAP ACTION", "VENDOR"
APPD_BACKEND_JMS"DESTINATION", "DESTINATIONTYPE", and "VENDOR"
APPD_BACKEND_WEBSPHEREMQ"HOST", "PORT", "DESTINATION", "DESTINATIONTYPE", "MAJOR VERSION", "VENDOR"
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

Define 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. For more about defining the custom metric path, see the 'Metric Path' section in Build a Monitoring Extension Using Java.   
  • 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. Use one of these options: 
    • 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 the topic on creating custom metrics in Using the C/C++ Agent SDK

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, from the following: 
    • APPD_LEVEL_NOTICE

    • APPD_LEVEL_WARNING

    • APPD_LEVEL_ERROR

  • message: Error message for this error.
  • mark_bt_as_errorIf 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++ Agent 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 (New in 4.5.1)

Records the start of a method call in the call stack. To track the duration of your method call, you must call appd_frame_beginnear the start of the method code, and appd_frame_endwhen 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. If not, then set to 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 occurred.

appd_frame_end (New in 4.5.1)

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.

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

An RAII (Resource Acquisition Is Initialization) pattern constructor for C++ applications. For a new business transaction, this constructor creates the business transaction object and a handle to that object. Continues existing transactions. Adds the correlation header if one is passed.

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

See 'APIs for Resource Management (C++)' in Using the C/C++ Agent SDK for more information.

Format 

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

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

appd:sdk::ExitCall

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

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

An ExitCall object cannot be copied.

See 'APIs for Resource Management (C++)' in Using the C/C++ Agent SDK for more information.

Format 

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

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

appd::sdk::Frame (New in 4.5.1) 

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

Format 

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

Parameters
  • bt: The BT object that owns this function call
  • frame_type: The type of the frame. When used in C 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.

Environment Variables

You can configure the following environment variables for the C++ agent.

Environment VariableValue
APP_NAMEName of the application
CONTROLLER_ACCESS_KEYAccess key for connecting to the Controller
CONTROLLER_ACCOUNTAccount name for connecting to the Controller
CONTROLLER_HOSTHostname of the Controller
CONTROLLER_PORTPort number on which the controller is listening.
CONTROLLER_HTTP_PROXY_HOSTHostname of the HTTP proxy if using an HTTP proxy to talk to Controller
CONTROLLER_HTTP_PROXY_PASSWORDThe password for connecting to the HTTP proxy
CONTROLLER_HTTP_PROXY_PASSWORD_FILEFile containing password to connect to the HTTP proxy with
CONTROLLER_HTTP_PROXY_PORTPort number of the HTTP proxy
CONTROLLER_HTTP_PROXY_USERNAMEUsername to connect to the HTTP proxy with
CONTROLLER_USE_SSL (optional)

To disable SSL, set to off0f, or false.
To enable SSL, set to on1t, or true.

CONTROLLER_CERTIFICATE_FILEThe SSL certificate file name for connecting to the Controller
CONTROLLER_CERTIFICATE_DIRThe directory where the SSL certificate is located
FLUSH_METRICS_ON_SHUTDOWN

To enable metric flushing before shutdown, set to a non-zero integer.
To disable metric flushing before shutdown, set to 0 (default).

INIT_TIMEOUT_MSNumber of milliseconds that you want appd_sdk_init, an asynchronous action, to wait until it has received Controller configuration and is ready to capture business transactions.

LOGGING_LOG_DIR

The directory that the logs are saved to
LOGGING_LEVELThe level of severity for which activity is logged. Options: all, trace, debug, info, warn, error
LOGGING_MAX_NUM_FILESThe maximum number of log files that can be saved
LOGGING_MAX_FILE_SIZE_BYTESThe maximum log file size that can be saved
NODE_NAMEName of the node
TIER_NAMEName of the tier
UNIQUE_HOST_ID (optional)The identifier of the physical host or virtual machine that the agent is installed on.

 

 

  • No labels