stackimpact

README

StackImpact Go Agent

Overview

StackImpact is a performance profiler for production applications. It gives developers continuous and historical view of application performance with line-of-code precision, which includes CPU, memory allocation and blocking call hot spots as well as execution bottlenecks, errors and runtime metrics. Learn more at stackimpact.com.

Features

• Continuous hot spot profiling for CPU, memory allocations, network, system calls and lock contention.
• Continuous latency bottleneck tracing.
• Error and panic monitoring.
• Health monitoring including CPU, memory, garbage collection and other runtime metrics.
• Anomaly detection.
• Multiple account users for team collaboration.

Learn more on the features page (with screenshots).

Documentation

See full documentation for reference.

Requirements

Linux, OS X or Windows. Go version 1.5+.

Getting started

Create StackImpact account

Sign up for a free account (also with GitHub login).

Installing the agent

Install the Go agent by running

go get github.com/stackimpact/stackimpact-go

And import the package github.com/stackimpact/stackimpact-go in your application.

Configuring the agent

Start the agent by specifying the agent key and application name. The agent key can be found in your account's Configuration section.

agent := stackimpact.Start(stackimpact.Options{
	AgentKey: "agent key here",
	AppName: "MyGoApp",
})

All initialization options:

• AgentKey (Required) The access key for communication with the StackImpact servers.
• AppName (Required) A name to identify and group application data. Typically, a single codebase, deployable unit or executable module corresponds to one application.
• AppVersion (Optional) Sets application version, which can be used to associate profiling information with the source code release.
• AppEnvironment (Optional) Used to differentiate applications in different environments.
• HostName (Optional) By default, host name will be the OS hostname.
• ProxyAddress (Optional) Proxy server URL to use when connecting to the Dashboard servers.
• AutoProfiling (Optional) If set to false, disables the default automatic profiling and reporting. agent.Profile() should be used instead. Useful for environments without support for timers or background tasks.
• Debug (Optional) Enables debug logging.

Example:

package main

import (
	"fmt"
	"net/http"

	"github.com/stackimpact/stackimpact-go"
)

func handler(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "Hello world!")
}

func main() {
	agent := stackimpact.Start(stackimpact.Options{
		AgentKey: "agent key here",
		AppName: "Basic Go Server",
		AppVersion: "1.0.0",
		AppEnvironment: "production",
	})

	http.HandleFunc("/", handler) 
	http.ListenAndServe(":8080", nil)
}

Manual profiling

The use of manual profiling is optional.

Manual profiling is suitable for repeating code, such as request or event handlers. By default, the agent starts and stops profiling automatically. In order to make sure the agent profiles the most relevant execution intervals, the agent.Profile() method can be used.

// Use this method to instruct the agent to start and stop 
// profiling. It does not guarantee that any profiler will be 
// started. The decision is made by the agent based on the 
// overhead constraints. The method returns Span object, on 
// which the Stop() method should be called.

span := agent.Profile();
defer span.Stop();

// A helper function to profile HTTP handler execution by wrapping 
// http.Handle method parameters.
// Usage example:
//   http.Handle(agent.ProfileHandler("/some-path", someHandler))
pattern, wrappedHandler := agent.ProfileHandler(pattern, handler)

// A helper function to profile HTTP handler function execution 
// by wrapping http.HandleFunc method parameters.
// Usage example:
//   http.HandleFunc(agent.ProfileHandlerFunc("/some-path", someHandlerFunc))
pattern, wrappedHandlerFunc := agent.ProfileHandlerFunc(pattern, handlerFunc)

Measuring code segments

The use of Segment API is optional.

To measure the execution time of arbitrary parts of the application, the Segment API can be used.

// Starts measurement of execution time of a code segment.
// To stop measurement, call Stop on returned Segment object.
// After calling Stop, the segment is recorded, aggregated and
// reported with regular intervals.
segment := agent.MeasureSegment("Segment1")
defer segment.Stop()

// A helper function to measure HTTP handler execution by wrapping 
// http.Handle method parameters.
// Usage example:
//   http.Handle(agent.MeasureHandler("/some-path", someHandler))
pattern, wrappedHandler := agent.MeasureHandler(pattern, handler)

// A helper function to measure HTTP handler function execution 
// by wrapping http.HandleFunc method parameters.
// Usage example:
//   http.HandleFunc(agent.MeasureHandlerFunc("/some-path", someHandlerFunc))
pattern, wrappedHandlerFunc := agent.MeasureHandlerFunc(pattern, handlerFunc)

Monitoring errors

The use of Error API is optional.

To monitor exceptions and panics with stack traces, the error recording API can be used.

Recording handled errors:

// Aggregates and reports errors with regular intervals.
agent.RecordError(someError)

Recording panics without recovering:

// Aggregates and reports panics with regular intervals.
defer agent.RecordPanic()

Recording and recovering from panics:

// Aggregates and reports panics with regular intervals. This function also
// recovers from panics.
defer agent.RecordAndRecoverPanic()

Analyzing performance data in the Dashboard

Once your application is restarted, you can start observing continuously recorded CPU, memory, I/O, and other hot spot profiles, execution bottlenecks as well as process metrics in the Dashboard.

Troubleshooting

To enable debug logging, add Debug: true to startup options. If the debug log doesn't give you any hints on how to fix a problem, please report it to our support team in your account's Support section.

