Go error tracking installation

1
Install the Go SDK
Required
Install the PostHog Go SDK:
Terminal
go get github.com/posthog/posthog-go
Source context not yet supported
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.

Initialize the client

Required

Go
package main

import (
    "github.com/posthog/posthog-go"
)

func main() {
    client, _ := posthog.NewWithConfig(
        "<ph_project_api_key>",
        posthog.Config{
            Endpoint: "https://us.i.posthog.com",
        },
    )
    defer client.Close()
}

Capture exceptions

Required

There are two ways to capture exceptions with the Go SDK:

Option A: Direct capture

Use NewDefaultException to capture errors directly. This automatically generates a UUID and stack trace for you.

Go
import (
    "time"
    "github.com/posthog/posthog-go"
)

exception := posthog.NewDefaultException(
    time.Now(),
    "user_distinct_id",
    "DatabaseError",         // type - rendered as title in the UI
    "connection refused",    // value - rendered as description in the UI
)
client.Enqueue(exception)

For more control, build the Exception struct manually:

Go
import (
    "time"
    "github.com/posthog/posthog-go"
)

handled := true
fingerprint := "my-custom-fingerprint"

exception := posthog.Exception{
    DistinctId: "user_distinct_id",
    Timestamp:  time.Now(),
    ExceptionList: []posthog.ExceptionItem{
        {
            Type:  "DatabaseError",
            Value: "connection refused",
            Mechanism: &posthog.ExceptionMechanism{
                Handled: &handled,
            },
        },
    },
    ExceptionFingerprint: &fingerprint,
}
client.Enqueue(exception)

Option B: Automatic capture with slog

The SDK provides a SlogCaptureHandler that wraps Go's standard log/slog logger and automatically captures log records as exceptions.

By default, it captures logs at Warning level and above.

Go
import (
    "context"
    "fmt"
    "log/slog"
    "os"

    "github.com/posthog/posthog-go"
)

client, _ := posthog.NewWithConfig(
    "<ph_project_api_key>",
    posthog.Config{
        Endpoint: "https://us.i.posthog.com",
    },
)
defer client.Close()

baseHandler := slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
    Level: slog.LevelInfo,
})

logger := slog.New(posthog.NewSlogCaptureHandler(baseHandler, client,
    posthog.WithDistinctIDFn(func(ctx context.Context, r slog.Record) string {
        // Return the user ID from context or another source
        return "user_distinct_id"
    }),
))

// This warning is automatically captured as an exception in PostHog
logger.Warn("Something broke",
    "error", fmt.Errorf("connection refused"),
)

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`

Error extraction

The slog handler automatically extracts error descriptions from log attributes with keys err or error (case-insensitive). It also supports wrapped errors via the Unwrap() interface.

Verify error tracking

Recommended

Trigger a test exception to confirm events are being sent to PostHog. You should see them appear in the activity feed.

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

// Flush the queue before exiting
client.Close()

Go error tracking installation

Contents

Install the Go SDK

Initialize the client

Capture exceptions

Option A: Direct capture

Option B: Automatic capture with slog

Verify error tracking

Community questions

Was this page useful?