Govern metric definitions

A tracking plan defines the events you collect. Metric governance defines how those events become numbers people use to make decisions.

Without a shared definition, “active account” can mean logged in, completed a core action, or generated revenue—each with a different time zone, exclusion list, and deduplication rule.

GraphJSON does not currently include a dedicated metric-catalog product. Keep the contract in version control, a reviewed internal catalog, or another durable system, and put a concise version in the saved query and dashboard descriptions.

Write a metric contract#

Every important metric should answer:

Name
Business question
Owner
Population
Qualifying event or state
Entity being counted
Time grain and time zone
Aggregation
Filters and exclusions
Deduplication rule
Source of truth
Freshness expectation
Definition version
Effective date

Example:

Name: Weekly active accounts
Question: How many customer accounts received product value this week?
Owner: Product Analytics
Population: Non-internal paid and trial accounts
Qualifying event: report_exported
Entity: account_id
Grain: ISO week in UTC
Aggregation: unique accounts
Exclusions: environment != production; is_internal != true
Deduplication: uniqExact(account_id)
Source: product_events
Freshness: operational, not contractual
Version: 2
Effective: 2026-07-01

The contract is more important than the display name.

Choose the right entity#

Be explicit about what is counted:

• events
• users
• accounts
• sessions
• orders
• subscriptions
• unique event IDs
• money in one currency

For B2B products, ten active teammates may represent one active customer. A dashboard should not label a user count as “customers.”

Separate facts from interpretation#

Prefer stable events:

{
  "event": "report_exported",
  "account_id": "acct_7",
  "user_id": "usr_42",
  "format": "csv"
}

Then define “active account” in SQL or a documented chart:

SELECT
  toStartOfWeek(toDateTime(timestamp)) AS week,
  uniqExact(JSONExtractString(json, 'account_id')) AS active_accounts
FROM product_events
WHERE
  JSONExtractString(json, 'event') = 'report_exported'
  AND JSONExtractString(json, 'environment') = 'production'
  AND JSONExtractBool(json, 'is_internal') = 0
GROUP BY week
ORDER BY week

Do not put every current business definition into the event name. Facts usually outlive interpretations.

Create one canonical implementation#

For a metric that requires SQL:

1. create one saved query
2. name it after the contract
3. put the concise definition and owner in the description
4. export that query to dashboards
5. reuse its logic rather than rewriting it ad hoc

For a metric the collection visualizer can express, record the collection, aggregation, filters, time zone, and range behavior in the catalog and dashboard description.

Avoid maintaining five almost-identical copies. When copying is unavoidable, link each copy to the canonical definition and test them together.

Define time precisely#

Specify:

• occurrence time versus ingestion time
• reporting time zone
• calendar week definition
• inclusive or exclusive boundaries
• whether the current incomplete period is shown
• late-event treatment

“Monthly revenue” can change depending on whether the chart uses payment time, invoice time, UTC, or the finance team’s reporting zone.

GraphJSON queries use the stored event occurrence timestamp. Preserve that timestamp during retries and backfills.

Define exclusions#

Common exclusions include:

• employees and internal accounts
• test environments
• synthetic monitoring
• deleted or fraudulent accounts
• refunded orders
• unsupported currencies
• events from deprecated schema versions

Exclusions should be based on stable properties or maintained reference data, not a hidden list copied into one analyst’s query.

Distinguish operational and authoritative metrics#

GraphJSON is well suited to product, operational, and customer-facing analytics. It should not silently become the authoritative ledger for:

• account balances
• invoices
• entitlements
• billable usage
• legal audit records

For those metrics:

1. calculate authoritative state in the source system
2. send an analytical event or snapshot to GraphJSON
3. reconcile the analytical result
4. label the dashboard appropriately

An operational estimate can be useful without pretending it is the invoice.

Version a definition change#

Create a new version when the meaning changes materially:

• qualifying event changes
• population changes
• counted entity changes
• time zone changes
• a major exclusion is added
• deduplication changes
• a new identity model joins anonymous and known activity

Do not silently rewrite a historical trend so the same line contains unlike definitions.

Choose one approach:

Preserve old and new series#

Run both definitions during an overlap window:

Weekly active accounts · v1
Weekly active accounts · v2

Use this when decision-makers need to understand the discontinuity.

Use an effective-date branch#

Apply the old definition before a documented date and the new definition after it. Add an annotation outside GraphJSON or a deployment/definition event so the transition remains discoverable.

Recompute all history#

Use this only when the new definition can be applied consistently to retained historical facts. Record that previously published values changed.

Review and approve changes#

A lightweight change record should include:

proposed change
reason
owner
reviewers
affected dashboards and consumers
historical impact
validation query
effective date
rollback plan

Review with product, engineering, data, finance, or operations according to the metric. Revenue and billable-usage definitions need different approval than a feature-adoption exploration.

Detect drift#

Metric drift can happen even when the saved SQL does not change:

• the producer stops emitting
• an identifier becomes optional
• a plan value is renamed
• one application sends a string instead of a number
• retention removes required history
• internal traffic loses its exclusion flag

Use Monitor instrumentation health for the event contract and reconcile critical metrics against their source.

Retire a metric#

Mark a metric deprecated before deleting it:

1. identify the replacement
2. find dashboards, embeds, reports, and decisions that use it
3. notify owners
4. preserve the definition and retirement reason
5. remove or relabel dashboards
6. delete the saved query only after the migration

Do not keep an obsolete metric on an executive dashboard because removing it requires a conversation. That is exactly when governance matters.

Quarterly review#

• Each critical metric has one owner.
• Entity, grain, time zone, and exclusions are explicit.
• Saved SQL and dashboard descriptions match the contract.
• Source reconciliation is current.
• Definition changes have effective dates.
• Deprecated metrics have replacements or removal dates.
• Retention still supports the required historical window.
• Customer-facing definitions remain understandable.

Pair this process with Tracking plan and instrumentation QA and Build a product dashboard.