> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Count active, new and returning users from product events

> Record what signed-in users do with observe.Track, deploy, and read active, new and returning users per environment with forge obs users, no analytics SDK.

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

* A Forge Go project deployed to Reliant hosting: [Deploy a Go API with managed Postgres](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md).
* Users who sign in to it, so events carry a user id: [Add sign-in with passkeys](https://docs.reliantlabs.io/guides/forge/add-sign-in-passkeys.md).
* 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:

```go internal/handlers/reports/rpc_export_report.go theme={null}
import (
	"log/slog"

	"github.com/reliant-labs/forge/pkg/observe"
)

// inside ExportReport, once the export has been written:
observe.Track(ctx, "report_exported", slog.String("format", req.Msg.GetFormat()))
```

`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:

```bash terminal theme={null}
grep 'product.report_exported' .forge/logs/dev/api.log
```

```json .forge/logs/dev/api.log (trimmed) theme={null}
{"level":"INFO","msg":"product.report_exported","event.name":"product.report_exported","user.id":"…","app.client":"backend","product.format":"csv","trace_id":"451f2d0af1ca72cd0de6b1fdcdd8e79b"}
```

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:

```bash terminal theme={null}
reliant forge env deploy prod v1.4.0 --yes
```

Events reach the environment's telemetry within a minute or two of being recorded.

**4. Count active, new and returning users**

```bash terminal theme={null}
reliant forge obs users prod --since 168h
```

```text Output theme={null}
ENV                                   ACTIVE  Δ    NEW  Δ  RETURNING  Δ    NEW BY  FROM
a2e59df8-0fdb-435a-aa06-f0d170b65031  5       new  0    -  5          new  -       backend
```

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**

```bash terminal theme={null}
reliant forge obs users prod --series 3 --seen-total
```

```text Output (trimmed) theme={null}
a2e59df8-0fdb-435a-aa06-f0d170b65031: 5 users seen in the last 90 days
a2e59df8-0fdb-435a-aa06-f0d170b65031 daily active, 2026-11-18 to 2026-11-20: ▁▁█
```

`--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](https://docs.reliantlabs.io/guides/observability/dashboard-ui-to-code.md).
* **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

> [accordion] 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`.

> [accordion] 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

> [card] [Debug from session timelines](https://docs.reliantlabs.io/guides/observability/debug-frontend-errors-session-timelines.md)
>
> Follow one user's session when the numbers point at a problem.

> [card] [Add a custom metric](https://docs.reliantlabs.io/guides/observability/add-custom-metric.md)
>
> Count things that are not user actions, without a cardinality explosion.

> [card] [Querying with forge obs](https://docs.reliantlabs.io/hosting/observability/forge-obs.md)
>
> Every obs verb and flag.

> [card] [Signals](https://docs.reliantlabs.io/hosting/observability/signals.md)
>
> What a Forge app records with no code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.