Skip to main content
By the end of this guide your API records a product event each time a user does something that matters, and you can ask how many users were active in the last week, how many were new, and how many came back. There is no analytics SDK to add: a product event is a log record with a reserved shape, and Reliant hosting counts users from the events in each environment.

Before you begin

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 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)
The local stack shows the record but cannot count users from it; counting happens on Reliant hosting.
3

Deploy

Ship the change the way you ship any release:
terminal
Events reach the environment’s telemetry within a minute or two of being recorded.
4

Count active, new and returning users

terminal
Output
The counts cover the range (--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 dev reads a table only Reliant hosting keeps.

Troubleshooting

You asked a local environment. The counts come from Reliant hosting: run the command against a hosted environment such as prod.
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.