appdynamics

package
v0.1.15 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 19, 2019 License: Apache-2.0 Imports: 5 Imported by: 0

README

AppDynamics SDK for Go

The AppDynamics SDK for Go allows you to add instrumentation to your Go applications and services. The SDK is shipped as a package containing a Cgo wrapper around the AppDynamics SDK for C/C++. The Go SDK and other AppDynamics agents and products are available from the AppDynamics Download site. For up-to-date installation instructions and documentation, see the AppDynamics Documentation Site.

Installation

To install, extract the Golang SDK in to your GOPATH (see the GOPATH documentation to learn how to set it or for the default value on your platform).

Usage

After installation, the appdynamics package is available to import into your program. It's typical to alias it as appd for simplicity:

import appd "appdynamics"

Before you can use the AppDynamics Golang SDK, you need to initialize the SDK with the required configuration:

cfg := appd.Config{}

cfg.AppName = "exampleapp"
cfg.TierName = "orderproc"
cfg.NodeName = "orderproc01"
cfg.Controller.Host = "my-appd-controller.example.org"
cfg.Controller.Port = 8080
cfg.Controller.UseSSL = true
cfg.Controller.Account = "customer1"
cfg.Controller.AccessKey = "secret"
cfg.InitTimeoutMs = 1000  // Wait up to 1s for initialization to finish

InitSDK(&cfg)

Afterwards, you can report business transactions using the StartBT and EndBT calls:

for i := 0; i < 1000; i++ {
    bt := StartBT("my bt", "")
    DoSomeWork()
    EndBT(bt)
}

It's ideal to use the Golang SDK in long running programs. To minimize network traffic, the SDK rolls up the metrics its observed over a sliding window before reporting. If a program terminates too soon, you may not see the metrics.

See the documentation for full usage instructions.

Documentation

Index

Constants

View Source 
const (
	APPD_BACKEND_HTTP       = "HTTP"
	APPD_BACKEND_DB         = "DB"
	APPD_BACKEND_CACHE      = "CACHE"
	APPD_BACKEND_RABBITMQ   = "RABBITMQ"
	APPD_BACKEND_WEBSERVICE = "WEBSERVICE"
	APPD_BACKEND_JMS        = "JMS"
)

Valid backend types to pass to AddBackend()

View Source 
const APPD_CORRELATION_HEADER_NAME string = "singularityheader"

The required name of the correlation header.

Other AppDynamics agents perform automatic correlation for certain types of entry and exit points by looking for a correlation header in the payload with this name.

Upstream Correlation ====================

When your SDK instrumented process receives a continuing transaction from an upstream agent that supports automatic correlation, extract the header named APPD_CORRELATION_HEADER_NAME from the incoming payload and pass it to StartBT(): 

string hdr = req.Header.Get(APPD_CORRELATION_HEADER_NAME);
BtHandle bt = StartBT("fraud detection", hdr);

If the header retrieved by the req.Header.Get() function is valid, the BT started on the second line will be a continuation of the business transaction started by the upstream service.

Downstream Correlation ======================

If you are making an exit call where a downstream agent supports automatic correlation, inject a header named APPD_CORREATION_HEADER_NAME into the outgoing payload. The value of the header is retrieved using the GetExitcallCorrelationHeader() function: 

ExitcallHandle inventory = StartExitcall(bt, "inventory");
string hdr = GetExitcallCorrelationHeader(inventory);
client := &http.Client{}
req, err := http.NewRequest("POST", "https://inventory/holds/sku123123")
req.Header.Add(APPD_CORRELATION_HEADER_NAME, hdr)
resp, err := client.Do(req)

In this example, the http functions (import "net/http") are used to make an HTTP POST request with an HTTP header containing the correlation header as retrieved by GetExitcallCorrelationHeader(). The header is given the name APPD_CORRELATION_HEADER_NAME. A downstream agent that supports automatic correlation for HTTP entry points will automatically extract the correlation header and perform distributed transaction tracing.

Variables

This section is empty.

Functions

func AddAppContextToConfig 

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

Add application context to AppDynamics configuration for multi-tenancy.

func AddBTError 

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

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

func AddBackend 

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

Adds a backend with the given name, type, and identifying properties. Returns an error on failure.

The resolve parameter: 

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 set resolve to false, 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 set resolve to true,
the flow map will be A -> C. If you set resolve to false, the flow
map will be A -> B -> C.

