ga4

The ga4 plugin reports Google Analytics 4 figures for every account and property one Google login can see. Per property it sends users active right now, users, sessions and page views for today, yesterday and the last 7 days, and 30 days of daily figures. It answers "is traffic still arriving", and it pages when Google stops answering.

Set it up

Google Analytics has no service-account path for this plugin. It runs on a user refresh token with the analytics.readonly scope, minted once by hand.

1. In Google Cloud, create an OAuth client of type Desktop app and download its JSON.

2. Enable the Google Analytics Admin API and the Google Analytics Data API in that project.

3. Set the OAuth consent screen to In production, or Internal. A client left in Testing hands out refresh tokens that expire after 7 days.

4. From the client directory, run the token helper.

   node etc/google-auth.mjs --source=ga4 <client_secret.json> [ssh-host] [remote-config-path]

   It opens Google's consent page, catches the redirect on a loopback port and trades the code for a refresh token. Before it saves anything, it checks that the token can see at least one Analytics account. With no ssh-host it writes the ga4 block into ./client.config.json. With one, it writes into that host's config over ssh and sends the secrets on stdin. Set BROWSER_APP to pick the browser that holds the right Google login.

5. Add ga4 to the agent's plugins array and restart the agent.

The Google account you consent with must have access to the Analytics properties.

{
  "plugins": ["ga4"],
  "ga4": {
    "name": "Google Analytics",
    "uniqueId": "ga4",
    "refreshInterval": 900000,
    "clientId": "<CLIENT_ID>.apps.googleusercontent.com",
    "clientSecret": "<CLIENT_SECRET>",
    "refreshToken": "<REFRESH_TOKEN>",
    "accounts": ["<GA_ACCOUNT_ID>"]
  }
}

Option	Default	What it does
clientId	required	OAuth client id.
clientSecret	required	OAuth client secret.
refreshToken	required	Refresh token from google-auth.mjs.
accounts	every account	GA account ids to collect, as strings. Accounts outside the list are never queried.
refreshInterval	900000	Milliseconds between reports.
timeout	20000	Milliseconds per HTTP request.

Set accounts unless the login sees only this customer's accounts. A Google login often sees accounts that belong to other customers, and everything collected lands in the view of the system this agent reports to.

client.config.json.example has no ga4 block. google-auth.mjs creates one.

What it reports

One report per interval, sent immediately on start.

• name, always Google Analytics.
• properties, the number of properties reported.
• accounts[], each with id, name and properties[].
• Per property, id, name, asOf, which is today's date in the property's time zone, and activeNow, the users active in the last 30 minutes. activeNow is null when the realtime call fails.
• Per property, today, yesterday and last7, each with users, sessions and views. The 7-day users figure comes from GA itself, so one person on three days counts once.
• Per property, daily with a start date and 30-entry users, sessions and views arrays. Days with no traffic are filled with 0.
• A property that fails carries error in place of figures. The others still report.
• When the whole poll fails, the report is { error }, plus authExpired: true if Google answered invalid_grant.

Only ordinary GA4 properties are listed. The plugin filters out other property types.

The server does not write a history row per report. The type is in SELF_HISTORIED, because each report already carries 30 days.

When it alerts

Condition	Severity	Reason text
authExpired	error	Google Analytics: authorization expired, mint a new refresh token
error	error	Google Analytics: <error>
clientId, clientSecret or refreshToken missing	error	Google Analytics: ga4 plugin needs clientId, clientSecret and refreshToken
One or more properties carry error	warning	Google Analytics: <n> properties failed to report (<first name>: <error>)

A new problem does not notify on the first bad report. The server waits for a second consecutive bad report, which is 15 minutes later at the default interval. A report that comes back clean resolves the alert.

There is no traffic threshold. A property that drops to zero users does not alert.

On the dashboard

The card is titled Google Analytics.

Reading	Source
PROPERTIES	Number of properties
ACTIVE NOW	Sum of activeNow across properties
USERS TODAY	Sum of today.users
SESSIONS 7D	Sum of last7.sessions

Below that, one row per property with today's users, or error in amber. While the report carries a top-level error, the figures blank out rather than showing zeroes. The card links to Google Analytics.

The card goes OFFLINE after 1800 seconds without a report, which is two missed polls at the default interval.

Gotchas

• A failed realtime call is silent. activeNow becomes null, and ACTIVE NOW counts it as 0.
• Changing accounts is a privacy decision, not a display one. Hiding properties and nicknames live in the portal.
• Refresh tokens from a consent screen in Testing die after 7 days, and the card turns red with authorization expired. Run google-auth.mjs again with the app set to In production.
• If Google returns no refresh token, remove the app's access at myaccount.google.com/permissions and run the helper again.