stackimpact

README

StackImpact Go Agent

Overview

StackImpact is a performance profiling and monitoring service for production Go applications. It gives you continuous visibility with line-of-code precision into application performance, such as CPU, memory and I/O hot spots as well execution bottlenecks, allowing to optimize applications and troubleshoot issues before they impact customers. Learn more at stackimpact.com.

Features

• Automatic hot spot profiling for CPU, memory allocations, network, system calls and lock contention.
• Automatic bottleneck tracing for HTTP handlers and HTTP clients.
• Error and panic monitoring.
• Health monitoring including CPU, memory, garbage collection and other runtime metrics.
• Alerts on hot spot anomalies.
• Multiple account users for team collaboration.

Learn more about 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 at stackimpact.com.

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 agent key and application name. The agent key can be found in your account's Configuration section.

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

Other initialization options:

• 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.
• Debug (Optional) Enables debug logging.
• DashboardAddress (Optional) Used by on-premises deployments only.

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.NewAgent()
    agent.Start(stackimpact.Options{
        AgentKey: "agent key here",
        AppName: "Basic Go Server",
        AppVersion: "1.0.0",
        AppEnvironment: "production",
    })

    // use MeasureHandlerFunc or MeasureHandler to additionally measure HTTP request execution time.
    http.HandleFunc(agent.MeasureHandlerFunc("/", handler)) 
    http.ListenAndServe(":8080", nil)
}

Measuring code segments (optional)

To measure execution time of arbitrary parts of 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 (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, start observing regular and anomaly-triggered CPU, memory, IO, 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 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

Reporting CPU, network and system profiles requires regular and anomaly-triggered profiling and tracing activation for short periods of time. Unlike memory profiling and process-level metric reporting, they produce some overhead when active. The agent makes sure the profiling is active not more than 5% of the time and, while active, the overhead stays very low and has no effect on application execution.

Documentation

Index

• Constants
• type Agent
  • func NewAgent() *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) 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()

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

Creates new agent instance.

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) 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. Agent should be started only once. Required options are AgentKey and AppName.

type Options

type Options struct {
	DashboardAddress string
	AgentKey         string
	AppName          string
	AppVersion       string
	AppEnvironment   string
	HostName         string
	Debug            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.