๐Ÿ›ก๏ธ Production-Grade Observability Blueprints

Cloud-Native Observability Platform

Unified LGTM (Loki, Grafana, Tempo, Prometheus/Thanos) and OpenTelemetry architecture with automated cross-layer AST verification, Google SRE Multi-Burn-Rate alerting, and GitOps blueprints.

โ— Release: v0.2.3
โœ“ CI: Passing
โฌก Terraform: 1.5+
โšก OTel Collector: v0.98+
bash ยท quickstart
$git clone https://github.com/umesh0492/cloud-native-observability.git
$cd cloud-native-observability
$docker compose up -d
Grafana UI (admin/admin) localhost:3000
Prometheus Web localhost:9090
Tempo Tracing localhost:3200
OTel OTLP Endpoints 4317 (gRPC) / 4318 (HTTP)

Telemetry Flow & Architecture

Unified telemetry ingestion: distributed traces, log streams, and system metrics are normalized by OpenTelemetry Collectors and routed to dedicated storage backends.

Microservices / Workloads Go, Python, Java, Node.js
โ†’
OTel Collector OTLP gRPC (4317) / HTTP (4318)
โ†’
Processors & Connectors Memory Limiter, Batch, Spanmetrics
โ†’
LGTM Storage Backends Prometheus/Thanos, Loki, Tempo
โ†’
Grafana Unified UI Single Pane of Glass

LGTM Platform Matrix

Engineered for production resilience across local Docker Compose sandboxes, Kubernetes Helm/ArgoCD clusters, and AWS EKS via Terraform.

Loki
Logs

Horizontally scalable, multi-tenant log aggregation system optimized for cost efficiency through index-free metadata labeling.

  • Structured metadata & LogQL streaming queries
  • Zero-indexing design avoids high-cardinality crashes
  • Direct trace-to-logs linking via `trace_id` correlation
Grafana
Visualization

Production dashboard visualization engine with pre-provisioned data sources and single-pane-of-glass operational telemetry.

  • Pre-built Platform Overview & Microservice APM dashboards
  • Automatic drill-down from metrics to Tempo trace spans
  • AST-verified alert rule queries & unified alert panel
Tempo
Distributed Tracing

High-scale distributed tracing backend designed for massive ingestion throughput with zero-dependency object storage persistence.

  • Native OTLP receiver integration
  • Spanmetrics connector derives latency histograms from spans
  • Service graph connector calculates request dependencies
Prometheus / Thanos
Metrics & SLOs

High-reliability metric TSDB with Thanos sidecar/store/querier integration for long-term historical retention and multi-cluster deduplication.

  • Precomputed recording rules for rolling 5m/30m/1h/6h/3d error rates
  • Google SRE Multi-Burn-Rate alerting engine
  • 100% unit-tested alert definitions via Promtool
OpenTelemetry Collector
Telemetry Gateway

Vendor-agnostic telemetry proxy providing memory-bounded pipeline buffering, attribute redaction, and multi-destination dispatching.

  • Memory limiter processor prevents container OOMKills
  • Batch processor buffers high-throughput trace and metric events
  • Route path normalization eliminates TSDB cardinality explosion

Google SRE Multi-Window Burn-Rate Alerting

Mathematical framework for high-precision, low-noise error budget consumption alerting adhering to Chapter 5 of the Google Site Reliability Workbook.

Mathematical Foundation

Given an availability target of 99.9% (SLO), the allowable unreliability is the Error Budget:

Error Budget = 1 - SLO = 1 - 0.999 = 0.001 (0.1% of total requests)

A Burn Rate of 1.0x exhausts exactly 100% of the budget over 30 days (720 hours). Faster consumption triggers multi-window paging:

Burn Rate = Observed Error Rate / Allowed Error Rate (0.001)
Alert Name Severity Tier Short Window Long Window Burn Rate Budget Consumed Routing Target
ServiceErrorBudgetBurnRateHigh1h CRITICAL PAGER 5 minutes 1 hour 14.4x 2% in 1 hour PagerDuty (Immediate Page)
ServiceErrorBudgetBurnRateHigh6h CRITICAL PAGER 30 minutes 6 hours 6.0x 5% in 6 hours PagerDuty (Immediate Page)
ServiceErrorBudgetBurnRateSlow3d WARNING TICKET 6 hours 3 days 1.0x 10% in 3 days Slack / Jira Backlog

Interactive SRE Burn-Rate Simulator

Adjust the parameters below to compute the instantaneous error budget burn rate and assess which alert tier triggers:

Calculated Burn Rate
14.4x
1h Budget Consumption
2.0% / hr
Alertmanager Evaluation
FIRING (Critical Pager)

Canonical Availability SLI AST Equivalence

Single-sourced mathematical logic in deploy/slo/canonical_sli.promql is statically parsed and AST-verified across all deployment blueprints to eliminate metric drift.

Canonical AST Formula

(sum(rate(http_requests_total{status=~"5.."}[{{WINDOW}}])) or vector(0)) / (sum(rate(http_requests_total[{{WINDOW}}])) > 0) or vector(0)

Security & Cardinality Guardrail: Excludes 4xx client errors (`status=~"5.."` server-only) to protect against false pages triggered by bad clients, unauthorized scans, or user typos.

