Go Profiling

Getting started guide

Create StackImpact account

Sign up for a free trial account at stackimpact.com.

Supported environment

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

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 into 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() and agent.Report() should be used instead. Useful for environments without support for timers or background tasks.
  • Debug (Optional) Enables debug logging.
Basic example
package main

import (


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)

Programmatic profiling

The use of programmatic profiling is optional.

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

Error reporting

The use of Error API is optional.

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

// Aggregates and reports errors with regular intervals.
// Aggregates and reports panics with regular intervals.
defer agent.RecordPanic()
// 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.



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.