sketchlog 1.2.1__tar.gz

sketchlog-1.2.1/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+## 1.2.1
+
+### Fixed
+
+- Prevent Windows checkpoint writers from being starved by concurrent same-path
+  readers, while retaining bounded retries for readers in other processes.
+
+## 1.2.0
+
+Python 3.10–3.14 are supported. Python 3.9 reached upstream end of life and is
+no longer an install target.
+
+### Security
+
+- Canonically validate all serialized state before native allocation.
+- Restrict mesh peers to canonical allowlisted origins, disable redirects, cap
+  membership, and require a cluster secret.
+- Add namespace-scoped HTTP, SQL, aggregate, delete, and WebSocket authorization.
+- Persist and gossip versioned deletion tombstones to prevent stale resurrection.
+- Bound authenticated mesh requests and responses, split oversized anti-entropy
+  exchanges into progressive chunks, and reject malformed/non-finite peer state.
+- Cap durable local tombstones and atomically commit SQL state deletion with its
+  tombstone so capacity or storage failure cannot create an unsafe delete.
+- Scan containers before publication and sign image and Helm digests.
+
+### Correctness and durability
+
+- Replace unbounded DDSketch dense spans with bounded sparse stores.
+- Make native batch ingestion transactional and correct for strided NumPy views.
+- Align integer event keys and cross-backend merges.
+- Use conservative threshold counts for SLO alert safety.
+- Make file checkpoints flush/fsync/atomically replace and tolerate Windows
+  reader-sharing windows.
+- Bound storage locks and make eviction wait for durable persistence.
+- Bound checkpoint and database decompression, reject trailing/truncated state,
+  and retain the prior checkpoint when a replacement exceeds the state limit.
+
+### Features
+
+- Add executable anomaly comparison, SLO recommendation, sketch diffing, live
+  Streaming SQL, and precision-safe WASM merge contracts.
+- Publishable TypeScript, React, WASM, and in-repository Go modules.
+- Authenticated SDKs with credential providers, redirect and response-size
+  defenses, sanitized errors, close methods, and real transport retry tests.
+- Runnable Linux/BCC collector with merge export and health/readiness endpoints.
+- StatefulSet-based Helm mesh mode and an `autoscaling/v2` HPA.
+
+### Quality and operations
+
+- Generate and verify the OpenAPI contract.
+- Serialize WebSocket 64-bit counters without JavaScript precision loss and
+  drive dashboard cardinality from the HyperLogLog estimate.
+- Add web lint/build/component gates, branch coverage and critical subsystem
+  floors, fail-closed benchmark gates, Helm variants, WASM Node/browser smoke
+  tests, immutable Action pins, SBOM/provenance, and public-registry smoke tests.
+- Synchronize version 1.2.0 across all coupled artifacts and rewrite operations
+  and feature documentation to match executable behavior.

sketchlog-1.2.1/CMakeLists.txt

