On this page:
About Go Application Instrumentation
The following topics provide a general outline of how to implement instrumentation in your Go application:
- Import the AppDynamics API File to the Application
- Initialize the Controller Configuration
- Initialize the Agent
- Create Business Transactions
- Manage Business Transaction Snapshots
- Create Backends
- Manage Exit Calls
- Correlate with Other Business Transactions
- Terminate the Agent
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 'Agent Configuration Settings' in Go SDK Reference for a complete list of the settings and information about which ones are required.
In your application, assign values to the required settings. 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 -1 instructs 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 BT or adding custom metrics. See Go SDK Reference for more about
() and related methods.
Initialize the Agent
In your main function, initialize the agent by passing the configuration structure to
InitSDK() returns nil, the agent is initialized successfully. If an error returns, it is likely because the agent could not reach the Controller.
The following example illustrates how to initialize the SDK:
Create Business Transactions
Define a Business Transaction by enclosing the code that constitutes the request that 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
GetExitcallCorrelationHeader()in the Go SDK Reference. 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
The following shows an example of setting 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 APPD_LEVEL_NOTICE, APPD_LEVEL_WARNING or APPD_LEVEL_ERROR.
Manage Business Transaction Snapshots
When the agent is monitoring a Business Transaction, it automatically creates Transaction Snapshots, which describe instances of the Business Transaction at certain points in time. Transaction snapshots are extremely useful for troubleshooting poor performance because they contain a lot of detail.
You do not have to modify anything to create these snapshots, other than creating the Business Transaction, 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
The agent is not always collecting snapshots, because that would be expensive. By default, it collects a snapshot every ten minutes, but this schedule is configurable. See 'Configure Snapshot Periodic Collection Frequency' in Transaction Snapshots for information about the frequency.
You can determine if a snapshot is happening using
IsBTSnapshotting(), which returns
true if the agent is collecting a snapshot. The main reason to do this is to avoid the wasted overhead for collecting user data for a snapshot or setting the snapshot URL if no snapshot is currently 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 AppDynamics 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 AppDynamics 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
Just before the application exits, terminate the agent.