Before you begin
- A Forge Go project deployed to Reliant hosting: Deploy a Go API with managed Postgres.
- Users who sign in to it, so events carry a user id: Add sign-in with passkeys.
- Forge v1.6.1 or later in the project (
reliant forge --version).
1
Record an event where the user acts
Call
observe.Track in the handler, after the work succeeds. Name the event in snake_case for what the user did:internal/handlers/reports/rpc_export_report.go
Track writes one INFO record named product.report_exported and adds the caller’s user.id from the claims the auth interceptor put on ctx. Each attribute becomes a product.<key> property: keep them low-cardinality (at most 32 per event, each value up to 256 characters). A value that looks like an email address, an IP address or a credential is dropped with a warning, and Track never fails the request.You do not need Track for every action. Sign-ins and the generated CRUD handlers’ <entity>_created, _updated and _deleted writes are product events already.2
See the event locally
Start the stack with The local stack shows the record but cannot count users from it; counting happens on Reliant hosting.
reliant forge env up dev, call the RPC as a signed-in user, and look for the record in the API log:terminal
.forge/logs/dev/api.log (trimmed)
3
Deploy
Ship the change the way you ship any release:Events reach the environment’s telemetry within a minute or two of being recorded.
terminal
4
Count active, new and returning users
terminal
Output
--since, default 7 days, at most 90) and Δ compares each with the range of the same length before it, which reads new when the earlier range was empty. FROM lists the clients the events came from. ENV is the environment’s id.- Active: users with any product event in the range: a sign-in, the daily session heartbeat, a CRUD write or one of your own events. Signing out does not count.
- New: users whose first sign-up is in the range. An environment that has reported no sign-up in the last 90 days counts users first seen in the range instead, except those first seen in the first 7 days of its data: the data, not the user, starts there, so on a new environment everyone reads as returning, as above.
- Returning: active and not new.
5
Break it down by day
terminal
Output (trimmed)
--series N adds one count per UTC day for the last N days, and --seen-total counts every user still retained (90 days). Add --json for a script or an agent: the document (forge.obs.users/v1) holds current and previous counts per environment, first_event_at and retention_days. --explain prints the SQL instead of running it, as a starting point for reliant forge obs query.What this does not do
- No product-analytics dashboards yet. Dashboards for these counts, retention and funnels are coming. Today you read them with
forge obs users, or chart your events in a dashboard of your own: Build a dashboard in the UI and keep it as code. - It does not count anonymous callers as users. An event with no signed-in user carries no
user.id, so it never adds to Active. - It does not count on a local stack.
forge obs users devreads a table only Reliant hosting keeps.
Troubleshooting
Unknown table expression identifier 'default.product_events'
Unknown table expression identifier 'default.product_events'
You asked a local environment. The counts come from Reliant hosting: run the command against a hosted environment such as
prod.product event dropped: name must be snake_case
product event dropped: name must be snake_case
The event name had capitals, dashes or spaces, or was longer than 64 characters. Use lowercase letters, digits and underscores, starting with a letter.
Next steps
Debug from session timelines
Follow one user’s session when the numbers point at a problem.
Add a custom metric
Count things that are not user actions, without a cardinality explosion.
Querying with forge obs
Every obs verb and flag.
Signals
What a Forge app records with no code.