Elixir
Contents
This library provides an Elixir HTTP client for PostHog. See the repository for more information.
Installation
This library was built by the community but it's being maintained by the PostHog core team since v1.0.0. Thank you to Nick Kezhaya for building it originally. Thank you to Alex Martsinovich for contributing v2.0.0.
The package can be installed by adding posthog
to your list of dependencies in mix.exs
:
Configuration
You can see all the available configuration options in the PostHog.Config module.
Optionally, you might want to enable the Plug integration to automatically capture events from your Plug-based applications including Phoenix.
Development/Test mode
For a test environment, you can pass in test_mode: true
value to the config. This causes events to be dropped instead of sent to PostHog.
Capturing events
To capture an event, use PostHog.capture/2
:
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
.
Setting event properties
Optionally, you can include additional information with the event by including a properties object:
Context
Carrying distinct_id
around all the time might not be the most convenient approach, so PostHog lets you store it and other properties in a context.
The context is stored in the Logger
metadata and PostHog automatically attaches these properties to any events you capture with PostHog.capture/2
, as long as they happen in the same process.
You can also scope the context to a specific event name:
Batching events
Events are automatically batched and sent to PostHog via a background job.
Special events
PostHog.capture/2
is very powerful and enables you to send events that have special meaning.
In other libraries you'll usually find helpers for these special events, but they must be explicitly sent in Elixir.
For example:
Create alias
Group analytics
Feature flags
PostHog's feature flags enable you to safely deploy and roll back new features as well as target specific users and groups with them.
PostHog.FeatureFlags.check/2
is the main function for checking a feature flag in Elixir. More documentation on it can be found in the HexPM Docs.
Boolean feature flags
It will attempt to take distinct_id
from the context if it's not provided.
Multivariate feature flags
Errors
We'll return an error if the feature flag doesn't exist.
You can also use PostHog.FeatureFlags.check!/2
if you're feeling adventurous or running a script and prefer errors to be raised instead.
Error tracking
Error tracking is enabled by default. It will automatically captures exceptions thrown by the application.
As a matter of fact, since this is built on top of Elixir's Logger
module, it automatically captures any Logger.error
calls.
You can always disable it by setting enable_error_tracking
to false:
Advanced configuration
By default, PostHog starts its own supervision tree and attaches a logger handler.
In certain cases, you might want to run this supervision tree yourself. You can do this by disabling the default supervisor and adding PostHog.Supervisor to your application tree with its own configuration:
Multiple instances
In even more advanced cases, you might want to interact with more than one PostHog project. In this case, you can run multiple PostHog supervision trees, one of which can be the default one:
Then, each function in the PostHog module accepts an optional first argument with the name of the PostHog supervisor tree that will process the capture:
Thanks
The library is maintained by the PostHog team since February 2025. Thanks to nkezhaya for contributing v0.1.0. Thanks to martosaur for contributing v2.0.0.