func AddCustomMetric 

func AddCustomMetric(applicationContext, metricPath string, rollup RollupType,
	clusterRollUp ClusterRollupType, holeHandling HoleHandlingType)

Define a custom metric. The API takes ApplicationContext, MetricPath, RollupType which specifies how to rollup metric values for this metric over time, e.g., to compute the average over time, pass APPD_TIMEROLLUP_TYPE_AVERAGE, ClusterRollUp which specifies how to rollup metric values for this metric across clusters and HoleHandlingType which specifies how to handle holes (gaps where no value has been reported from this metric

func AddExitcallError 

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

Add an error to the exit call.

func AddUserDataToBT 

func AddUserDataToBT(bt BtHandle, key, value string)

Add user data to a snapshot (if one is being taken).

User data is added to a snapshot if one is occurring. Data should be 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 IsBTSnapshotting() to check if the business transaction is snapshotting before extracting the data and calling this function.

func EndBT 

func EndBT(bt BtHandle)

End the given business transaction.

func EndExitcall 

func EndExitcall(exitcall ExitcallHandle)

Complete the exit call.

func GetCClusterRollupType 

func GetCClusterRollupType(rollUp ClusterRollupType) C.enum_appd_cluster_rollup_type

func GetCErrorLevel 

func GetCErrorLevel(level ErrorLevel) C.enum_appd_error_level

translates the Go "enum" to the C equivalent in appdynamics.h

func GetCHoleHandlingType 

func GetCHoleHandlingType(counter HoleHandlingType) C.enum_appd_hole_handling_type

func GetCRollupType 

func GetCRollupType(rollUp RollupType) C.enum_appd_time_rollup_type

func GetExitcallCorrelationHeader 

func GetExitcallCorrelationHeader(exitcall ExitcallHandle) string

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 C string that is returned from the C.appd_get_exitcall_get_correlation_header() is freed when the exit call ends. Do not free it yourself.

Returns a 7-bit ASCII string containing the correlation information. 

You can inject this into your payload for an exit call. An
agent on the other end can then extract the header from your
payload and continue the business transaction. On error, a
message is logged and the default header that prevents
downstream bt detection is returned.

func InitSDK 

func InitSDK(cfg *Config) error

Initializes the AppDynamics SDK. Returns an error on failure.

func IsBTSnapshotting 

func IsBTSnapshotting(bt BtHandle) bool

Returns true if the business transaction is taking a snapshot, otherwise false.

func ReportCustomMetric 

func ReportCustomMetric(applicationContext, metricPath string, value int64)

Report a value for a given metric. API takes ApplicationContext, MetricPath and the the value to report for the metric. The way the value is aggregated is specified by the roll-up parameters to `AddCustomMetric`

func SetBTURL 

func SetBTURL(bt BtHandle, url string)

Set URL for a snapshot (if one is being taken).

URL is set for a snapshot if one is occurring. Data should be 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 IsBTSnapshotting() to check if the business transaction is snapshotting before extracting the data and calling this function.

func SetExitcallDetails 

func SetExitcallDetails(exitcall ExitcallHandle, details string) error

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. Returns an error on failure.

func StoreBT 

func StoreBT(bt BtHandle, guid string)

func StoreExitcall 

func StoreExitcall(exitcall ExitcallHandle, guid string)

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.

func TerminateSDK 

func TerminateSDK()

Types

type BtHandle 

type BtHandle uint64

func GetBT 

func GetBT(guid string) BtHandle

// Get a BT handle associated with the given guid by StoreBT.

func StartBT 

func StartBT(name, correlation_header string) BtHandle

Starts a business transaction. Returns an opaque handle for the business transaction that was started

func StartBTWithAppContext 

func StartBTWithAppContext(context, name, correlation_header string) BtHandle

type ClusterRollupType 

type ClusterRollupType int

Specifies how to aggregate metric values for the tier (a cluster of nodes). APPD_CLUSTERROLLUP_TYPE_INDIVIDUAL – Aggregates the metric value by averaging the metric values across each node in the tier. For example, "Hardware Resources|Memory|Used %" is a built-in metric that uses the individual rollup type. APPD_CLUSTERROLLUP_TYPE_COLLECTIVE – Aggregates the metric value by adding up the metric values for all the nodes in the tier. For example, "Agent|Metric Upload|Metrics uploaded" is a built-in metric that uses the collective rollup type. 

const (
	APPD_CLUSTERROLLUP_TYPE_INDIVIDUAL ClusterRollupType = iota + 1
	APPD_CLUSTERROLLUP_TYPE_COLLECTIVE
)

type Config 

type Config struct {
	AppName, TierName, NodeName string

	Controller Controller
	Logging    LoggingConfig

	/*
	 * Set to true if you want the SDK to check for configuration in the
	 * environment on init. Note that because this happens on init, the
	 * environment settings override whatever configuration you set in
	 * your program.
	 *
	 * See the documentation for appd_config_getenv in the C/C++ SDK
	 * for more information.
	 */
	UseConfigFromEnv bool

	/*
	 * If UseConfigFromEnv is set, this specifies the prefix to use for
	 * environment variable names. If UseConfigFromEnv is true and this
	 * is empty, then the default (APPD_SDK) is used.
	 *
	 * See the documentation for appd_config_getenv in the C/C++ SDK
	 * for more information.
	 */
	EnvVarPrefix string

	/*
	 * appd_sdk_init relies on controller configuration to start business
	 * transactions. This is an asynchronous action so that InitSDK does
	 * not block your program. This Config field allows you to instruct
	 * InitSDK to wait for up to InitTimeoutMs milliseconds and
	 * wait until it has received controller configuration and is ready to
	 * capture BTs.
	 *
	 * 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
	 */
	InitTimeoutMs int
}

type ContextConfig 

type ContextConfig struct {
	AppName  string
	TierName string
	NodeName string
}

*

  • Configuration of an application context (tenant) for the SDK.

type Controller 

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

	HTTPProxy HTTPProxy
}