Overhead

The agent overhead is measured to be less than 1% for applications under high load. For applications that are horizontally scaled to multiple processes, StackImpact agents are only active on a small subset (adjustable) of the processes at any point of time, therefore the total overhead is much lower.

Documentation

Index

• Constants
• type Agent
  • func NewAgent() *Agent
  • func Start(options Options) *Agent
  • func (a *Agent) Configure(agentKey string, appName string)
  • func (a *Agent) MeasureHandler(pattern string, handler http.Handler) (string, http.Handler)
  • func (a *Agent) MeasureHandlerFunc(pattern string, handlerFunc func(http.ResponseWriter, *http.Request)) (string, func(http.ResponseWriter, *http.Request))
  • func (a *Agent) MeasureSegment(segmentName string) *Segment
  • func (a *Agent) Profile() *Span
  • func (a *Agent) ProfileHandler(pattern string, handler http.Handler) (string, http.Handler)
  • func (a *Agent) ProfileHandlerFunc(pattern string, handlerFunc func(http.ResponseWriter, *http.Request)) (string, func(http.ResponseWriter, *http.Request))
  • func (a *Agent) ReadMetrics() []interface{}
  • func (a *Agent) RecordAndRecoverPanic()
  • func (a *Agent) RecordError(err interface{})
  • func (a *Agent) RecordPanic()
  • func (a *Agent) Start(options Options)
• type Options
• type Segment
  • func (s *Segment) Stop()
• type Span
  • func (s *Span) Stop()

Constants

const ErrorGroupHandledExceptions string = "Handled exceptions"

const ErrorGroupRecoveredPanics string = "Recovered panics"

const ErrorGroupUnrecoveredPanics string = "Unrecovered panics"

Types

type Agent

type Agent struct {

	// compatibility < 1.2.0
	DashboardAddress string
	AgentKey         string
	AppName          string
	HostName         string
	Debug            bool
	// contains filtered or unexported fields
}

func NewAgent

func NewAgent() *Agent

DEPRECATED. Kept for compatibility with <1.4.3.

func Start

func Start(options Options) *Agent

Starts the agent with configuration options. Required options are AgentKey and AppName.

func (*Agent) Configure

func (a *Agent) Configure(agentKey string, appName string)

DEPRECATED. Kept for compatibility with <1.2.0.

func (*Agent) MeasureHandler

func (a *Agent) MeasureHandler(pattern string, handler http.Handler) (string, http.Handler)

A helper function to measure HTTP handler execution by wrapping http.Handle method parameters.

func (*Agent) MeasureHandlerFunc

func (a *Agent) MeasureHandlerFunc(pattern string, handlerFunc func(http.ResponseWriter, *http.Request)) (string, func(http.ResponseWriter, *http.Request))

A helper function to measure HTTP handler function execution by wrapping http.HandleFunc method parameters.

func (*Agent) MeasureSegment

func (a *Agent) MeasureSegment(segmentName string) *Segment

Starts measurement of execution time of a code segment. To stop measurement call Stop on returned Segment object. After calling Stop the segment is recorded, aggregated and reported with regular intervals.

func (*Agent) Profile

func (a *Agent) Profile() *Span

Use this method to instruct the agent to start and stop profiling. It does not guarantee that any profiler will be started. The decision is made by the agent based on the overhead constraints. The method returns Span object, on which the Stop() method should be called.

func (*Agent) ProfileHandler

func (a *Agent) ProfileHandler(pattern string, handler http.Handler) (string, http.Handler)

A helper function to profile HTTP handler execution by wrapping http.Handle method parameters.

func (*Agent) ProfileHandlerFunc

func (a *Agent) ProfileHandlerFunc(pattern string, handlerFunc func(http.ResponseWriter, *http.Request)) (string, func(http.ResponseWriter, *http.Request))

A helper function to profile HTTP handler function execution by wrapping http.HandleFunc method parameters.

func (*Agent) ReadMetrics

func (a *Agent) ReadMetrics() []interface{}

Returns reported metrics in standalone mode.

func (*Agent) RecordAndRecoverPanic

func (a *Agent) RecordAndRecoverPanic()

Aggregates and reports panics with regular intervals. This function also recovers from panics

func (*Agent) RecordError

func (a *Agent) RecordError(err interface{})

Aggregates and reports errors with regular intervals.

func (*Agent) RecordPanic

func (a *Agent) RecordPanic()

Aggregates and reports panics with regular intervals.

func (*Agent) Start

func (a *Agent) Start(options Options)

Starts the agent with configuration options. Required options are AgentKey and AppName.

type Options

type Options struct {
	DashboardAddress string
	ProxyAddress     string
	AgentKey         string
	AppName          string
	AppVersion       string
	AppEnvironment   string
	HostName         string
	AutoProfiling    bool
	Standalone       bool
	Debug            bool
	ProfileAgent     bool
}

type Segment

type Segment struct {
	Name string

	Duration float64
	// contains filtered or unexported fields
}

func (*Segment) Stop

func (s *Segment) Stop()

Stops the measurement of a code segment execution time.

type Span

type Span struct {
	// contains filtered or unexported fields
}

func (*Span) Stop

func (s *Span) Stop()

Stops profiling.