# Installation (/docs/go/installation)

Tracepanel for Go is the
[`github.com/tracepanel/tracepanel-go`](https://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](https://github.com/tracepanel/tracepanel-go/blob/main/CHANGELOG.md).

## Add the module [#add-the-module]

```bash
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 app [#add-it-to-your-app]

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:

<Tabs items={["net/http", "chi", "gin", "Echo"]}>
  <Tab value="net/http">

```go
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)))
}
```

Each request is named by its `ServeMux` pattern, such as `GET /books/{id}`.

  </Tab>
  <Tab value="chi">

chi takes `tracepanel.Middleware`. Tell Tracepanel the route with
`Config.Route`, in `tracepanel.Setup` before it:

```go
tracepanel.Setup(tracepanel.Config{
	Route: func(r *http.Request) string {
		return chi.RouteContext(r.Context()).RoutePattern()
	},
})
router := chi.NewRouter()
router.Use(tracepanel.Middleware)
```

gorilla/mux and other routers on `net/http` work the same way.

  </Tab>
  <Tab value="gin">

```bash
go get github.com/tracepanel/tracepanel-go/gintrace@v0.10.0
```

```go
router := gin.Default()
router.Use(gintrace.Middleware())
```

  </Tab>
  <Tab value="Echo">

```bash
go get github.com/tracepanel/tracepanel-go/echotrace@v0.10.0
```

```go
e := echo.New()
e.Use(echotrace.Middleware())
```

For Echo v5, use `github.com/tracepanel/tracepanel-go/echo5trace` and
`echo5trace.Middleware()`.

  </Tab>
</Tabs>

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](#development-only).

## Open the panel [#open-the-panel]

A badge in the corner of each HTML page opens the [panel](/docs/panel).
Every response carries `Tracepanel-Id` and `Server-Timing`, and
`Tracepanel-Url` names the trace in the [console](/docs/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](/docs/go/cli).

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

```bash
echo ".tracepanel/" >> .gitignore
```

## The agent [#the-agent]

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](/docs/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 proxy [#behind-a-mirror-or-a-proxy]

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

```bash
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 only [#development-only]

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:

```bash
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](/docs/go/cli#tracepanel-run).