Observability Layer Target Configuration File Rule / Metric Target Window AST Verification Status
Layer 1: Local Sandbox deploy/docker-compose/prometheus/alerts.yml HighErrorRate 5m Verified Equivalent โœ…
Layer 2: Production GitOps deploy/kubernetes/alerts/slo-alerts.yaml job:http_requests:error_rate_5m 5m Verified Equivalent โœ…
Layer 2: Production GitOps deploy/kubernetes/alerts/slo-alerts.yaml job:http_requests:error_rate_30m 30m Verified Equivalent โœ…
Layer 2: Production GitOps deploy/kubernetes/alerts/slo-alerts.yaml job:http_requests:error_rate_1h 1h Verified Equivalent โœ…
Layer 2: Production GitOps deploy/kubernetes/alerts/slo-alerts.yaml job:http_requests:error_rate_6h 6h Verified Equivalent โœ…
Layer 2: Production GitOps deploy/kubernetes/alerts/slo-alerts.yaml job:http_requests:error_rate_3d 3d Verified Equivalent โœ…
Layer 3: Infrastructure as Code deploy/terraform/modules/grafana_provisioning/alerts.tf HighErrorRateP1 5m Verified Equivalent โœ…

Telemetry Configurations & Rules

Browse verified PromQL alert rules, OpenTelemetry pipeline definitions, and Alertmanager routing hierarchies.

# Canonical Service Level Indicator (SLI) - Availability Error Rate
# deploy/slo/canonical_sli.promql
(
  sum(rate(http_requests_total{status=~"5.."}[{{WINDOW}}]))
  or vector(0)
)
/
(
  sum(rate(http_requests_total[{{WINDOW}}])) > 0
)
or vector(0)
# Google SRE Multiwindow Burn-Rate Alert (14.4x consumption)
# deploy/kubernetes/alerts/slo-alerts.yaml
- alert: ServiceErrorBudgetBurnRateHigh1h
  expr: |
    (
      job:http_requests:error_rate_1h{job="demo-app"} > (1 - 0.999) * 14.4
    )
    and
    (
      job:http_requests:error_rate_5m{job="demo-app"} > (1 - 0.999) * 14.4
    )
  for: 2m
  labels:
    severity: critical
    tier: p1-pager
  annotations:
    summary: "High error budget burn rate (14.4x) on {{ $labels.service }}"
    description: "Service {{ $labels.service }} is consuming 2% of its monthly error budget in 1 hour."
    runbook_url: "https://github.com/umesh0492/cloud-native-observability/blob/main/docs/RUNBOOKS.md#serviceerrorbudgetburnratehigh1h"
# OpenTelemetry Collector Pipeline Configuration
# deploy/docker-compose/otel-collector/otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  memory_limiter:
    check_interval: 1s
    limit_percentage: 75
    spike_limit_percentage: 20

  batch:
    send_batch_size: 8192
    timeout: 500ms

connectors:
  spanmetrics:
    histogram:
      explicit:
        buckets: [2ms, 5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 2.5s, 5s]
    dimensions:
      - name: http.status_code
      - name: http.method
      - name: http.route

exporters:
  prometheus:
    endpoint: "0.0.0.0:8889"
  otlp/tempo:
    endpoint: "tempo:4317"
    tls:
      insecure: true
  otlphttp/loki:
    endpoint: "http://loki:3100/otlp"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlp/tempo, spanmetrics]
    metrics:
      receivers: [otlp, spanmetrics]
      processors: [memory_limiter, batch]
      exporters: [prometheus]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp/loki]
# Alertmanager Multi-Tier Routing Configuration
# deploy/kubernetes/alerts/alertmanager.yaml
global:
  resolve_timeout: 5m

route:
  group_by: ['alertname', 'namespace', 'service']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h
  receiver: 'slack-notifications'
  routes:
    # Critical Tier -> PagerDuty Immediate Page
    - match:
        severity: critical
      receiver: 'pagerduty-critical'
      continue: true

    # Warning Tier -> Slack Monitoring Channel
    - match:
        severity: warning
      receiver: 'slack-notifications'

inhibit_rules:
  # Inhibit warning alerts if the entire service is down
  - source_match:
      alertname: 'ServiceDown'
    target_match_re:
      alertname: 'HighErrorRate|HighLatencyP99'
    equal: ['service', 'namespace']

Architecture & Operations Library

Comprehensive operational documentation, incident runbooks, and cloud infrastructure guides.

Incident Runbooks
Actionable SOPs for on-call engineers covering Multi-Burn-Rate breaches, pod crash looping, worker pool exhaustion, and circuit breaker trip events.
Read docs/RUNBOOKS.md โ†’
SLO & Error Budget Design
Theoretical derivations, rolling multi-window alerting mathematics, and the canonical availability SLI specification.
Read docs/SLO_DESIGN.md โ†’
Clustered Observability
Production topologies for multi-tenant, high-volume metrics, logs, and distributed trace architectures at enterprise scale.
Read docs/CLUSTERED_OBSERVABILITY.md โ†’
Terraform IaC Guide
Automated provisioning workflows for AWS EKS clusters, Helm monitoring releases, and Grafana alert rule synchronization.
Read docs/TERRAFORM_GUIDE.md โ†’
Integration Guide
Step-by-step instrumentations for Go, Python, and Java services exporting OTLP traces and Prometheus golden signals.
Read docs/INTEGRATION_GUIDE.md โ†’
Sampling Strategies
Head-based and tail-based distributed tracing sampling algorithms to preserve critical error spans while containing storage costs.
Read docs/SAMPLING_STRATEGIES.md โ†’