Skip to content

docs(error-tracking): Document Mach-O executable support for symbol uploads #18820

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
inkeep wants to merge 2 commits into
base: master
Choose a base branch
from
+46 −16
Open

docs(error-tracking): Document Mach-O executable support for symbol uploads #18820

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d4f440e
docs(error-tracking): add macOS debug symbol upload step for Go\n\nPR…
inkeep[bot] Jul 22, 2026
a685275
docs(rust): document Mach-O executable support in symbol-sets upload
inkeep[bot] Jul 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 41 additions & 11 deletions contents/docs/error-tracking/installation/go.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ platformLogo: go
showStepsToc: true
---

import { Steps, Step } from 'components/Docs/Steps'
import { CalloutBox } from 'components/Docs/CalloutBox'
import { Steps, Step } from "components/Docs/Steps";
import { CalloutBox } from "components/Docs/CalloutBox";

<Steps>

Expand All @@ -19,7 +19,7 @@ go get github.com/posthog/posthog-go

<CalloutBox icon="IconInfo" title="Source context not yet supported" type="fyi">

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

</CalloutBox>

Expand Down Expand Up @@ -143,14 +143,14 @@ logger.Warn("Something broke",

The handler supports several configuration options:

| Option | Description | Default |
|---|---|---|
| `WithMinCaptureLevel(level)` | Minimum log level to capture | `slog.LevelWarn` |
| `WithDistinctIDFn(fn)` | Function to extract distinct ID from context/record | Returns `""` (skips capture) |
| `WithFingerprintFn(fn)` | Custom fingerprint for error grouping | `nil` (PostHog assigns) |
| `WithSkip(n)` | Stack frames to skip | `5` |
| `WithStackTraceExtractor(e)` | Custom stack trace extractor | `DefaultStackTraceExtractor` |
| `WithDescriptionExtractor(e)` | Custom description extractor | `ErrorExtractor` |
| Option | Description | Default |
| ----------------------------- | --------------------------------------------------- | ---------------------------- |
| `WithMinCaptureLevel(level)` | Minimum log level to capture | `slog.LevelWarn` |
| `WithDistinctIDFn(fn)` | Function to extract distinct ID from context/record | Returns `""` (skips capture) |
| `WithFingerprintFn(fn)` | Custom fingerprint for error grouping | `nil` (PostHog assigns) |
| `WithSkip(n)` | Stack frames to skip | `5` |
| `WithStackTraceExtractor(e)` | Custom stack trace extractor | `DefaultStackTraceExtractor` |
| `WithDescriptionExtractor(e)` | Custom description extractor | `ErrorExtractor` |

<CalloutBox icon="IconInfo" title="Error extraction" type="fyi">

Expand Down Expand Up @@ -179,4 +179,34 @@ client.Close()

</Step>

<Step title="Upload debug symbols (macOS)" badge="optional">

For production Go binaries on macOS, uploading debug symbols enables server-side symbolication with full stack traces including inlined frames.

### Build with uncompressed DWARF

Go compresses its embedded DWARF by default, which the symbolication server cannot read. Disable compression when building:

```bash
go build -ldflags="-compressdwarf=false" -o myapp .
```

### Upload the binary

After building, upload the binary with the [PostHog CLI](/docs/cli):

```bash
posthog-cli symbol-sets upload --directory ./
```

The CLI finds the Go executable, extracts its `LC_UUID`, and uploads the debug symbols. Run this as part of the same pipeline that produces your production binary — each build has its own UUID, so symbols must be re-uploaded for every build you deploy.

<CalloutBox icon="IconInfo" title="Version requirements" type="action">

Mach-O executable uploads require [CLI 0.8.2](https://github.com/PostHog/posthog/releases/tag/posthog-cli%2Fv0.8.2) or later.

</CalloutBox>

</Step>

</Steps>
10 changes: 5 additions & 5 deletions contents/docs/error-tracking/upload-source-maps/rust.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,16 @@ title: Upload debug symbols for Rust
showStepsToc: true
---

import CLIDownload from "../_snippets/cli/download.mdx"
import CLIAuthenticate from "../_snippets/cli/authenticate.mdx"
import StepVerifySymbolSetsUpload from "../_snippets/StepVerifySymbolSetsUpload"
import CLIDownload from "../_snippets/cli/download.mdx";
import CLIAuthenticate from "../_snippets/cli/authenticate.mdx";
import StepVerifySymbolSetsUpload from "../_snippets/StepVerifySymbolSetsUpload";

The [Rust SDK](/docs/error-tracking/installation/rust) resolves stack traces in-process from whatever debug info the running binary carries — which works well in development, but release builds omit that debug info by default. Uploading debug symbols gives you fully resolved production stack traces: PostHog symbolicates frames server-side from the exact build that crashed, resolves inlined frames, and can display the source code around each frame.

<CalloutBox icon="IconInfo" title="Version requirements" type="action">

- [posthog-rs 0.16.0](https://github.com/PostHog/posthog-rs/releases) or later, which records the instruction addresses server-side symbolication needs. We recommend the latest version.
- [CLI 0.7.32](https://github.com/PostHog/posthog/releases/tag/posthog-cli%2Fv0.7.32) or later for Linux binaries. Uploading macOS `.dSYM` bundles with the same command needs [CLI 0.8.1](https://github.com/PostHog/posthog/releases/tag/posthog-cli%2Fv0.8.1) or later. As always, we recommend [keeping up with the latest CLI version](/docs/error-tracking/upload-source-maps/cli).
- [CLI 0.7.32](https://github.com/PostHog/posthog/releases/tag/posthog-cli%2Fv0.7.32) or later for Linux binaries. Uploading macOS `.dSYM` bundles needs [CLI 0.8.1](https://github.com/PostHog/posthog/releases/tag/posthog-cli%2Fv0.8.1) or later. Uploading standalone Mach-O executables (including universal binaries) needs [CLI 0.8.2](https://github.com/PostHog/posthog/releases/tag/posthog-cli%2Fv0.8.2) or later. As always, we recommend [keeping up with the latest CLI version](/docs/error-tracking/upload-source-maps/cli).

</CalloutBox>

Expand Down Expand Up @@ -75,7 +75,7 @@ cargo build --release
posthog-cli symbol-sets upload --directory target/release
```

The CLI scans the directory and uploads every executable and shared library that carries debug info and a build ID, skipping everything else. On macOS it also uploads `.dSYM` bundles (this needs `dwarfdump`, which ships with Xcode). Windows binaries (PDB debug info) are not supported yet. The upload is associated with a [release](/docs/error-tracking/releases) automatically when the build directory is inside a git checkout.
The CLI scans the directory and uploads every executable and shared library that carries debug info and a build ID, skipping everything else. On macOS it also uploads `.dSYM` bundles (this needs `dwarfdump`, which ships with Xcode). It also uploads standalone Mach-O executables, dylibs, and debug companions that carry embedded DWARF and an `LC_UUID` — useful for builds that produce Mach-O binaries without generating dSYM bundles. Universal (fat) binaries are automatically split and each architecture slice is uploaded separately. Windows binaries (PDB debug info) are not supported yet. The upload is associated with a [release](/docs/error-tracking/releases) automatically when the build directory is inside a git checkout.

Run this as part of the same pipeline that produces your production binary. Each build has its own build ID, so symbols must be re-uploaded for every build you deploy.

Expand Down
Loading