✅ TL;DR
ChronoGraf is a high-performance, Java-based time series analytics platform backed by PostgreSQL.
It supports three complementary data modes:
- 🔢 Event Counters
- 📊 Aggregated Histograms
- 📃 Raw Events
Each is available across six fixed UTC-aligned temporal granularities:5s, 1m, 1h, 1d, 1w, 1mo.
With mixed-granularity querying, dynamic percentile calculation, and late event correction (via upward propagation), ChronoGraf provides scalable, accurate analytics for:
- Real-time dashboards
- Long-term trends
- SLA enforcement
- Compliance and audit use cases
It runs as a standalone REST service or embedded Java library, and is container-ready.
🏠 Implementation Architecture
- Java 17
- Spring Boot + JPA/Hibernate
- Time series data stored in PostgreSQL
- Partitioned by time and metric key set
🧱 Deployment Modes
| Mode | Description |
|---|---|
| Standalone | REST-based microservice (Docker-supported) |
| Embedded | Drop-in Java module for Spring Boot projects |
✅ Includes: Dockerfile, docker-compose.yml, initdb/, and CLI tooling in scripts/.
🧠 Data Models and Storage Types
🔢 1. Event Counters
- Tracks total number of events per time interval
- Efficient: 8 bytes per segment
- Granularities: all six
- Use cases: request count, error rate, transaction volume
✅ Late Event Handling
✅ In-place updates
✅ Upward rollups and cache invalidation
📊 2. Aggregated Histograms 🧭
- Stores value distributions (e.g., latency, sizes)
- Bucketed using key-set-defined shapes: linear / exponential / custom
- Use cases: percentile queries, statistical summaries
✅ Dynamic percentile support
✅ Precomputed P50, P90, P95, P99 (optional per segment)
🧭 Planned support for categorical histograms (e.g., status codes, error types)
📃 3. Raw Events
- Stores full-resolution events with metadata and dimensions
- For forensic inspection, audit trails, deep filtering
- Immutable, append-only
🗂️ Granularity Strategy
| Granularity | Use Case |
|---|---|
| 5s | High-precision real-time |
| 1m | Operational dashboards |
| 1h | Mid-term trends |
| 1d | Daily summaries |
| 1w | Weekly aggregation |
| 1mo | Monthly / archival analysis |
✅ All data aligned to these granularities for consistency and performance.
🤤 Mixed Granularity Querying 🧭
ChronoGraf uses a planner to minimize read costs while preserving boundary precision.
Example: Query from 21 Oct 13:30:25 → 23 Oct 09:30:30
| Phase | Range | Granularity | Segments |
|---|---|---|---|
| Start boundary | 13:30:25 → 13:31:00 | 5s | 7 |
| Hour fill | 13:31:00 → 14:00:00 | 1m | 29 |
| Bulk segment | 14:00 → 09:00 (2d) | 1h | 43 |
| End approach | 09:00 → 09:30 | 1m | 30 |
| End boundary | 09:30:00 → 09:30:30 | 5s | 6 |
🔍 Total: 115 segments instead of 30,000+ (pure 5s scan)
📊 Percentile Support 🧭
✅ Dynamic Percentile Calculation
- Arbitrary percentiles (P68, P99.7, etc.)
- Based on cumulative histogram with linear interpolation
⚠️ P99.9+ requires ≥1000 buckets for useful resolution
✅ Precomputed Percentiles
- P50, P90, P95, P99 stored per segment
- Enables fast SLA dashboards and alerting
- Cached and available across all granularities
🛠️ Late Event Arrival & Fast Propagation 🧭
Late-arriving events are handled with accuracy:
- Routed to correct segment (5s/1m/etc.)
- Updates relevant buckets and counters
- Upward propagation (to 1h/1d/1w/1mo)
- Affected caches (e.g., percentiles) are invalidated and recomputed
✅ Implemented for event counters
🧭 Partial for histograms
⚙️ Performance Optimizations
| Optimization | Description |
|---|---|
| 🧭 Temporal delta encoding | Only changed buckets are stored |
| 🧭 Sparse encoding | Skips zero-count buckets |
| Bucket shape reuse | Avoids duplicate metadata per segment |
| 🧭 Parallel retrieval | Per-granularity fetch in parallel |
| In-memory aggregation | Efficient sum + percentile computation |
| 🧭 Caching layers | Segment, shape, and aggregation caches |
Compression Ratios:
- Sparse data: 80–90%
- Typical: 60–70%
- Dense: 40–50%
🔒 Fault Handling
| Condition | Behavior |
|---|---|
| 🧭 Bucket misalignment | ❌ Query rejected before execution |
| Partial segment loss | ✅ Partial results returned |
| 🧭 Invalid percentiles | ❌ Clear validation errors |
| 🧭 Counter overflow risk | ✅ Future-proofed via safe type enforcement |
📈 Monitoring & Metrics
ChronoGraf tracks system health and behavior:
- 🧭 Query latency (in progress)
- 🧭 Bucket alignment status
- 🧭 Cache hit/miss ratios
- 🧭 Late event handling metrics
- 🧭 Granularity distribution usage
- 🧭 Rollup propagation and recomputation latency
🔀 Integration and Deployment
| Mode | Description |
|---|---|
| Standalone | Exposes REST API, runs in Docker or VM |
| Embedded | Spring Boot library – plug in directly |
✅ Includes: Dockerfile, docker-compose.yml, initdb/, CLI tooling
📈 Use Case Scenarios
- Real-time dashboards (e.g., P95 latency per service/region)
- SLA enforcement with precomputed + dynamic percentiles
- Event auditing (by ID, timestamp, or field)
- Delayed pipelines with guaranteed correction
- High-volume metrics via event counters
- Executive summaries using 1w/1mo rollups
🏢 Multi-Tenant Identity & Distributed Tracing
ChronoGraf supports secure, isolated metric ingestion in multi-tenant deployments.
🔐 Authentication Methods
| Method | Description |
|---|---|
| mTLS | Mutual TLS for trusted service communication |
| SPIFFE | Mesh-based identity (e.g., spiffe://org/...) |
| JWT | OAuth2 access tokens with tenant-scoped claims |
| BasicAuth | Legacy passkey credentials |
📄 Derived Context Fields
| Field | Purpose |
|---|---|
| Tenant ID | Enforces metric isolation |
| Service ID | Records the producer/consumer identity |
| Instance ID | Tags service instance (static/dynamic) |
Derived from: tokens, SPIFFE, mTLS certs.
🔁 Parent Event ID Support
ChronoGraf supports distributed tracing via parent_event_id:
event-A
├─ event-A.1
│ └─ event-A.1.1
└─ event-A.2
🔍 Use cases:
- Trace reconstruction
- Retry/failure lineage
- Async process visibility
🌱 Roadmap Features 🧭
- 🧭 Categorical histograms (status codes, enums)
- 🧭 Configurable bucket regeneration on schema change
- 🧭 Counter overflow detection and throttling
- 🧭 Segment-level TTL and archival support
- 🧭 Enhanced UI dashboards for histogram visualizations
ChronoGraf is scalable, observable, secure, and ready for the future.
Whether you need real-time metrics, forensic traceability, or executive-level rollups — ChronoGraf delivers.