Use the Go SDK to instrument Google Go applications. The API includes functions for creating business transactions, transaction backends, exit points, and so on. See Use Go SDK.

Basic Types

The Go SDK defines these opaque types:

• BtHandle: A handle to an active business transaction
• ExitcallHandle: A handle to an active exit call

Config Struct

The Config struct contains settings used by the agent to connect to the Controller. The structure serves an equivalent function of the agent configuration files described in Agent-to-Controller Connections. 

The Config struct is defined as follows:

type Config struct {
    AppName, TierName, NodeName string
    Controller Controller
    InitTimeoutMs int
    Initialized uint // a special field used by the underlying AppDynamics libraries. Do not use.
    Logging LoggingConfig
    UseConfigFromEnv bool
    EnvVarPrefix string
}

The structure is made up of these fields:

• AppName: Name of the business application to which this node belongs. 
• TierName: Name of the tier to which this node belongs. A tier is a group of identical or similar nodes. An originating tier is the tier that receives the first request of a business transaction. A downstream tier is a tier that is called from another tier, thus continuing a business transaction.
• NodeName: The monitored application server to be monitored by this agent.

• Controller: Connection settings for the Controller. This struct is defined as: 

  type Controller struct { Host string Port uint16 Account, AccessKey string UseSSL bool HTTPProxy HTTPProxy CertificateFile CertificateDir }

  The Controller struct contains these fields:

  • Host: Controller host.
  • Port: Controller port; defaults to 8080.
  • Account: Name of your account.
  • Access_key: Key to your account. To find your access key, click the settings (gear) icon in the upper right corner of the Controller UI, then click License.
  • UseSSL: Enable SSL communication with the controller; the default is false. Set to true to enable. If you set UseSSL to true, the default certificate, ca-bundle.crt, is used. To use your own certificate, specify your certificate file and directory in the CertificateFile and CertificateDir parameters.
  • HTTPProxy:  If the agent needs to connect to the Controller via a local HTTP proxy, use this struct to specify connection settings for the proxy. 
  • CertificateFile : The file name of the SSL certificate.
  • CertificateDir – The directory where the certificate is located.

• InitTimeoutMs: The initialization function, InitSDK relies on the Controller configuration to start business transactions. To prevent the initialization function from blocking your application, you can use this setting. It lets you instruct InitSDK whether to wait for the Controller configuration and if so how long to wait before starting business transactions. Valid values are:

  • N: Wait for up to N milliseconds for the Controller configuration.

  • 0: Do not wait for the Controller configuration. This is the default.

  • -1: Wait indefinitely until the Controller configuration is received by the agent.

• Logging: Logging settings for the controller. This struct is defined as:

  const ( APPD_LOG_LEVEL_DEFAULT LogLevel = iota APPD_LOG_LEVEL_TRACE APPD_LOG_LEVEL_DEBUG APPD_LOG_LEVEL_INFO APPD_LOG_LEVEL_WARN APPD_LOG_LEVEL_ERROR APPD_LOG_LEVEL_FATAL ) type LoggingConfig struct { BaseDir string MinimumLevel LogLevel MaxNumFiles uint MaxFileSizeBytes uint }

  The Logging struct contains these fields:

  • BaseDir: The absolute path to the directory where log files are written. If left empty, the default is /tmp/appd.
  • MinimumLevel: One of the APPD_LOG_LEVEL_xxx constants that are shown above. The default is APPD_LOG_LEVEL_INFO.
  • MaxNumFiles: The maximum number of logging files to store on disk. Once this maximum is hit, older logs are rotated out.
  • MaxFileSizeBytes: The maximum size of the log files before they are rotated.
• UseConfigFromEnv: Set to true if you want the SDK to check for any configuration environment variables and use those configuration values for initialization. Note that because this happens on initialization, the environment variable settings override the configuration you set in your program.
• EnvVarPrefix: If UseConfigFromEnv is set to true, use this property to specify the prefix to use for environment variable names. The default prefix is APPD_SDK.
  

If the agent needs to connect to the Controller via a local HTTP proxy server, you need to configure the settings for the proxy server. You can do so using the HTTPProxy struct, defined as follows:

type HTTPProxy struct {
    Host string
    Port uint16
    Username, PasswordFile string
}

The HTTPProxy struct has the following fields: 

• Host: Hostname or IP address of the HTTP proxy server
• Port: Port of the proxy server
• Username: Proxy server user name
• PasswordFile: Proxy server password file

ContextConfig Struct

You use the ContextConfig struct for calls that apply to multi-tenant Controller environments. 

type ContextConfig struct {
    AppName string
    TierName string
    NodeName string
}

The ContextConfig struct has these fields:

• AppName: Name of the business application to which this node belongs. 
• TierName: Name of the tier to which this node belongs. A tier is a group of identical or similar nodes. An originating tier is the tier that receives the first request of a business transaction. A downstream tier is a tier that is called from another tier, thus continuing a business transaction.
• NodeName: The monitored application server to be monitored by this agent.

AddAppContextToConfig

Add application context to the configuration for a multi-tenant Controller.

Format 

func AddAppContextToConfig(cfg *Config, context string, contextCfg *ContextConfig) error 

Parameters

• cfg: configuration object. 
• context: A unique identifier used to refer to this context. 
• contextCfg: A context configuration object indicating the business application, tier, and node name for this context.

InitSDK

Initialize the Go SDK. An instrumented application must call this function once, preferably during application startup.

Format 

func InitSDK(cfg *Config) error 

Parameter

cfg: configuration settings that enable communication between the agent and the Controller.

Returns

nil on success, otherwise an error value

TerminateSDK

Stop the Go SDK. Ends all active business transactions for this agent and stops agent metric reporting to the Controller.

