nthlayer 0.1.0a1

NthLayer - The Missing Layer of Reliability

Early Access - NthLayer is in active development. We're looking for early adopters to try it and share feedback! Join the discussion or report issues.

NthLayer

The Missing Layer of Reliability
One YAML file. Complete reliability stack. Zero toil.
Auto-generate dashboards, SLOs, alerts, runbooks, and deployment gates from a single service definition.

Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. 🌐 Live Demo
2. About The Project
   • The Problem
   • The Solution
   • Built With
3. Key Features
4. Getting Started
   • Prerequisites
   • Installation
5. Usage
6. Documentation
7. Roadmap
8. Contributing
9. License
10. Acknowledgments

---

🌐 Live Demo

See what NthLayer generates — real dashboards, real metrics, real configs:

What's in the demo:

• Live Grafana Dashboards - 6 auto-generated dashboards with real metrics from our demo app
• Generated Configs - Real dashboard JSON, SLO definitions, alert rules, and recording rules
• Demo Site - Overview of NthLayer capabilities with links to live examples

---

About The Project

NthLayer eliminates operational toil by auto-generating SLOs, alerts, dashboards, and deployment gates from simple service definitions.

Define once. Generate everywhere. Zero toil.

(back to top)

The Problem

Every new service requires 20+ hours of manual operational setup:

• 6 hours: Define SLOs and calculate error budgets
• 4 hours: Research and configure alert rules for dependencies (PostgreSQL, Redis, Kafka, etc.)
• 5 hours: Build Grafana dashboards with technology-specific panels
• 5 hours: Set up deployment gates, runbooks, and PagerDuty escalation

Cost: 20 hours × 200 services = 4,000 hours of annual toil

The Solution

Write one YAML file. NthLayer generates everything automatically with a unified workflow:

# 1. Initialize from template
$ nthlayer init payment-api --team payments --template critical-api

# 2. Preview what will be generated (like terraform plan)
$ nthlayer plan payment-api.yaml
✅ SLOs (3)
✅ Alerts (28) - PostgreSQL, Redis, Kubernetes
✅ Dashboard (1) - 12 panels
✅ Recording Rules (21) - 10x faster dashboards
✅ PagerDuty Service (1)

# 3. Generate everything at once (like terraform apply)
$ nthlayer apply payment-api.yaml
✅ [1/5] SLOs          → 3 created
✅ [2/5] Alerts        → 28 created
✅ [3/5] Dashboard     → 1 created
✅ [4/5] Recording     → 21 created
✅ [5/5] PagerDuty     → 1 created

Successfully applied 54 resources in 1.2s

# 4. Check deployment readiness
$ nthlayer check-deploy payment-api.yaml
✅ Deployment approved (15% error budget consumed)

# Or use environment-specific configs
$ nthlayer apply payment-api.yaml --env prod

Time saved: 20 hours → 5 minutes ⚡
Commands: 7 → 2 (like Terraform!) 🚀

(back to top)

Built With

(back to top)

Key Features

Unified Workflow (NEW!)

• ✅ nthlayer plan - Preview all resources (like terraform plan)
• ✅ nthlayer apply - Generate everything at once (like terraform apply)
• ✅ Auto-Detection - Automatically detects what resources to generate
• ✅ One Command - Replace 5-7 commands with a single unified workflow
• ✅ Declarative - Define once, get everything (SLOs, alerts, dashboards, rules)

Core Capabilities

• ✅ 5 Built-in Templates - critical-api, standard-api, low-api, background-job, pipeline
• ✅ SLO Generation - Generates Sloth specifications from service definitions
• ✅ Auto-Generated Alerts - 400+ battle-tested rules from awesome-prometheus-alerts
• ✅ Multi-Environment Support - Dev/staging/prod configs with --env flag
• ✅ PagerDuty Integration - Auto-creates services with escalation policies
• ✅ Prometheus Integration - Real-time error budget tracking
• ✅ Deployment Gates - Error budget-based deployment validation
• ✅ Template Variables - Portable queries with ${service}, ${team}, etc.

Observability Suite

• ✅ Hybrid Dashboard Model - Intent-based templates + live metric discovery for zero "No Data" panels
• ✅ Dashboard Generation - Auto-generate Grafana dashboards (12-28 panels per service)
• ✅ Technology Templates - 40+ production-grade panels for PostgreSQL, Redis, Elasticsearch, MongoDB, HTTP/API
• ✅ 118 Auto-Generated Alerts - Production-ready Prometheus alerts with smart routing
• ✅ Recording Rules - 20+ pre-computed metrics for 10x faster dashboards
• ✅ 4 Deployment Methods - Kubernetes, Mimir/Cortex, GitOps, or traditional Prometheus

(back to top)

Getting Started

Get NthLayer running locally in 5 minutes. No external accounts required for development.

Prerequisites

You only need:

• Docker - For PostgreSQL and Redis
• Python 3.9+ - For the NthLayer CLI
• Make - For convenient shortcuts (optional)

Installation

Option 1: pip install (recommended)

pip install nthlayer

Option 2: From source (for development)

