GressTrace Documentation Portal

Welcome to the official developer documentation for GressTrace — the Sentry-inspired root cause attribution platform for Kubernetes cloud network costs.

1. Quickstart Guide (60 Seconds)

Deploy the complete backend stack (PostgreSQL 16, Redis 7, Celery Worker, Beat, Django REST API, and NGINX UI) using Docker Compose:

quickstart.sh

# 1. Clone the open source repository
git clone https://github.com/akshatjaiin/nasLogs.git
cd nasLogs

# 2. Boot the stack in background
docker compose up -d

# 3. Generate 7 days of historical cost telemetry & sample incidents
docker compose exec web python manage.py seed_demo

# 4. Open GressTrace UI in your browser
open http://localhost:3000

2. System Architecture & Flow

GressTrace functions completely out-of-band relative to your main application execution path. Network metrics are collected passively via eBPF flow agents or OpenCost scraper tasks, ingested over an authenticated DSN HTTP endpoint, and correlated against Kubernetes audit logs.

architecture_pipeline.txt

[Pod Egress Metrics] ──> [DSN Collector /api/collector/v1/ingest/]
                             │
                             ▼
                 [Statistical Z-Score Engine]
                             │
                             ▼
              [±30 min K8s Audit Log Correlator]
                             │
                             ▼
                  [Blame Trail & Alerts]

3. Docker Compose Self-Host Setup

Our hardened docker-compose.yml includes database healthcheck dependencies to guarantee PostgreSQL is fully initialized before Django migrations execute:

docker-compose.yml

services:
  db:
    image: postgres:16-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
  web:
    depends_on:
      db: { condition: service_healthy }

4. Kubernetes Helm Deployment

Deploy GressTrace into your Kubernetes cluster in under 1 minute using our official Helm repository:

helm_install.sh

helm repo add gresstrace https://charts.gresstrace.dev
helm repo update
helm install gresstrace gresstrace/gresstrace --namespace gresstrace-system --create-namespace

5. Python Client SDK Reference

Install and initialize the Python telemetry SDK in your workload containers:

sdk_example.py

from nas_logs import NASLogsClient

client = NASLogsClient(
    dsn="http://key_live_7a3b1c@localhost:8000/api/collector/v1/ingest/1",
    flush_interval=60.0,
    max_buffer_size=10000
)

client.capture({
    "namespace": "ecommerce",
    "controller_name": "cart-service",
    "network_cost_total": 12.50
})