Format 

func TerminateSDK() 

StartBT

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. Unlike transactions discovered by other types of agents, business transactions that exceed the limit that are reported by the Go SDK are not 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 

func StartBT(name, correlation_header string) BtHandle  

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

StartBTWithAppContext

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

Format

func StartBTWithAppContext(context, name, correlation_header string) BtHandle 

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

EndBT

End the given business transaction.

Format

func EndBT(bt BtHandle) 

Parameter

bt: The handle to the business transaction to end.

GetBT

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

Format 

func GetBT(guid string) BtHandle 

Parameter

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 doesn't find a handle associated with the guid
• The call ended before the SDK could retrieve the handle

IsBTSnapshotting

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

Format

func IsBTSnapshotting(bt BtHandle) bool 

Parameter

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

Returns

true if the given business transaction is taking a snapshot. Otherwise, false. 

SetBTURL

Set the URL for a snapshot, if one is being taken. 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 IsBTSnapshotting to check if the business transaction is snapshotting before extracting the data and calling this function. The url argument data should be either 7-bit ASCII or UTF-8.

Format 

func SetBTURL(bt BtHandle, url string)

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.

StoreBT

Store a BT handle in a global registry to retrieve later with GetBT. This is convenient when you need to start and end a business transaction in separate places, and it is difficult to pass the handle to the business transaction through the parts of the code that need it.

When the business transaction is ended, the handle is removed from the global registry.

Format

func StoreBT(bt BtHandle, guid string) 

Parameters

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

AddBTError

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 

func AddBTError(bt BtHandle, level ErrorLevel, message string, mark_bt_as_error bool) 

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.

AddUserDataToBT

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 USER 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 IsBTSnapshotting to check if the business transaction is actually taking a snapshot before extracting the data and calling this function.

The data in the value argument should be either 7-bit ASCII or UTF-8.

Format

func AddUserDataToBT(bt BtHandle, key, value string) 

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.

AddBackend

Add a backend to the business application. 

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

Format

func AddBackend(name, backendType string, identifyingProperties map[string]string, resolve bool) error  

Parameters

• name: The name of the backend. Must be unique to the Go SDK instance.
• backendType: 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 

• identifyingProperties:  A map of key/value pairs that contain the backend's identifying properties. The properties uniquely identify backend. In the Controller, these properties appear 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 Type	Valid 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"

  For example, a key PORT would have a value of 3304. 

• resolve:  Set the property to false to prevent a downstream agent from resolving as this backend.
  If true, the default, an agent that detects a correlation header for an unresolved backend resolves itself as that backend. However, if the backend is actually an uninstrumented tier that is passing through the correlation header—for example, a message queue or proxy—you may wish the backend to show up distinct from the tier that it routes to. If false, correlation headers generated for exit calls to this backend will instruct downstream agents to report as distinct from the backend.

  For example, if you have Tier A connecting to uninstrumented Backend B, which routes to instrumented Tier C, the setting affects the flow map as follows: 

  • True, the flow map will be A > C. 

  • False, the flow map will be A > B > C.

Returns

nil on success, otherwise an error value

AddExitcallError

Add an error to the exit call.

Format 

func AddExitcallError(exitcall ExitcallHandle, level ErrorLevel, message string, mark_bt_as_error bool)  

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

StartExitcall

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

Format

func StartExitcall(bt BtHandle, backend string) ExitcallHandle  

Parameters

• bt: Handle to the business transaction making the exit call.
• backend:The destination backend of the exit call. 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. 

EndExitcall

Complete the exit call.

Format 

func EndExitcall(exitcall ExitcallHandle) 

Parameter

exitcall: Handle to the exit call being ended.

GetCRollupType

Specify how to roll up values for the metric over time.

Format 

func GetCRollupType(rollUp RollupType)

Parameters

• rollUp: The approach for rolling up metrics. The following roll-up options are valid: 
  • APPD_TIMEROLLUP_TYPE_AVERAGE: The average of all metric values across each node in the tier.
  • APPD_TIMEROLLUP_TYPE_SUM: Sum of all reported values in the minute.
  • APPD_TIMEROLLUP_TYPE_CURRENT: The last reported metric in the minute.

GetCClusterRollupType

Specify how to aggregate metric values for the tier (a cluster of nodes).

Format 

func GetCClusterRollupType(rollUp ClusterRollupType)

Parameters

• rollUp: The approach for rolling up metrics. The following roll-up options are valid: 
  • APPD_CLUSTERROLLUP_TYPE_INDIVIDUAL: The average of all metric values across each node in the tier.
  • APPD_CLUSTERROLLUP_TYPE_COLLECTIVE: The sum of all metric values for all the nodes in the tier.

GetExitcall

Get a handle to an exit call associated with a guid via StoreExitcall.

Format 

func GetExitcall(guid string) ExitcallHandle 

Parameter

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

GetExitcallCorrelationHeader

Get the header for correlating a business transaction. 

If a business transaction makes exit calls that you want to correlate across, retrieve the correlation header using this function 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 

func GetExitcallCorrelationHeader(exitcall ExitcallHandle) string  

Parameter

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 payload of the exit call. 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.

SetExitcallDetails

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 

func SetExitcallDetails(exitcall ExitcallHandle, details string) error  

Parameters

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

Returns

Nil on success, otherwise an error value

StoreExitcall

Store an exit call handle in a global registry for later retrieval with GetExitcall. This is useful when you need to start and end a 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 

func StoreExitcall(exitcall ExitcallHandle, guid string)  

Parameters

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

Example 

ExitcallHandle ec = StartExitcall(bt, "authdb");
StoreExitcall(ec, "login-exit");