1. Clone the repo

   git clone https://github.com/rsionnach/nthlayer.git
   cd nthlayer
   

2. Run setup (installs dependencies, starts services, runs migrations)

   make setup
   

3. Verify installation

   make test
   # All 84 tests should pass ✅
   

4. Try the demo

   make demo-reconcile
   # Shows step-by-step what NthLayer does
   

That's it! You're ready to use NthLayer.

(back to top)

Usage

Unified Workflow (Recommended)

Preview what will be generated:

nthlayer plan payment-api.yaml

# Output:
# ✅ SLOs (3)
# ✅ Alerts (28)
# ✅ Dashboard (1)
# ✅ Recording Rules (21)
# ✅ PagerDuty Service (1)

Generate all resources at once:

nthlayer apply payment-api.yaml

# Output:
# ✅ [1/5] SLOs          → 3 created
# ✅ [2/5] Alerts        → 28 created
# ✅ [3/5] Dashboard     → 1 created
# ✅ [4/5] Recording     → 21 created
# ✅ [5/5] PagerDuty     → 1 created

With environment-specific configs:

# Production: Stricter thresholds, all alerts
nthlayer apply payment-api.yaml --env prod

# Development: Relaxed thresholds, critical alerts only
nthlayer apply payment-api.yaml --env dev

Advanced options:

# Skip specific resources
nthlayer apply payment-api.yaml --skip pagerduty

# Only generate specific resources
nthlayer apply payment-api.yaml --only slos dashboard

# Verbose output
nthlayer apply payment-api.yaml --verbose

# Dry-run (preview without writing files)
nthlayer apply payment-api.yaml --dry-run

Individual Commands (Advanced)

For granular control, individual commands are still available:

# Generate specific resource types
nthlayer generate-slo payment-api.yaml
nthlayer generate-alerts payment-api.yaml
nthlayer generate-dashboard payment-api.yaml --full
nthlayer generate-recording-rules payment-api.yaml

# Check deployment readiness
nthlayer check-deploy payment-api.yaml

Development Workflow

# Start services
make dev-up

# Run tests
make test

# Start mock API server
make mock-server

# Demo workflows
make demo-reconcile

# Stop services
make dev-down

For more examples and detailed usage, please refer to the Getting Started Guide and Documentation

(back to top)

Documentation

User Guides

• GETTING_STARTED.md - 10-minute quick start guide
• docs/OBSERVABILITY.md - Dashboard & recording rules guide
• docs/ENVIRONMENTS.md - Multi-environment configuration
• docs/ALERTS.md - Auto-generated alerts documentation
• docs/TEMPLATES.md - Service template reference
• docs/CUSTOM_TEMPLATES.md - Custom template guide

Developer Docs

• docs/DEVELOPMENT.md - Complete developer guide
• docs/DIAGRAMS.md - Visual architecture diagrams
• Makefile - Run make help to see all commands
• nthlayer_architecture.md - System architecture

Reference

• CHANGELOG.md - Feature changelog
• ATTRIBUTION.md - Third-party attributions
• LICENSING_COMPLIANCE.md - License compliance
• archive/dev-notes/ - Development history

(back to top)

Roadmap

Recently Completed ✅

• Multi-environment support (dev/staging/prod)
• Auto-generated alerts (400+ rules)
• Dashboard generation (12-28 panels)
• Technology templates (PostgreSQL, Redis, K8s, HTTP/API)
• Recording rules (20+ metrics)
• Template variables and portability

Coming Soon

• MySQL, MongoDB, Elasticsearch templates
• Custom panel selection for dashboards
• Multi-service aggregate dashboards
• Datadog integration
• Slack notifications

See the open issues for a full list of proposed features and known issues.

(back to top)

Contributing

Contributions are what make the open source community amazing. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

1. Read GETTING_STARTED.md to understand the codebase
2. Fork the Project
3. Create your Feature Branch (git checkout -b feature/AmazingFeature)
4. Write tests with respx mocks
5. Run tests and linting (make test lint format)
6. Commit your Changes (git commit -m 'Add some AmazingFeature')
7. Push to the Branch (git push origin feature/AmazingFeature)
8. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Acknowledgments

NthLayer builds on the shoulders of giants:

Core Dependencies

• grafana-foundation-sdk - Grafana dashboard generation SDK (Apache 2.0). Powers our Hybrid Model for intent-based dashboard generation with type-safe panel building.
• awesome-prometheus-alerts - 580+ battle-tested alert rules (CC BY 4.0). Our alert templates for PostgreSQL, Redis, Elasticsearch, and 40+ technologies.

Architecture Inspiration

• Sloth - SLO specification format and burn rate calculations
• OpenSLO - SLO specification standard

Tooling

• Best-README-Template - This README structure
• Shields.io - Badges used in this README
• Slidev - Presentation framework for our decks

(back to top)

---

Quick Links

Getting Started:

# Setup and test
make setup && make test

# Try the unified workflow
nthlayer plan examples/services/payment-api.yaml
nthlayer apply examples/services/payment-api.yaml

Need Help?

• 📖 Quick Start Guide
• 💬 Open an Issue
• 🎯 View Roadmap

Happy coding! 🚀