Skip to content

Commit 50bdc02

Browse files
cat-phcat-ph
committed
docs(error-tracking): add Go debug symbol upload guide
1 parent 3547149 commit 50bdc02

4 files changed

Lines changed: 134 additions & 2 deletions

File tree

‎contents/docs/error-tracking/_snippets/upload-symbol-sets-platforms.tsx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,11 @@ const UploadSymbolSetsPlatforms = () => {
4848
url: '/docs/error-tracking/upload-source-maps/flutter',
4949
image: 'https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/flutter.svg',
5050
},
51+
{
52+
label: 'Go',
53+
url: '/docs/error-tracking/upload-source-maps/go',
54+
image: 'https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/go.svg',
55+
},
5156
{
5257
label: 'iOS',
5358
url: '/docs/error-tracking/upload-source-maps/ios',

‎contents/docs/error-tracking/installation/go.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,9 @@ Install the [PostHog Go SDK](/docs/libraries/go):
1717
go get github.com/posthog/posthog-go
1818
```
1919

20-
<CalloutBox icon="IconInfo" title="Source context not yet supported" type="fyi">
20+
<CalloutBox icon="IconInfo" title="Debug symbol uploads" type="fyi">
2121

22-
The Go SDK captures stack traces with file names, line numbers, and function names, but does not yet support source context (displaying the surrounding lines of code in the error tracking UI). Symbol set uploads for Go are not currently available.
22+
The Go SDK resolves stack traces in-process, so captured frames include file names, line numbers, and function names without any symbol uploads. For exact inlined frame resolution and source context (the surrounding lines of code in the error tracking UI), [upload debug symbols](/docs/error-tracking/upload-source-maps/go) — this needs posthog-go 1.20.0 or later.
2323

2424
</CalloutBox>
2525

‎contents/docs/error-tracking/upload-source-maps/go.mdx‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: Upload debug symbols for Go
3+
showStepsToc: true
4+
---
5+
6+
import CLIDownload from "../_snippets/cli/download.mdx"
7+
import CLIAuthenticate from "../_snippets/cli/authenticate.mdx"
8+
import StepVerifySymbolSetsUpload from "../_snippets/StepVerifySymbolSetsUpload"
9+
10+
The [Go SDK](/docs/error-tracking/installation/go) resolves stack traces in-process from the Go runtime, so captured frames always include file names, line numbers, and function names. Uploading debug symbols improves on that: PostHog symbolicates frames server-side from the exact build that crashed, resolves inlined calls precisely, and can display the source code around each frame.
11+
12+
<CalloutBox icon="IconInfo" title="Version requirements" type="action">
13+
14+
- [posthog-go 1.20.0](https://github.com/PostHog/posthog-go/releases) or later, which records the instruction addresses and binary identity server-side symbolication needs. We recommend the latest version.
15+
- The latest [CLI](/docs/error-tracking/upload-source-maps/cli). Linux binaries work with CLI 0.7.32 or later; uploading macOS Go binaries directly is newer, so update if you have an older install.
16+
17+
</CalloutBox>
18+
19+
<Steps>
20+
21+
<Step title="Download CLI" badge="required">
22+
23+
<CLIDownload />
24+
25+
</Step>
26+
27+
<Step title="Authenticate" badge="required">
28+
29+
<CLIAuthenticate />
30+
31+
</Step>
32+
33+
<Step title="Build with the right linker flags" badge="required">
34+
35+
Go embeds DWARF debug info in every binary by default, but the SDK and CLI need a little help depending on the platform.
36+
37+
On Linux, add a GNU build ID — the unique identifier PostHog uses to match stack frames to uploaded symbols. Go doesn't emit one by default:
38+
39+
```bash
40+
go build -ldflags="-B gobuildid" -o my-app .
41+
```
42+
43+
On macOS, keep the DWARF uncompressed. Binaries always carry a Mach-O UUID, so there is no build ID step, but Go compresses debug info by default and compressed DWARF can't be used for symbolication yet:
44+
45+
```bash
46+
go build -ldflags="-compressdwarf=false" -o my-app .
47+
```
48+
49+
Watch out for flags that remove what the upload needs: `-ldflags="-w"` or `-ldflags="-s"` strip DWARF entirely, and `-trimpath` rewrites the source paths that `--include-source` relies on.
50+
51+
</Step>
52+
53+
<Step title="Build and upload" badge="required">
54+
55+
Point the CLI at the directory containing your built binary:
56+
57+
```bash
58+
posthog-cli symbol-sets upload --directory ./bin
59+
```
60+
61+
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 none is needed. Universal (fat) binaries upload one symbol set per architecture slice. Windows binaries are not supported yet: the SDK sends plain runtime-resolved frames there.
62+
63+
Run this as part of the same pipeline that produces your production binary. Each build has its own identity, so symbols must be re-uploaded for every build you deploy.
64+
65+
</Step>
66+
67+
<Step title="Optional: Include source code context" badge="optional">
68+
69+
By default, only debug symbols are uploaded. To also display the source code around each frame in your stack traces, add `--include-source`:
70+
71+
```bash
72+
posthog-cli symbol-sets upload --directory ./bin --include-source
73+
```
74+
75+
This bundles the project source files referenced by the debug info into the upload. It increases upload size, so only enable it if you want source context in the error tracking UI. It also requires building without `-trimpath`, since the CLI reads sources from the paths recorded at compile time.
76+
77+
</Step>
78+
79+
<Step title="Optional: Upload from CI" badge="optional">
80+
81+
In CI, authenticate with environment variables instead of `posthog-cli login`. For GitHub Actions:
82+
83+
```yaml
84+
- name: Build release binary
85+
run: go build -ldflags="-B gobuildid" -o bin/my-app .
86+
87+
- name: Upload debug symbols
88+
run: posthog-cli symbol-sets upload --directory ./bin
89+
env:
90+
POSTHOG_CLI_API_KEY: ${{ secrets.POSTHOG_CLI_API_KEY }}
91+
POSTHOG_CLI_PROJECT_ID: ${{ secrets.POSTHOG_CLI_PROJECT_ID }}
92+
```
93+
94+
Scope the credentials to the upload step only — the build itself doesn't need them.
95+
96+
The CLI defaults to US Cloud. If you are on EU Cloud or self-hosted, also set `POSTHOG_CLI_HOST` (for example `https://eu.posthog.com`).
97+
98+
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.
99+
100+
</Step>
101+
102+
<StepVerifySymbolSetsUpload symbolType="debug symbols" />
103+
104+
<Step title="Test it end-to-end" badge="optional">
105+
106+
Capture a test exception from the same binary the symbols were uploaded for:
107+
108+
```go
109+
exception := posthog.NewDefaultException(
110+
time.Now(),
111+
"test_user",
112+
"TestError",
113+
"This is a test exception from Go",
114+
)
115+
client.Enqueue(exception)
116+
client.Close()
117+
```
118+
119+
Run the binary, then check the [error tracking issues view](https://app.posthog.com/error_tracking): the stack trace should resolve against the uploaded symbols, including source context if you uploaded with `--include-source`. A rebuild changes the binary's identity, so if you rebuild, upload again before testing.
120+
121+
</Step>
122+
123+
</Steps>

‎src/navs/index.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5315,6 +5315,10 @@ export const docsMenu = {
53155315
name: 'Flutter',
53165316
url: '/docs/error-tracking/upload-source-maps/flutter',
53175317
},
5318+
{
5319+
name: 'Go',
5320+
url: '/docs/error-tracking/upload-source-maps/go',
5321+
},
53185322
{
53195323
name: 'iOS',
53205324
url: '/docs/error-tracking/upload-source-maps/ios',

0 commit comments

Comments
 (0)