@@ -0,0 +1,43 @@
+cmake_minimum_required(VERSION 3.14)
+project(SketchLog CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+if(MSVC)
+    set(CXX_WARNINGS /W4 /EHsc)
+else()
+    set(CXX_WARNINGS -Wall -Wextra)
+endif()
+
+# Unified sketchlog library (header-only)
+add_library(sketchlog INTERFACE)
+target_include_directories(sketchlog INTERFACE include)
+
+# Scale benchmark
+add_executable(benchmark_scale benchmarks/benchmark_scale.cpp)
+target_link_libraries(benchmark_scale PRIVATE sketchlog)
+target_include_directories(benchmark_scale PRIVATE include)
+target_compile_options(benchmark_scale PRIVATE ${CXX_WARNINGS})
+
+# Tests
+enable_testing()
+add_executable(tests_cpp tests/test_cpp.cpp)
+target_link_libraries(tests_cpp PRIVATE sketchlog)
+target_include_directories(tests_cpp PRIVATE include)
+target_compile_options(tests_cpp PRIVATE ${CXX_WARNINGS})
+add_test(NAME cpp_tests COMMAND tests_cpp)
+
+# Fuzzing
+option(ENABLE_FUZZING "Build fuzz targets" OFF)
+if(ENABLE_FUZZING)
+    if(NOT MSVC)
+        add_executable(fuzz_cpp tests/fuzz_cpp.cpp)
+        target_link_libraries(fuzz_cpp PRIVATE sketchlog)
+        target_include_directories(fuzz_cpp PRIVATE include)
+        target_compile_options(fuzz_cpp PRIVATE ${CXX_WARNINGS} -fsanitize=fuzzer)
+        target_link_options(fuzz_cpp PRIVATE -fsanitize=fuzzer)
+    else()
+        message(WARNING "Fuzzing is not supported on MSVC without explicit Clang integration.")
+    endif()
+endif()

sketchlog-1.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sketchlog contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sketchlog-1.2.1/MANIFEST.in

@@ -0,0 +1,12 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include SECURITY.md
+include docs/guarantees.md
+recursive-include python/sketchlog *.py
+include CMakeLists.txt
+recursive-include cpp *.cpp
+recursive-include include *.hpp
+include wasm/bindings.cpp
+include wasm/sketchlog.js
+include build_wasm.*

sketchlog-1.2.1/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: sketchlog
+Version: 1.2.1
+Summary: Bounded-memory streaming metrics with DDSketch, HyperLogLog, and Count-Min Sketch.
+Author: Bala Vignesh S
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SBALAVIGNESH123/sketchlog
+Project-URL: Repository, https://github.com/SBALAVIGNESH123/sketchlog
+Project-URL: Issues, https://github.com/SBALAVIGNESH123/sketchlog/issues
+Keywords: streaming,metrics,ddsketch,hyperloglog,count-min-sketch,percentile,p99,monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material<10,>=9.5.0; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: numpy; extra == "test"
+Requires-Dist: httpx; extra == "test"
+Requires-Dist: hypothesis; extra == "test"
+Requires-Dist: greenlet; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: mkdocs<2,>=1.6; extra == "dev"
+Requires-Dist: mkdocs-material<10,>=9.5.0; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: types-psutil; extra == "dev"
+Provides-Extra: opentelemetry
+Requires-Dist: opentelemetry-api; extra == "opentelemetry"
+Requires-Dist: opentelemetry-sdk; extra == "opentelemetry"
+Requires-Dist: opentelemetry-exporter-otlp; extra == "opentelemetry"
+Provides-Extra: server
+Requires-Dist: fastapi<1,>=0.100.0; extra == "server"
+Requires-Dist: uvicorn<1,>=0.20.0; extra == "server"
+Requires-Dist: pydantic<3,>=2.0; extra == "server"
+Requires-Dist: structlog>=23.1.0; extra == "server"
+Requires-Dist: prometheus-client>=0.17.0; extra == "server"
+Requires-Dist: asgi-correlation-id>=4.2.0; extra == "server"
+Requires-Dist: psutil; extra == "server"
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == "server"
+Requires-Dist: aiosqlite; extra == "server"
+Dynamic: license-file
+
+# SketchLog
+
+![Status](https://img.shields.io/badge/status-beta-orange)
+![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+**Bounded-memory streaming metrics with explicit approximation guarantees.**
+
+SketchLog allows you to ingest high-throughput event streams and extract accurate
+percentiles and cardinalities in constant memory. It combines **DDSketch** for latencies,
+**HyperLogLog** for unique items, and **Count-Min Sketch** for event frequencies.
+
+Instead of storing arrays of events or exporting raw telemetry, SketchLog compresses
+the statistical shape of your data in real time, making it ideal for continuous
+monitoring, edge devices, and memory-constrained environments.
+
+---
+
+## 📚 Documentation
+
+The full documentation is available at [SketchLog Documentation Site](https://sbalavignesh123.github.io/sketchlog/) (or via `/docs` in the repository).
+It includes:
+- **Architecture**: Details on distributed merges, drift detection, and memory footprint.
+- **Benchmarks**: Memory footprint scaling and CPU throughput limits.
+- **Guarantees**: Published error bounds, implementation preconditions, and
+  checked capacity limits.
+- **Integrations**: How to integrate with Prometheus, FastAPI, and OpenTelemetry.
+- **API Reference**: Core classes, methods, and persistence operations.
+- **Contributing**: Guidelines for contributing to SketchLog.
+
+### Local Documentation Build
+To build and preview the documentation locally:
+```bash
+pip install ".[docs]"
+mkdocs serve
+```
+
+---
+
+## Installation
+
+### 1. The Core Library (Python)
+If you just want to use the high-performance sketching data structures directly in Python:
+```bash
+pip install sketchlog
+```
+
+### 2. The Standalone Server
+To run SketchLog as an independent network service (like Redis or Prometheus):
+```bash
+pip install "sketchlog[server]"
+uvicorn sketchlog.server:app --port 8080
+```
+
+---
+
+## Quickstart
+
+### 🐍 Python (Embedded Library)
+```python
+from sketchlog import StreamLog
+
+log = StreamLog()
+log.add_latency(42.5)
+log.add_batch([15.0, 88.2, 42.1])
+log.add_unique("user_12345")
+log.add_event("cache_miss", count=5)
+
+print(f"p99 Latency:  {log.p99():.2f}ms")
+```
+
+### 🟨 TypeScript / Node.js SDK
+Connect to the standalone server via HTTP:
+```bash
+npm install @sketchlog/client
+```
+```typescript
+import { SketchLogClient } from '@sketchlog/client';
+
+const client = new SketchLogClient({ endpoint: 'http://localhost:8080' });
+
+// Validated HTTP ingestion with bounded retries
+await client.ingestEvents('production_api', {
+  latencies: [42.5, 15.0, 88.2, 42.1],
+  uniques: ["user_12345"],
+  events: { "cache_miss": 5 }
+});
+```
+
+### 🐹 Go SDK
+```bash
+go get github.com/SBALAVIGNESH123/sketchlog/clients/go@v1.2.1
+```
+```go
+import "github.com/SBALAVIGNESH123/sketchlog/clients/go"
+
+client := sketchlog.NewClient(sketchlog.ClientOptions{
+    Endpoint: "http://localhost:8080",
+})
+
+batch := sketchlog.EventBatch{
+    Latencies: []float64{42.5, 15.0, 88.2, 42.1},
+    Uniques:   []string{"user_12345"},
+    Events:    map[string]int64{"cache_miss": 5},
+}
+
+err := client.IngestEvents(ctx, "production_api", batch)
+```
+
+## Distributed Clustering (Beta)
+
+SketchLog supports multi-node clustering without requiring external coordination services like Redis.
+
+You can run a cluster using the following environment variables:
+```bash
+SKETCHLOG_NODE_ID="node-1"
+SKETCHLOG_PEERS="http://node2:8000,http://node3:8000"
+SKETCHLOG_CLUSTER_SECRET="your-secret-token"
+uvicorn sketchlog.server:app --port 8000
+```
+
+> **Performance trade-off**: Mesh mode currently uses deterministic Python
+> sketches to guarantee identical merge state across heterogeneous nodes. Measure
+> this mode with your own traffic before capacity planning.
+
+## Community
+
+Join us in Slack! [Join SketchLog Slack](https://join.slack.com/t/sketchlog/shared_invite/zt-41kc03dnl-tiyHm4Gr2CbaJWuGHxdbiQ)
+
+---
+
+## What this is not
+
+SketchLog is a streaming metrics compression layer. It is deliberately not:
+
+- **Not a tracing system.** No request paths, no correlation IDs, no causal chains.
+- **Not a time-series database.** No historical drill-down, no label indexing.
+- **Not an observability platform.** No raw log storage, no ad-hoc queries.
+- **Not exact.** All results are probabilistic with bounded error. If you need exact percentiles, use numpy.
+
+---
+
+MIT License

sketchlog-1.2.1/README.md

@@ -0,0 +1,143 @@
+# SketchLog
+
+![Status](https://img.shields.io/badge/status-beta-orange)
+![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+**Bounded-memory streaming metrics with explicit approximation guarantees.**
+
+SketchLog allows you to ingest high-throughput event streams and extract accurate
+percentiles and cardinalities in constant memory. It combines **DDSketch** for latencies,
+**HyperLogLog** for unique items, and **Count-Min Sketch** for event frequencies.
+
+Instead of storing arrays of events or exporting raw telemetry, SketchLog compresses
+the statistical shape of your data in real time, making it ideal for continuous
+monitoring, edge devices, and memory-constrained environments.
+
+---
+
+## 📚 Documentation
+
+The full documentation is available at [SketchLog Documentation Site](https://sbalavignesh123.github.io/sketchlog/) (or via `/docs` in the repository).
+It includes:
+- **Architecture**: Details on distributed merges, drift detection, and memory footprint.
+- **Benchmarks**: Memory footprint scaling and CPU throughput limits.
+- **Guarantees**: Published error bounds, implementation preconditions, and
+  checked capacity limits.
+- **Integrations**: How to integrate with Prometheus, FastAPI, and OpenTelemetry.
+- **API Reference**: Core classes, methods, and persistence operations.
+- **Contributing**: Guidelines for contributing to SketchLog.
+
+### Local Documentation Build
+To build and preview the documentation locally:
+```bash
+pip install ".[docs]"
+mkdocs serve
+```
+
+---
+
+## Installation
+
+### 1. The Core Library (Python)
+If you just want to use the high-performance sketching data structures directly in Python:
+```bash
+pip install sketchlog
+```
+
+### 2. The Standalone Server
+To run SketchLog as an independent network service (like Redis or Prometheus):
+```bash
+pip install "sketchlog[server]"
+uvicorn sketchlog.server:app --port 8080
+```
+
+---
+
+## Quickstart
+
+### 🐍 Python (Embedded Library)
+```python
+from sketchlog import StreamLog
+
+log = StreamLog()
+log.add_latency(42.5)
+log.add_batch([15.0, 88.2, 42.1])
+log.add_unique("user_12345")
+log.add_event("cache_miss", count=5)
+
+print(f"p99 Latency:  {log.p99():.2f}ms")
+```
+
+### 🟨 TypeScript / Node.js SDK
+Connect to the standalone server via HTTP:
+```bash
+npm install @sketchlog/client
+```
+```typescript
+import { SketchLogClient } from '@sketchlog/client';
+
+const client = new SketchLogClient({ endpoint: 'http://localhost:8080' });
+
+// Validated HTTP ingestion with bounded retries
+await client.ingestEvents('production_api', {
+  latencies: [42.5, 15.0, 88.2, 42.1],
+  uniques: ["user_12345"],
+  events: { "cache_miss": 5 }
+});
+```
+
+### 🐹 Go SDK
+```bash
+go get github.com/SBALAVIGNESH123/sketchlog/clients/go@v1.2.1
+```
+```go
+import "github.com/SBALAVIGNESH123/sketchlog/clients/go"
+
+client := sketchlog.NewClient(sketchlog.ClientOptions{
+    Endpoint: "http://localhost:8080",
+})
+
+batch := sketchlog.EventBatch{
+    Latencies: []float64{42.5, 15.0, 88.2, 42.1},
+    Uniques:   []string{"user_12345"},
+    Events:    map[string]int64{"cache_miss": 5},
+}
+
+err := client.IngestEvents(ctx, "production_api", batch)
+```
+
+## Distributed Clustering (Beta)
+
+SketchLog supports multi-node clustering without requiring external coordination services like Redis.
+
+You can run a cluster using the following environment variables:
+```bash
+SKETCHLOG_NODE_ID="node-1"
+SKETCHLOG_PEERS="http://node2:8000,http://node3:8000"
+SKETCHLOG_CLUSTER_SECRET="your-secret-token"
+uvicorn sketchlog.server:app --port 8000
+```
+
+> **Performance trade-off**: Mesh mode currently uses deterministic Python
+> sketches to guarantee identical merge state across heterogeneous nodes. Measure
+> this mode with your own traffic before capacity planning.
+
+## Community
+
+Join us in Slack! [Join SketchLog Slack](https://join.slack.com/t/sketchlog/shared_invite/zt-41kc03dnl-tiyHm4Gr2CbaJWuGHxdbiQ)
+
+---
+
+## What this is not
+
+SketchLog is a streaming metrics compression layer. It is deliberately not:
+
+- **Not a tracing system.** No request paths, no correlation IDs, no causal chains.
+- **Not a time-series database.** No historical drill-down, no label indexing.
+- **Not an observability platform.** No raw log storage, no ad-hoc queries.
+- **Not exact.** All results are probabilistic with bounded error. If you need exact percentiles, use numpy.
+
+---
+
+MIT License

sketchlog-1.2.1/SECURITY.md

@@ -0,0 +1,38 @@
+# Security Policy
+
+## Supported Versions
+
+We provide security updates for the current major version. Users are strongly encouraged to stay on the latest available minor version.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x.x   | :white_check_mark: |
+| < 1.0.0 | :x:                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please do **NOT** open a public issue.
+
+Please report all security vulnerabilities via the **[GitHub Security Advisories](https://github.com/SBALAVIGNESH123/sketchlog/security/advisories/new)** tab in this repository. If you do not have access to this feature, please email the project owner directly.
+
+### What to Include
+*   A clear description of the vulnerability.
+*   The versions of Sketchlog affected.
+*   A minimal reproduction or Proof of Concept (PoC).
+*   Any potential impact or exploit scenarios.
+
+### Response Targets
+*   **Initial Acknowledgement**: Within 48 hours.
+*   **Vulnerability Confirmation & Triage**: Within 5 days.
+*   **Patch Development**: Varies by complexity, but we aim for 14 days.
+
+## SLA & Release Blocking Policy
+
+To protect our users and software supply chain, Sketchlog enforces the following remediation Service Level Agreement (SLA) for confirmed vulnerabilities:
+
+*   **Critical / High Severity**: Must be patched within 30 days. No new feature releases or non-security patches will be published until the vulnerability is resolved.
+*   **Medium / Low Severity**: Will be patched in the next scheduled minor release.
+
+## Coordinated Disclosure
+
+We believe in responsible, coordinated disclosure. If you report a vulnerability, we ask that you keep the details confidential until we have published a fix and issued an official security advisory. In return, we commit to transparent communication and will credit you (with your permission) in the release notes and advisory.

sketchlog-1.2.1/build_wasm.ps1

@@ -0,0 +1,27 @@
+# PowerShell script to build WASM using Docker
+
+Write-Host "Compiling SketchLog to WASM..."
+
+if (!(Test-Path "wasm/dist")) {
+    New-Item -ItemType Directory -Path "wasm/dist" | Out-Null
+}
+
+$CurrentDir = (Get-Item .).FullName
+$EmsdkImage = "emscripten/emsdk:5.0.4@sha256:ef91f658e0104636cf40a702c99169273969cf04d939f4f08e5d0223965d5788"
+
+docker run --rm -v "${CurrentDir}:/src" -w /src $EmsdkImage emcc `
+    -O3 `
+    --bind `
+    -Iinclude `
+    wasm/bindings.cpp `
+    -s MODULARIZE=1 `
+    -s EXPORT_NAME="SketchLogModule" `
+    -s ALLOW_MEMORY_GROWTH=1 `
+    -o wasm/dist/sketchlog.js
+
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "Docker compilation failed with exit code $LASTEXITCODE"
+    exit $LASTEXITCODE
+}
+
+Write-Host "Successfully built wasm/dist/sketchlog.js and wasm/dist/sketchlog.wasm" -ForegroundColor Green

sketchlog-1.2.1/build_wasm.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "Compiling SketchLog to WASM..."
+
+mkdir -p wasm/dist
+
+readonly EMSDK_IMAGE="emscripten/emsdk:5.0.4@sha256:ef91f658e0104636cf40a702c99169273969cf04d939f4f08e5d0223965d5788"
+
+docker run --rm -v "$(pwd):/src" -w /src -u "$(id -u):$(id -g)" \
+    "${EMSDK_IMAGE}" emcc \
+    -O3 \
+    --bind \
+    -Iinclude \
+    wasm/bindings.cpp \
+    -s MODULARIZE=1 \
+    -s EXPORT_NAME="SketchLogModule" \
+    -s ALLOW_MEMORY_GROWTH=1 \
+    -o wasm/dist/sketchlog.js
+
+echo "Successfully built wasm/dist/sketchlog.js and wasm/dist/sketchlog.wasm"