Installation

Tracepanel for Go is the github.com/tracepanel/tracepanel-go module. It records the traces of your app and sends them to the agent. Its integrations with gin, Echo, pgx, GORM, Redis, zap, zerolog, gRPC and Kafka are modules of their own, so the core module keeps no dependencies.

The module shares the minor version with the agent, 0.10 today, and downloads the agent of the same minor the first time. See the changelog.

Add the moduleCopy Anchor Link

go get github.com/tracepanel/tracepanel-go@v0.10.0

Tracepanel needs Go 1.26 or newer, on Linux, macOS or Windows. Its tests and an app against the real agent run on Windows too.

Add it to your appCopy Anchor Link

Pass the driver's name to sql.Open through tracepanel.Driver, and wrap the app's handler. How you wrap it depends on the router:

import tracepanel "github.com/tracepanel/tracepanel-go"

func main() {
	db, err := sql.Open(tracepanel.Driver("pgx"), os.Getenv("DATABASE_URL"))
	if err != nil {
		log.Fatal(err)
	}
	app := &App{db: db}
	mux := http.NewServeMux()
	mux.HandleFunc("GET /books/{id}", app.showBook)
	log.Fatal(http.ListenAndServe(":8080", tracepanel.WrapHandler(mux)))
}

Pass the request's context down, as in db.QueryContext(r.Context(), ...). Tracepanel finds the request's trace in the context, so a query run without it isn't recorded. The same goes for log records and HTTP calls.

Run the app as usual, with go run ., and open a page of it. The first request starts the agent. Tracepanel records in development only, so a binary built with go build records nothing unless you turn it on. See Development only.

Open the panelCopy Anchor Link

A badge in the corner of each HTML page opens the panel. Every response carries Tracepanel-Id and Server-Timing, and Tracepanel-Url names the trace in the console. The SDK exposes these headers on CORS responses, so a single-page app on another origin reads them too.

The console isn't on your app's port. The agent serves it on 127.0.0.1, on a port of its own, and Tracepanel-Url has its address. tracepanel dev serves it on a fixed port. See Command line.

Add .tracepanel/ to your .gitignore: it holds the project's traces.

echo ".tracepanel/" >> .gitignore

The agentCopy Anchor Link

The agent is a separate program that keeps the traces, finds the issues and serves the console. You don't install it. The first time your app runs, the SDK downloads the agent of its version for your platform from the agent's npm package. It checks the binary against the SHA-512 the SDK was released with, and keeps it in the user's cache for every project. It checks it again the first time a process runs it. The cache is the first of these that is set:

1. TRACEPANEL_CACHE_DIR
2. %LOCALAPPDATA%\tracepanel\, on Windows only
3. $XDG_CACHE_HOME/tracepanel/
4. ~/.cache/tracepanel/, on macOS too

Without a home directory, the agent is kept in the system's temporary directory, under tracepanel/.

Without a network, the SDK runs tracepanel-agent from the PATH. TRACEPANEL_AGENT_BIN names another agent, such as a build of your own. See How it works.

The agent comes for these platforms:

• Linux on glibc: x86_64, arm64, i686, ppc64le, s390x and riscv64.
• Linux on musl, such as Alpine: x86_64, arm64 and i686.
• Linux on 32-bit ARM: one static build for glibc and musl.
• macOS: Apple silicon and Intel.
• Windows: x86_64, x86 and arm64.

Behind a mirror or a proxyCopy Anchor Link

Where your company mirrors npm, set TRACEPANEL_NPM_REGISTRY to the mirror. Without it, the SDK uses npm's own npm_config_registry.

export TRACEPANEL_NPM_REGISTRY=https://artifactory.corp/api/npm/npm/

Where the network goes through a proxy, the download goes through HTTPS_PROXY, and NO_PROXY lists the hosts that skip it, as Go's HTTP client reads them.

Development onlyCopy Anchor Link

Tracepanel records in development only, as every Tracepanel SDK does. Go has no debug mode, so the SDK records when one of these holds:

• The app runs under go run.
• TRACEPANEL_ENABLED=1 is set.
• The app sets Config.Enabled, such as for a staging build. Call tracepanel.Setup with it before Driver, so the database is recorded too.

A binary built with go build, as your production build or a container's is, records nothing. WrapHandler and Middleware return your handler as it is, Driver returns the driver's own name, the integrations record nothing, and no agent is downloaded or started. TRACEPANEL_ENABLED=0 turns Tracepanel off, whatever else says.

To record a built binary, run it through the SDK's command, which sets TRACEPANEL_ENABLED=1 for it:

go install github.com/tracepanel/tracepanel-go/cmd/tracepanel@v0.10.0
tracepanel run ./shop

tracepanel run exits with the app's exit code. See Command line.