This page provides instructions and an overview of the GO SDK, which provides routines for creating and managing Business Transactions, Transaction Snapshots, backends, and exit calls in AppDynamics.
Before You Begin
Import the AppDynamics Package to the Application
After downloading the SDK, you are ready to add AppDynamics instrumentation to your Go application. The first step is to import the AppDynamics package:
Initialize the Controller Configuration
Controller information settings permit the SDK to connect to the Controller. Some settings are required for all applications while others are required only for certain types of application environments. For example, if the SDK needs to connect to the Controller via an internal proxy in your network, set up the connection settings for the proxy. See Go SDK Reference for a complete list of settings and which ones are required.
Assign values to the required settings in your application. For example, to set the Controller connection information:
InitTimeoutMs field. Once you initialize the configuration, you pass the configuration object to the call to initialize the agent via
InitTimeoutMs field can have these values:
- When set to
0, the default, the
InitSDK()function operates as an asynchronous action, so that the initialization call does not block your program.
- Setting the value to
-1instructs the program to wait indefinitely until the controller configuration is received by the agent, that is, the
()method returns control. This is useful when you want to capture short-running Business Transactions that occur at application startup and you do not mind the delay of waiting for the Controller to send the configuration.
- Alternatively, set it to a specific number of milliseconds to wait.
If you use a multi-tenant Controller (SaaS or on-premises multi-tenant), you need to create the context for the multi-tenant environments using the
AddAppContextToConfig() method. You can then pass the context as a parameter to methods for performing particular operations, such as starting a Business Transaction or adding custom metrics. See Go SDK Reference for
() and related methods.
Initialize the Agent
Initialize the agent by passing the configuration structure to
InitSDK() in your main function.
nil, the agent is initialized successfully. If an error returns, it is likely because the agent could not reach the Controller.
For example, to initialize the SDK:
Create Business Transactions
Define a Business Transaction by enclosing the code that constitutes the request you want to monitor between
StartBT() returns a handle to use in subsequent routines that affect that business transaction.
If you are creating a Business Transaction that correlates with an upstream Business Transaction, pass the correlation header of the upstream transaction so the new transaction that you are creating can correlate with it. See Go SDK Reference for
GetExitcallCorrelationHeader(). If the transaction does not need to correlate with another transaction, pass an empty string for the correlation header parameter.
You can optionally store the Business Transaction handle in the global handle registry with a GUID for easy retrieval later using
StoreBT(). Retrieve the handle from the global handle registry
For example, to set a Business Transaction:
Between starting and ending the transaction, you can perform operations such as adding errors to the business transaction, defining the transaction snapshot attributes, adding backends and exit calls, and so on.
When the business transaction ends via a call to
EndBT(), the agent stops reporting metrics for the business transaction.
Add Business Transaction Errors
AddBTError() to report Business Transaction errors. If you set this function's
markBTAsError parameter, the transaction is reported as an Error Transaction when the error occurs.
The SDK provides constants classifying the error level as
Manage Business Transaction Snapshots
The agent automatically creates Transaction Snapshots when monitoring a Business Transaction. Transaction snapshots are useful for troubleshooting poor performance because they describe instances of the business transaction at certain points in time.
Other than creating the Business Transaction, you do not have to modify anything to create these snapshots, but you can add calls to:
- Find out if a snapshot is being taken
- Provide additional data in a snapshot
- Set the URL for a snapshot
Determine if the Agent is Taking a Snapshot Now
Due to high cost, the agent does not constantly collect snapshots. By default, it collects a snapshot every ten minutes, but this schedule is configurable. See Configure Snapshot Periodic Collection Frequency.
You can determine if a snapshot is happening using
IsBTSnapshotting(), which returns
true if the agent is collecting a snapshot. This method avoids wasted overhead in collecting user data for a snapshot or setting the snapshot URL if no snapshots are being collected.
Add Business Transaction User Data
You can optionally add data to transaction snapshots. For example, you might want to know which users are getting a lot of errors, or from which regions users are experiencing slow response times, or which methods are slow. In the Controller UI, the data appears in the USER DATA tab of the transaction snapshot.
If a snapshot is occurring, use
AddUserDataToBT() passing a key and value for the data that you want the snapshot to collect.
Add Snapshot URL
If a snapshot is occurring, you can set a URL for the current snapshot using
Set Snapshot Example
A backend is a database or a remote service such as a message queue, HTTP service, or cache service that your application uses. A backend component is not itself monitored by the application agent, but the agent monitors calls to it from instrumented servers. You need to create backends in the instrumented environment so that the agent registers them. Creating and adding the backend to the instrumented application involves:
- Naming the backend
- Setting its identifying properties
- Optionally, configuring how the backend is presented in the Controller UI
A backend has identifying properties. These vary depending on the type of the backend and the types of information that you want to display. The Controller displays identifying properties in backend dashboards. You must set at least one identifying property for the type of any backend that you plan to add.
The following shows the backend properties in the Controller UI for an Oracle database:
Resolve to a Tier
The following listing shows an example of setting up a database backend.
Manage Exit Calls
When an application makes a call to another component, such as a detected backend or another application server, the agent reports metrics on those calls.
Define an exit call by enclosing the code that constitutes the exit call between
StartExitcall() returns a handle to use in subsequent routines that affect that exit call. An exit call occurs in the context of a Business Transaction.
You can optionally store the exit call handle in the global handle registry with a guid for easy retrieval later using
StoreExitcall(). Retrieve the handle from the global handle registry
You can optionally add details to an exit call as any arbitrary string with
SetExitcallDetails(). The details are reported in the exit call details in the transaction snapshots in the Controller UI:
You can also add errors to an exit call using
AddExitcallError(). Use the enum for the error levels. You can also add an error message.
Simple Exit Call Example
Correlate with Other Business Transactions
A correlation header contains the information that enables the agents to continue the flow of a Business Transaction across multiple tiers.
An SDK agent can correlate with other SDK agents as well as other AppDynamics agents, such as Java, .NET, or PHP, that perform automatic correlation for certain types of entry and exit points.
Correlate with an Upstream Tier
When your instrumented process receives a continuing transaction from an upstream agent that supports automatic correlation:
Using a third-party
Header.Get()function, extract the header named
APPD_CORRELATION_HEADER_NAMEfrom the incoming HTTP payload.
Pass the header to
StartBT(). For example:
If the header retrieved by the
Header.Get() function is valid, the business transaction started by the
StartBT() call will be a continuation of the Business Transaction started by the upstream service.
Correlate with a Downstream Tier
The downstream agent is watching for a correlation header named
singularityheader in the HTTP payload.
If your SDK agent is making an exit call to a downstream agent that supports automatic correlation:
- Set the name of the correlation header using
- Begin the exit call.
- Retrieve the correlation header from the exit call using the
- Using third-party HTTP functions, prepare an HTTP POST request.
- Inject a header named
APPD_CORRELATION_HEADER_NAMEwith the value of the correlation header retrieved in Step 3 into the outgoing payload of the HTTP request.
Make the request. For example:
Terminate the Agent
Terminate the agent right before the application exits: