{"id":45316857,"url":"https://github.com/josedab/chronicle","last_synced_at":"2026-02-21T07:52:22.579Z","repository":{"id":337798587,"uuid":"1146709912","full_name":"josedab/chronicle","owner":"josedab","description":"Chronicle is an embedded time-series database for Go designed for constrained and edge environments. It provides compressed columnar storage, SQL-like queries, retention, and downsampling in a single-file format.","archived":false,"fork":false,"pushed_at":"2026-02-20T10:53:34.000Z","size":15265,"stargazers_count":0,"open_issues_count":11,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-20T14:38:11.943Z","etag":null,"topics":["columnar-storage","database","edge-computing","embedded-database","golang","iot","monitoring","prometheus","time-series","tsdb"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/josedab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-31T14:55:09.000Z","updated_at":"2026-02-20T10:48:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/josedab/chronicle","commit_stats":null,"previous_names":["josedab/chronicle"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/josedab/chronicle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josedab%2Fchronicle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josedab%2Fchronicle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josedab%2Fchronicle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josedab%2Fchronicle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/josedab","download_url":"https://codeload.github.com/josedab/chronicle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josedab%2Fchronicle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29676855,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T06:23:40.028Z","status":"ssl_error","status_checked_at":"2026-02-21T06:23:39.222Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["columnar-storage","database","edge-computing","embedded-database","golang","iot","monitoring","prometheus","time-series","tsdb"],"created_at":"2026-02-21T07:52:22.439Z","updated_at":"2026-02-21T07:52:22.573Z","avatar_url":"https://github.com/josedab.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chronicle\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/chronicle-db/chronicle.svg)](https://pkg.go.dev/github.com/chronicle-db/chronicle)\n[![Go Report Card](https://goreportcard.com/badge/github.com/chronicle-db/chronicle)](https://goreportcard.com/report/github.com/chronicle-db/chronicle)\n[![codecov](https://codecov.io/gh/chronicle-db/chronicle/branch/main/graph/badge.svg)](https://codecov.io/gh/chronicle-db/chronicle)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![CI](https://github.com/chronicle-db/chronicle/actions/workflows/ci.yml/badge.svg)](https://github.com/chronicle-db/chronicle/actions/workflows/ci.yml)\n\nChronicle is an embedded time-series database for Go designed for constrained and edge environments. It provides compressed columnar storage, SQL-like queries, retention, and downsampling in a single-file format.\n\n## Installation\n\n```bash\ngo get github.com/chronicle-db/chronicle\n```\n\n**Requirements:** Go 1.24 or later — Chronicle uses recent Go features (range-over-func, enhanced generics). If Go 1.24 is not yet packaged for your OS, install from [go.dev/dl](https://go.dev/dl/) or use `go install golang.org/dl/go1.24@latest`.\n\n## Getting Started\n\nNew to Chronicle? Start with the **[Getting Started Guide](docs/GETTING_STARTED.md)** for a 10-minute walkthrough.\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"log\"\n    \"time\"\n\n    \"github.com/chronicle-db/chronicle\"\n)\n\nfunc main() {\n    db, err := chronicle.Open(\"sensors.db\", chronicle.Config{\n        Storage: chronicle.StorageConfig{\n            MaxMemory:         64 * 1024 * 1024,\n            PartitionDuration: time.Hour,\n            BufferSize:        10_000,\n        },\n        Retention: chronicle.RetentionConfig{\n            RetentionDuration: 7 * 24 * time.Hour,\n        },\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    defer db.Close()\n\n    _ = db.Write(chronicle.Point{\n        Metric:    \"temperature\",\n        Tags:      map[string]string{\"room\": \"living\"},\n        Value:     22.5,\n        Timestamp: time.Now().UnixNano(),\n    })\n\n    result, err := db.Execute(\u0026chronicle.Query{\n        Metric: \"temperature\",\n        Tags:   map[string]string{\"room\": \"living\"},\n        Start:  time.Now().Add(-time.Hour).UnixNano(),\n        End:    time.Now().UnixNano(),\n        Aggregation: \u0026chronicle.Aggregation{\n            Function: chronicle.AggMean,\n            Window:   5 * time.Minute,\n        },\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    _ = result\n}\n```\n\n## Core API\n\nThese are the essential types and functions for most use cases:\n\n| Symbol | Purpose |\n|--------|---------|\n| `Open(path, config)` | Create or open a database |\n| `DB.Write(point)` | Write a single point |\n| `DB.WriteBatch(points)` | Write multiple points |\n| `DB.Execute(query)` | Run a query and get results |\n| `DB.Close()` | Close the database |\n| `Point` | A metric name, float64 value, nanosecond timestamp, and tags |\n| `Query` | Metric, time range, tag filters, aggregation |\n| `Config` / `DefaultConfig()` | Database configuration with sensible defaults |\n| `ConfigBuilder` | Fluent API: `NewConfigBuilder(path).WithRetention(...).Build()` |\n| `Result` | Query output containing matched `Points` |\n\nFor the full API surface, see the [Go reference](https://pkg.go.dev/github.com/chronicle-db/chronicle) or [`api_stability.go`](api_stability.go).\n\n## Features\n\n\u003e Stability tiers: ✅ Stable — ⚠️ Beta — 🧪 Experimental.\n\u003e See [API Maturity](#api-maturity) for definitions.\n\n### Core Storage ✅\n- **Single-file storage** with append-only partitions\n- **Gorilla float compression** and delta timestamp encoding\n- **Dictionary tag compression** and per-column encoding selection\n- **WAL-based crash recovery** with rotation\n- **Pluggable storage backends** (file, memory, S3, tiered)\n\n### Query \u0026 Analytics\n- ✅ **SQL-like query parser** (limited subset)\n- ⚠️ **PromQL subset support** for Prometheus compatibility\n- ⚠️ **GraphQL API** with interactive playground\n- ⚠️ **Time-series forecasting** (Holt-Winters, exponential smoothing, anomaly detection)\n- ⚠️ **Recording rules** for pre-computed queries\n- ✅ **Native histograms** with exponential bucketing\n- ✅ **Retention policies** — time-based and size-based limits\n- ✅ **Downsampling** background workers\n- ⚠️ **Continuous queries** (materialized views)\n- 🧪 **Query assistant** — natural language to SQL/PromQL\n\n### Integrations\n- ⚠️ **HTTP API** with Influx line protocol, Prometheus remote write\n- ⚠️ **OpenTelemetry receiver** for OTLP metric ingestion\n- ⚠️ **Grafana data source plugin** for visualization\n- 🧪 **WebAssembly compilation** for browser/edge runtime\n- 🧪 **Admin UI dashboard** for monitoring and exploration\n- ⚠️ **Query federation** across multiple instances\n- ⚠️ **Data export** to CSV, JSON, Parquet formats\n\n### Enterprise Features\n- ✅ **Encryption at rest** with AES-256-GCM\n- ⚠️ **Schema registry** for metric validation\n- ⚠️ **Multi-tenancy** with namespace isolation\n- ⚠️ **Alerting engine** with webhook notifications\n- ⚠️ **Streaming API** for real-time subscriptions\n- ⚠️ **Exemplar support** for trace correlation\n- ⚠️ **Cardinality management** with limits and alerts\n- ⚠️ **Delta/incremental backups** with retention\n- ⚠️ **Outbound replication** to a central endpoint\n- 🧪 **Vector embeddings** for ML/semantic search\n- 🧪 **Continuous profiling** with metric correlation\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│  API Layer                                                   │\n│  /write  /query  /api/v1/query  /v1/metrics  /stream         │\n├──────────────────────────────────────────────────────────────┤\n│  Core Engine                                                 │\n│  Write Buffer → Schema Validation → Stream Hub               │\n│  Query Engine (SQL + PromQL) → Alert Manager                 │\n├──────────────────────────────────────────────────────────────┤\n│  Partition Manager                                           │\n│  [Partition 0: t0-t1] [Partition 1: t1-t2] ... [Active]     │\n├──────────────────────────────────────────────────────────────┤\n│  Storage Backend (pluggable)                                 │\n│  FileBackend │ MemoryBackend │ S3Backend │ TieredBackend     │\n├──────────────────────────────────────────────────────────────┤\n│  Background: WAL Recovery │ Retention │ Downsampling │ Compaction │\n└──────────────────────────────────────────────────────────────┘\n```\n\nFor a detailed walkthrough, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).\n\n## API Maturity\n\nChronicle is pre-1.0. Not all features have the same stability level.\n\n| Tier | Meaning | Examples |\n|------|---------|----------|\n| **Stable** | Covered by semver. Safe for production. | `DB`, `Point`, `Query`, `Open()`, `Write()`, `Execute()`, `Config` |\n| **Beta** | May change between minor versions. | PromQL, HTTP API, Grafana plugin, replication |\n| **Experimental** | May change or be removed without notice. | Jupyter kernel, WASM runtime, TinyML, ZK proofs |\n\nSee [`api_stability.go`](api_stability.go) for the full classification of every exported symbol.\n\n## Configuration\n\nLegacy flat fields (for example, `MaxMemory`) remain supported, but new grouped config is preferred.\n\n```go\ncfg := chronicle.Config{\n    Path: \"data.db\", // Database file path\n    Storage: chronicle.StorageConfig{\n        MaxMemory:         64 * 1024 * 1024, // Max memory for buffers (64MB)\n        MaxStorageBytes:   0,                // Max storage size (0 = unlimited)\n        PartitionDuration: time.Hour,        // Time span per partition\n        BufferSize:        10_000,           // Write buffer size\n    },\n    Retention: chronicle.RetentionConfig{\n        RetentionDuration: 7 * 24 * time.Hour, // Data retention period\n    },\n    Query: chronicle.QueryConfig{\n        QueryTimeout: 30 * time.Second,\n    },\n    HTTP: chronicle.HTTPConfig{\n        HTTPEnabled: false, // Enable HTTP API\n        HTTPPort:    8086,  // HTTP port\n    },\n    StrictSchema: false, // Enforce schema validation\n    Encryption: \u0026chronicle.EncryptionConfig{\n        Enabled:     false, // Enable encryption at rest\n        KeyPassword: \"\",    // Password for key derivation\n    },\n}\n```\n\n## HTTP API\n\nWhen `HTTPEnabled: true`, the following endpoints are available:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/health` | GET | Health check |\n| `/write` | POST | Write points (Influx line protocol) |\n| `/query` | POST | Execute SQL-like query |\n| `/metrics` | GET | List all metrics |\n| `/api/v1/query` | GET/POST | Prometheus instant query |\n| `/api/v1/query_range` | GET/POST | Prometheus range query |\n| `/api/v1/forecast` | POST | Time-series forecasting |\n| `/api/v1/histogram` | GET/POST | Native histogram operations |\n| `/v1/metrics` | POST | OpenTelemetry OTLP JSON ingestion |\n| `/schemas` | GET/POST/DELETE | Schema registry CRUD |\n| `/api/v1/alerts` | GET | Get active alerts |\n| `/api/v1/rules` | GET/POST | Alerting rules management |\n| `/stream` | GET | WebSocket streaming subscription |\n| `/graphql` | POST | GraphQL API |\n| `/graphql/playground` | GET | Interactive GraphQL playground |\n| `/admin` | GET | Admin UI dashboard |\n| `/api/v1/prom/write` | POST | Prometheus remote write |\n\n## Project Structure\n\n```\nchronicle/\n├── internal/              # Private implementation details\n│   ├── adminui/           # Admin UI dashboard components\n│   ├── anomaly/           # Anomaly detection and classification\n│   ├── bits/              # Bit-level I/O utilities\n│   ├── cep/               # Complex event processing engine\n│   ├── chprotocol/        # ClickHouse-compatible protocol\n│   ├── cluster/           # Cluster coordination and write routing\n│   ├── continuousquery/   # Continuous query execution engine\n│   ├── cql/               # CQL query engine and parser\n│   ├── digitaltwin/       # Digital twin synchronization\n│   ├── edgemesh/          # Edge mesh networking (CRDT, mDNS)\n│   ├── encoding/          # Compression codecs (Gorilla, Delta, Dictionary)\n│   ├── gpucompression/    # GPU-accelerated compression\n│   ├── hardwareaccel/     # Hardware acceleration (SIMD, FPGA)\n│   ├── oteldistro/        # OpenTelemetry distribution helpers\n│   ├── pluginmkt/         # Plugin marketplace and registry\n│   ├── query/             # Query parsing and aggregation\n│   └── raft/              # Raft consensus implementation\n├── docs/                  # Documentation\n│   ├── ARCHITECTURE.md    # System design overview\n│   ├── BENCHMARKS.md      # Performance benchmarks\n│   └── adr/               # Architecture Decision Records\n├── examples/              # Example applications\n│   ├── core-only/         # Minimal write and query (start here)\n│   ├── simple/            # Basic write and query\n│   ├── http-server/       # Full HTTP API server\n│   ├── iot-collector/     # IoT sensor data collection\n│   ├── prometheus-compatible/ # Prometheus backend\n│   └── analytics-dashboard/   # Forecasting and alerting\n├── .github/               # GitHub configuration\n│   └── workflows/         # CI/CD workflows\n├── *.go                   # Main package source files\n├── *_test.go              # Test files\n└── doc.go                 # Package documentation\n```\n\nThe main `chronicle` package provides the public API. Internal packages under `internal/`\ncontain implementation details that should not be imported directly.\n\nFor a detailed package organization map and restructuring plan, see [docs/PACKAGES.md](docs/PACKAGES.md).\n\n## Documentation\n\n- **[Getting Started](docs/GETTING_STARTED.md)** — 10-minute tutorial from install to query\n- **[Core API Reference](docs/CORE_API.md)** — The 10 functions you need for 90% of use cases\n- [API Documentation](https://pkg.go.dev/github.com/chronicle-db/chronicle)\n- [HTTP API Reference](docs/API.md)\n- [Features Guide](docs/FEATURES.md)\n- [Configuration Reference](docs/CONFIGURATION.md)\n- [Plugin Development](docs/PLUGIN_DEVELOPMENT.md)\n- [Testing Guide](docs/TESTING.md)\n- [Architecture Overview](docs/ARCHITECTURE.md)\n- [Benchmarks](docs/BENCHMARKS.md)\n- [FAQ / Troubleshooting](docs/FAQ.md)\n- [Migration Guide](docs/MIGRATION.md)\n\n## Development\n\n### Testing\n\nChoose the right test speed for your workflow:\n\n| Command | Time | What it runs | When to use |\n|---------|------|-------------|-------------|\n| `make check` | ~15s | `go vet` + internal tests | Pre-commit validation ⚡ |\n| `make test-fast` | ~5s | Internal packages only | TDD fast iteration ⚡ |\n| `make quickcheck` | ~25s | `go vet` + all short tests | Before pushing |\n| `make test-short` | ~30s | All tests, short mode | Before pushing |\n| `make test` | ~45s | All tests + race detector | CI-level confidence |\n| `make test-cover` | ~60s | All tests + HTML coverage | Coverage review |\n\n```bash\n# Run a single test\ngo test -run TestMyFeature -count=1 -v\n\n# Run benchmarks\nmake bench\n```\n\nSee [docs/TESTING.md](docs/TESTING.md) for writing tests, test helpers, and debugging tips.\n\n### Other Commands\n\n```bash\n# Install development tools\nmake setup\n\n# Run all checks (lint + test + build)\nmake all\n\n# Run linters\nmake lint\n\n# Format code\nmake fmt\n\n# See all commands\nmake help\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## Security\n\nFor reporting security vulnerabilities, see [SECURITY.md](SECURITY.md). Chronicle includes:\n\n- AES-256-GCM encryption at rest (opt-in)\n- Request body limits and rate limiting on HTTP endpoints\n- Query timeout limits to prevent DoS\n- No `unsafe` package usage in core code\n- Path traversal protection in storage backends\n\n## License\n\nApache 2.0 - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosedab%2Fchronicle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosedab%2Fchronicle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosedab%2Fchronicle/lists"}