Setting the file. One moment.
Chapter 47 · Instrument Integration
Subchapter 47.43
references/go.mdMarkdown19 KBView on GitHub
This library uses an internal queue to make calls fast and non-blocking. It also batches requests and flushes asynchronously, making it perfect to use in any part of your web app or other server-side application that needs performance.
Terminal
PostHog AI
go get github.com/posthog/posthog-goGo
PostHog AI
package main
import (
"os"
"github.com/posthog/posthog-go"
)
func main() {
client, _ := posthog.NewWithConfig(
os.Getenv("POSTHOG_API_KEY"),
posthog.Config{
PersonalApiKey: "your personal API key", // Optional, but much more performant. If this token is not supplied, then fetching feature flag values will be slower.
Endpoint: "https://us.i.posthog.com",
},
)
defer client.Close()
// run commands
}Identifying users is required. Backend events need a
distinct_idthat matches the ID your frontend uses when callingposthog.identify(). Without this, backend events are orphaned — they can’t be linked to frontend event captures, session replays (opens in a new tab), LLM traces (opens in a new tab), or error tracking (opens in a new tab).See our guide on identifying users (opens in a new tab) for how to set this up.
You can send custom events using capture:
Go
PostHog AI
client.Enqueue(posthog.Capture{
DistinctId: "distinct_id_of_the_user",
Event: "user_signed_up",
})Tip: We recommend using a
[object] [verb]format for your event names, where[object]is the entity that the behavior relates to, and[verb]is the behavior itself. For example,project created,user signed up, orinvite sent.
Tip: You can define event schemas with typed properties and generate type-safe code using schema management (opens in a new tab).
Optionally, you can include additional information with the event by including a properties (opens in a new tab) object:
Go
PostHog AI
client.Enqueue(posthog.Capture{
DistinctId: "distinct_id_of_the_user",
Event: "user_signed_up",
Properties: posthog.NewProperties().
Set("login_type", "email").
Set("is_free_trial", true),
})If you’re aiming for a backend-only implementation of PostHog and won’t be capturing events from your frontend, you can send pageviews from your backend like so:
Go
PostHog AI
client.Enqueue(posthog.Capture{
DistinctId: "distinct_id_of_the_user",
Event: "$pageview",
Properties: posthog.NewProperties().
Set("$current_url", "https://example.com"),
})For backward compatibility, the Go SDK captures identified events by default. These create person profiles (opens in a new tab). To set person properties (opens in a new tab) in these profiles, include them when capturing an event:
Go
PostHog AI
client.Enqueue(posthog.Capture{
DistinctId: "distinct_id",
Event: "event_name",
Properties: map[string]interface{}{
"$set": map[string]interface{}{
"name": "Max Hedgehog",
},
"$set_once": map[string]interface{}{
"initial_url": "/blog",
},
},
})For more details on the difference between $set and $set_once, see our person properties docs (opens in a new tab).
To capture anonymous events (opens in a new tab) without person profiles, set the event’s $process_person_profile property to false:
Go
PostHog AI
client.Enqueue(posthog.Capture{
DistinctId: "distinct_id",
Event: "event_name",
Properties: map[string]interface{}{
"$process_person_profile": false,
},
})Sometimes, you want to assign multiple distinct IDs to a single user. This is helpful when your primary distinct ID is inaccessible. For example, if a distinct ID used on the frontend is not available in your backend.
In this case, you can use alias to assign another distinct ID to the same user.
Go
PostHog AI
client.Enqueue(posthog.Alias{
DistinctId: "distinct_id",
Alias: "alias_id",
})We strongly recommend reading our docs on alias (opens in a new tab) to best understand how to correctly use this method.
Use request context to apply a distinct ID, session ID, and common request properties to capture and exception events inside a net/http request. This is useful when connecting frontend activity to backend events, session replay, error tracking, and feature flag evaluation.
If you’re using PostHog on your frontend, enable tracing headers for your backend domain:
JavaScript
PostHog AI
posthog.init('<ph_project_token>', {
__add_tracing_headers: ['your-backend-domain.com']
})Then wrap your handler with NewRequestContextMiddleware and use the context-aware helpers:
Go
PostHog AI
handler := posthog.NewRequestContextMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
flags, err := posthog.EvaluateFlagsWithContext(r.Context(), client, posthog.EvaluateFlagsPayload{})
if err != nil {
// If neither the request context nor payload has a distinct ID,
// err is posthog.ErrNoDistinctID.
}
_ = posthog.EnqueueWithContext(r.Context(), client, posthog.Capture{
Event: "checkout started",
Flags: flags,
})
}))The middleware adds $current_url, $request_method, $request_path, $user_agent, and $ip properties. By default, it also reads X-PostHog-Distinct-Id and X-PostHog-Session-Id as request-scoped defaults. Explicit DistinctId values and $session_id properties passed to captures take precedence over request context.
If request context is attached but no distinct ID is available, capture and exception events are sent as personless events (opens in a new tab) with an auto-generated UUID and $process_person_profile: false. Calls to Enqueue without request context still require DistinctId. EvaluateFlagsWithContext uses the request-scoped distinct ID when EvaluateFlagsPayload.DistinctId is empty, but it never generates personless IDs and returns ErrNoDistinctID when no distinct ID is available.
Tracing headers are client-controlled analytics context, not authentication or authorization. For security-sensitive server-side decisions, pass an authenticated DistinctId explicitly or attach one to the request context:
Go
PostHog AI
ctx := posthog.WithRequestContext(r.Context(), posthog.RequestContext{
DistinctId: user.ID,
})To ignore tracing headers while keeping request metadata, disable tracing header capture:
Go
PostHog AI
handler := posthog.NewRequestContextMiddleware(
next,
posthog.WithCaptureTracingHeaders(false),
)PostHog’s feature flags (opens in a new tab) enable you to safely deploy and roll back new features as well as target specific users and groups with them.
There are two steps to implement feature flags in Go:
Call client.EvaluateFlags() once for the user, then read values from the returned snapshot.
Go
PostHog AI
flags, err := client.EvaluateFlags(posthog.EvaluateFlagsPayload{
DistinctId: "distinct_id_of_your_user",
})
if err != nil {
// Handle error (e.g. capture error and fallback to default behavior)
}
if flags.IsEnabled("flag-key") {
// Do something differently for this user
// Optional: fetch the payload
matchedFlagPayload := flags.GetFlagPayload("flag-key")
}Go
PostHog AI
flags, err := client.EvaluateFlags(posthog.EvaluateFlagsPayload{
DistinctId: "distinct_id_of_your_user",
})
if err != nil {
// Handle error (e.g. capture error and fallback to default behavior)
}
enabledVariant := flags.GetFlag("flag-key")
if enabledVariant == "variant-key" { // replace "variant-key" with the key of your variant
// Do something differently for this user
// Optional: fetch the payload
matchedFlagPayload := flags.GetFlagPayload("flag-key")
}flags.GetFlag() returns the variant string for multivariate flags, true for enabled boolean flags, false for disabled flags, and nil when the flag wasn’t returned by the evaluation.
Note:
client.IsFeatureEnabled(),client.GetFeatureFlag(),client.GetFeatureFlagPayload(), andCapture.SendFeatureFlagsstill work during the migration period, but they’re deprecated. PreferEvaluateFlags()for new code.
If you want use your feature flag to breakdown or filter events in your insights (opens in a new tab), you’ll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.
Note: This step is only required for events captured using our server-side SDKs or API (opens in a new tab).
There are two methods you can use to include feature flag information in your events:
Pass the same flags object that you used for branching. This attaches the exact flag values from that evaluation and doesn’t make another /flags request.
Go
PostHog AI
flags, err := client.EvaluateFlags(posthog.EvaluateFlagsPayload{
DistinctId: "distinct_id_of_your_user",
})
if err != nil {
// Handle error
}
if flags.IsEnabled("flag-key") {
// Do something differently for this user
}
client.Enqueue(posthog.Capture{
DistinctId: "distinct_id_of_your_user",
Event: "event_name",
Flags: flags,
})By default, this attaches every flag in the snapshot using $feature/<flag-key> properties and $active_feature_flags.
To reduce event property bloat, pass a filtered snapshot:
Go
PostHog AI
// Attach only flags accessed with IsEnabled() or GetFlag() before this call
client.Enqueue(posthog.Capture{
DistinctId: "distinct_id_of_your_user",
Event: "event_name",
Flags: flags.OnlyAccessed(),
})
// Attach only specific flags
client.Enqueue(posthog.Capture{
DistinctId: "distinct_id_of_your_user",
Event: "event_name",
Flags: flags.Only([]string{"checkout-flow", "new-dashboard"}),
})OnlyAccessed() is order-dependent. If you call it before accessing any flags with IsEnabled() or GetFlag(), no feature flag properties are attached.
In the event properties, include $feature/feature_flag_name: variant_key:
Go
PostHog AI
client.Enqueue(posthog.Capture{
DistinctId: "distinct_id_of_your_user",
Event: "event_name",
Properties: posthog.NewProperties().
Set("$feature/feature-flag-key", "variant-key"), // replace feature-flag-key with your flag key. Replace "variant-key" with the key of your variant
})By default, EvaluateFlags() evaluates every flag for the user. If you only need a few flags, pass FlagKeys to request only those flags:
Go
PostHog AI
flags, err := client.EvaluateFlags(posthog.EvaluateFlagsPayload{
DistinctId: "distinct_id_of_your_user",
FlagKeys: []string{"checkout-flow", "new-dashboard"},
})Capturing $feature_flag_called events enables PostHog to know when a flag was accessed by a user and provide analytics and insights (opens in a new tab) on the flag. With EvaluateFlags(), the SDK sends this event when you call flags.IsEnabled() or flags.GetFlag() for a flag.
The SDK deduplicates these events per (distinct_id, flag, value) in a local cache. If you reinitialize the PostHog client, the cache resets and $feature_flag_called events may be sent again. PostHog handles duplicates, so duplicate $feature_flag_called events don’t affect your analytics.
flags.GetFlagPayload() doesn’t send $feature_flag_called events and doesn’t count as an access for OnlyAccessed().
Sometimes, you may want to evaluate feature flags using person properties (opens in a new tab), groups (opens in a new tab), or group properties that haven’t been ingested yet, or were set incorrectly earlier.
You can provide properties to evaluate the flag with by using the person properties, groups, and group properties arguments. PostHog will then use these values to evaluate the flag, instead of any properties currently stored on your PostHog server.
For example:
Go
PostHog AI
flags, err := client.EvaluateFlags(posthog.EvaluateFlagsPayload{
DistinctId: "distinct_id_of_the_user",
Groups: posthog.NewGroups().
Set("your_group_type", "your_group_id").
Set("another_group_type", "your_group_id"),
PersonProperties: posthog.NewProperties().
Set("property_name", "value"),
GroupProperties: map[string]posthog.Properties{
"your_group_type": posthog.NewProperties().
Set("group_property_name", "value"),
"another_group_type": posthog.NewProperties().
Set("group_property_name", "value"),
},
})
if err != nil {
// Handle error
}
if flags.IsEnabled("flag-key") {
// Do something differently for this user
}By default, a user’s GeoIP properties are set using the IP address they use to capture events on the frontend. You may want to override the these properties when evaluating feature flags. A common reason to do this is when you’re not using PostHog on your frontend, so the user has no GeoIP properties.
You can override GeoIP properties by including them in the person_properties parameter when evaluating feature flags. This is useful when you’re evaluating flags on your backend and want to use the client’s location instead of your server’s location.
The following GeoIP properties can be overridden:
$geoip_country_code$geoip_country_name$geoip_city_name$geoip_city_confidence$geoip_continent_code$geoip_continent_name$geoip_latitude$geoip_longitude$geoip_postal_code$geoip_subdivision_1_code$geoip_subdivision_1_name$geoip_subdivision_2_code$geoip_subdivision_2_name$geoip_subdivision_3_code$geoip_subdivision_3_name$geoip_time_zoneSimply include any of these properties in the person_properties parameter alongside your other person properties when calling feature flags.
You can configure the FeatureFlagRequestTimeout parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked if PostHog’s servers are too slow to respond. By default, this is set to 3 seconds.
Go
PostHog AI
client, _ := posthog.NewWithConfig(
os.Getenv("<ph_project_token>"),
posthog.Config{
PersonalApiKey: "your personal API key", // Optional, but much more performant. If this token is not supplied, then fetching feature flag values will be slower.
Endpoint: "https://us.i.posthog.com",
FeatureFlagRequestTimeout: 3, // Time in seconds. Defaults to 3.
},
)Evaluating feature flags requires making a request to PostHog for each flag. However, you can improve performance by evaluating flags locally. Instead of making a request for each flag, PostHog will periodically request and store feature flag definitions locally, enabling you to evaluate flags without making additional requests.
It is best practice to use local evaluation flags when possible, since this enables you to resolve flags faster and with fewer API calls.
For details on how to implement local evaluation, see our local evaluation guide (opens in a new tab).
Since experiments (opens in a new tab) use feature flags, the code for running an experiment is very similar to the feature flags code:
Go
PostHog AI
flags, err := client.EvaluateFlags(posthog.EvaluateFlagsPayload{
DistinctId: "user_distinct_id",
})
if err != nil {
// Handle error (e.g. capture error and fallback to default behavior)
}
variant := flags.GetFlag("experiment-feature-flag-key")
if variant == "variant-name" {
// Do something
}It’s also possible to run experiments without using feature flags (opens in a new tab).
You can capture exceptions and errors using the Go SDK. There are two approaches:
Direct capture using NewDefaultException, which automatically generates a stack trace:
Go
PostHog AI
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)Automatic capture using the SlogCaptureHandler, which wraps Go’s log/slog and sends log records at warning level and above as exceptions:
Go
PostHog AI
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 "user_distinct_id"
}),
))
// Automatically captured as an exception in PostHog
logger.Warn("Something broke", "error", fmt.Errorf("connection refused"))For the full setup guide, see the Go error tracking installation docs (opens in a new tab).
Group analytics allows you to associate an event with a group (e.g. teams, organizations, etc.). Read the Group Analytics (opens in a new tab) guide for more information.
Note: This is a paid feature and is not available on the open-source or free cloud plan. Learn more on the pricing page (opens in a new tab).
Go
PostHog AI
client.Enqueue(posthog.Capture{
DistinctId: "user_distinct_id",
Event: "some_event",
Groups: posthog.NewGroups().
Set("company", "company_id_in_your_db"),
})Go
PostHog AI
client.Enqueue(posthog.GroupIdentify{
Type: "company",
Key: "company_id_in_your_db",
Properties: posthog.NewProperties().
Set("name", "Awesome Inc.").
Set("employees", 11),
})The name is a special property which is used in the PostHog UI for the name of the group. If you don’t specify a name property, the group ID will be used instead.
This library is largely based on the analytics-go package.
Ask a question
HelpfulCould be better