Metrics

The Metrics Pipeline handles application-level observability events.

It is ingestion-driven, plan-aware, and sampling-bound.

Metrics are designed for:

Request analytics
Navigation analytics
Session analytics
Custom application events

They are not governance-grade logs.

Ingestion Flow

Metrics originate from SDKs:

@auditauth/web
@auditauth/next

SDKs capture:

Request metrics
Navigation events
Custom events

Metrics are sent to:


POST /metrics

Ingestion requires:

Valid apiKey
Valid appId

Metrics ingestion does not require a user JWT.

Observability operates at the application boundary.

Ingestion-Time Decisions

Before a metric is persisted, the system evaluates:

feature_access.metrics
metrics.retention_days
metrics.sampling

If:

feature_access.metrics is disabled → metric is discarded
retention_days = 0 → metric is discarded
sampling = 0 → metric is discarded

Sampling is applied before persistence.

All decisions occur at ingestion time.

Sampling Model

Sampling is:

Probabilistic
Based on Math.random()
Applied per event

Sampling characteristics:

Not deterministic per session
Not stored as metadata
Not recalculated after ingestion
Affects only new events when plan changes

If plan changes:

Historical events are unaffected
Only new ingested events follow updated sampling rate

Sampling reduces storage and aggregation load.

Metric Structure

Metrics are stored as raw events.

Typical fields include:

type (request, navigation, custom)
application
session_id
metadata
createdAt
expires_at

Metrics do not include:

Direct user identifiers
Email fields
Identity PII by default

However, metadata is client-controlled.

Clients must avoid sending sensitive data in custom events.

Retention Model

Each metric includes:

expires_at

A TTL index on expires_at ensures:

Physical deletion
Automatic cleanup by MongoDB
No logical-only filtering

Retention is calculated at ingestion time.

Plan upgrades do not extend historical expiration dates.

Plan downgrades do not retroactively reduce existing expiration.

Request Metrics

Request metrics capture:

HTTP method
Path
Status code
Latency

They are:

Captured by SDK
Sent to /metrics
Associated with application
Associated with session_id

They are not directly associated with user identity.

Navigation metrics:

Track client-side route changes
Are SPA-aware (basic pushState/popstate tracking)
Include session_id
Do not include referrer
Do not include duration

Navigation analytics are activity-driven.

There is no explicit session start or end event.

Session boundaries are inferred.

Real-Time Characteristics

Metrics dashboards operate:

Near real-time
Via on-demand Mongo aggregation queries
Without pre-aggregation
Without materialized views
Without caching layer

Each analytics endpoint runs aggregation pipelines dynamically.

This favors simplicity over extreme scalability.

Storage Model

Metrics are stored in a dedicated collection.

Data isolation is logical:

Scoped by application

There is:

No physical partitioning per application
No explicit timestamp indexing beyond TTL
No sharding configuration in code

Storage is optimized for simplicity in Beta.

Plan Enforcement Boundaries

Plan configuration affects:

Whether metrics are stored
Sampling rate
Retention duration
Dashboard feature visibility

It does not currently:

Emit dedicated enforcement audit events
Provide raw metrics export endpoint
Provide per-user metrics gating

Metrics operate at application scope.

Architectural Trade-Offs

The current pipeline favors:

Deterministic ingestion rules
Low system complexity
Minimal background processing
Database-native retention enforcement

It does not yet include:

Pre-aggregation layers
Streaming pipelines
Caching tiers
Advanced anonymization

These may be introduced in future releases.

Next Step

To understand how retention and sampling interact with plan enforcement, continue with:

Retention & Sampling Model