type ErrorLevel 

type ErrorLevel int

Error levels for passing to AddBTError() and AddExitcallError(). 

const (
	APPD_LEVEL_NOTICE ErrorLevel = iota
	APPD_LEVEL_WARNING
	APPD_LEVEL_ERROR
)

type ExitcallHandle 

type ExitcallHandle uint64

func GetExitcall 

func GetExitcall(guid string) ExitcallHandle

// Get an exit call associated with a guid via StoreExitcall.

func StartExitcall 

func StartExitcall(bt BtHandle, backend string) ExitcallHandle

Start an exit call as part of a business transaction.

Returns An opaque handle to the exit call that was started.

type HTTPProxy 

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

type HoleHandlingType 

type HoleHandlingType int

A particular metric may not report data for a given minute. This configuration tells the Controller how to set the metric's count for that time slice. The count is set to zero if the hole handling type is APPD_HOLEHANDLING_TYPE_REGULAR_COUNTER, and set to one if APPD_HOLEHANDLING_TYPE_RATE_COUNTER. In effect, APPD_HOLEHANDLING_TYPE_RATE_COUNTER does not affect aggregation while APPD_HOLEHANDLING_TYPE_RATE_COUNTER does. 

const (
	APPD_HOLEHANDLING_TYPE_RATE_COUNTER HoleHandlingType = iota + 1
	APPD_HOLEHANDLING_TYPE_REGULAR_COUNTER
)

type LogLevel 

type LogLevel int
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 

type LoggingConfig struct {
	BaseDir          string
	MinimumLevel     LogLevel
	MaxNumFiles      uint
	MaxFileSizeBytes uint
}

type RollupType 

type RollupType int

Specifies how to roll up values for the metric over time. There are three ways in which the Controller can roll up metrics, as follows: APPD_TIMEROLLUP_TYPE_AVERAGE: It can calculate the average of all reported values in the time period. An example of a built-in metric that uses this is the "Average Response Time" metric. APPD_TIMEROLLUP_TYPE_SUM: Sum of all reported values in that minute. This operation behaves like a counter. An example metric is the "Calls per Minute" metric. APPD_TIMEROLLUP_TYPE_CURRENT: Current is the last reported value in the minute. If no value is reported in that minute, the last reported value is used. An example of a metric that uses this would be a machine state metric, such as "Max Available (MB)" metric. 

const (
	APPD_TIMEROLLUP_TYPE_AVERAGE RollupType = iota + 1
	APPD_TIMEROLLUP_TYPE_SUM
	APPD_TIMEROLLUP_TYPE_CURRENT
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.