Upload debug symbols for Go

Install posthog-cli:

npm install -g @posthog/cli

curl --proto '=https' --tlsv1.2 -LsSf https://download.posthog.com/cli | sh
posthog-cli-update

To authenticate the CLI, call the login command. This opens your browser where you select your organization, project, and API scopes to grant:

posthog-cli login

If you are using the CLI in a CI/CD environment such as GitHub Actions, you can set environment variables to authenticate:

You can also use the --host option instead of the POSTHOG_CLI_HOST environment variable to target a different PostHog instance or region. For EU users:

posthog-cli --host https://eu.posthog.com [CMD]

Go embeds DWARF debug info in every binary by default. What you add on top depends on the platform.

On Linux, add a GNU build ID. That's the identifier PostHog uses to match stack frames to uploaded symbols, and Go doesn't emit one unless you ask:

go build -ldflags="-B gobuildid" -o my-app .

On macOS there's no build ID step, since every Mach-O binary carries a UUID. Instead, turn off DWARF compression. Go compresses debug info by default, and symbolication can't read the compressed form yet:

go build -ldflags="-compressdwarf=false" -o my-app .

Two flags to avoid: -ldflags="-w" and -ldflags="-s" strip the DWARF entirely, and -trimpath rewrites the source paths that --include-source reads from.

Point the CLI at the directory containing your built binary:

posthog-cli symbol-sets upload --directory ./bin

The CLI scans the directory and uploads every executable that carries debug info and an identity, skipping everything else. On macOS the Go binary uploads directly. Go never produces a .dSYM bundle, and it doesn't need one. Universal (fat) binaries upload one symbol set per architecture slice. Windows isn't supported yet, so the SDK falls back to plain runtime-resolved frames there.

Run this in the same pipeline that produces your production binary. Every build gets its own identity, so you need to re-upload for each build you deploy.

By default, only debug symbols are uploaded. To also display the source code around each frame in your stack traces, add --include-source:

posthog-cli symbol-sets upload --directory ./bin --include-source

This bundles the project source files referenced by the debug info into the upload. Uploads get bigger, so turn it on only if you want source context in the error tracking UI. It also means building without -trimpath, since the CLI reads the sources off disk using the paths recorded at compile time.

In CI, authenticate with environment variables instead of posthog-cli login. For GitHub Actions:

- name: Build release binary
  run: go build -ldflags="-B gobuildid" -o bin/my-app .

- name: Upload debug symbols
  run: posthog-cli symbol-sets upload --directory ./bin
  env:
    POSTHOG_CLI_API_KEY: ${{ secrets.POSTHOG_CLI_API_KEY }}
    POSTHOG_CLI_PROJECT_ID: ${{ secrets.POSTHOG_CLI_PROJECT_ID }}

Scope the credentials to the upload step. The build itself doesn't need them.

The CLI defaults to US Cloud. If you're on EU Cloud or self-hosted, also set POSTHOG_CLI_HOST (for example https://eu.posthog.com).

If your binary is built inside a Dockerfile, run the upload in the build stage right after the build, and pass the credentials in as build secrets so they never reach the runtime image.

Capture a test exception from the same binary the symbols were uploaded for:

exception := posthog.NewDefaultException(
    time.Now(),
    "test_user",
    "TestError",
    "This is a test exception from Go",
)
client.Enqueue(exception)
client.Close()

Run the binary, then open the error tracking issues view. The stack trace should resolve against the uploaded symbols, with source context if you used --include-source. Rebuilding changes the binary's identity, so upload again before you test.