Core Concepts

Overview#

JustAnalytics is an end-to-end observability platform that replaces multiple tools with a single, privacy-first solution. It combines web analytics, error tracking, distributed tracing, log aggregation, infrastructure metrics, and uptime monitoring.

Architecture#

JustAnalytics uses a simple architecture:

• Client-side scripts (tracker.js, monitor.js) collect browser-side analytics and errors
• Server-side SDKs (@justanalyticsapp/node) collect backend traces, errors, logs, and metrics
• Ingestion APIs receive data and store it in PostgreSQL
• Dashboard provides real-time visualization and analysis

Key Concepts#

Sites#

A Site is the top-level organizational unit. Each site has a unique Site ID and represents one application or website. All data is scoped to a site, ensuring complete tenant isolation.

Events#

Events are the core data unit for web analytics. Every pageview, click, scroll, or custom interaction generates an event. Events include:

• URL and referrer information
• Device and browser details
• Geographic location (derived from IP, which is never stored)
• Session context
• Custom properties you define

Sessions#

A session groups events from a single visitor. Sessions expire after 30 minutes of inactivity. JustAnalytics identifies sessions without cookies using a combination of IP hash, user agent, and screen resolution.

Traces and Spans#

In the APM module, a Trace represents a single end-to-end request as it flows through your system. Each trace is composed of Spans -- individual units of work like an HTTP request, a database query, or a function call.

Traces use the W3C Trace Context standard (traceparent header) for propagation across services.

Error Groups#

Errors are automatically grouped by their stack trace fingerprint. An Error Group represents a unique error type, while individual Error Events are specific occurrences.

API Keys#

Server-side SDKs authenticate using API keys. You can create multiple keys per site with different permissions. API keys use the format ja_sk_... and should be kept secret.

Privacy First#

JustAnalytics is designed with privacy as a core principle:

• No cookies -- sessions are identified without setting any cookies
• No personal data storage -- IP addresses are hashed and never stored in raw form
• DNT compliance -- respects the Do Not Track browser setting
• Bot filtering -- automatically excludes known bots and crawlers
• GDPR compliant -- no consent banner needed since no personal data is collected

Data Flow#

1. Collection -- Scripts/SDKs collect events, spans, errors, and logs
2. Ingestion -- Data is sent to /api/track (client) or /api/ingest/* (server) endpoints
3. Storage -- PostgreSQL stores raw events and pre-computed aggregations
4. Aggregation -- Background jobs compute hourly and daily rollups for fast queries
5. Visualization -- Dashboard queries aggregated data for charts and real-time metrics