Gözlemlenebilirlik CLI’ı

Sentinel Coming

Sentinel Coming; ajan tabanlı bir Python CLI’ı, salt-okunur bir gözlemlenebilirlik ağ geçidi ve gerçekçi bir çok servisli test platformu etrafında kurulmuş, portföy düzeyinde bir gözlemlenebilirlik ve altyapı otomasyonu projesidir. Operatörlerin metrik, log, trace, yapılandırma ve dağıtım durumunu tek bir terminal akışından daha güvenli biçimde incelemesi gereken yerel laboratuvarlar ve Kubernetes/COS tarzı ortamlar için tasarlanmıştır.

Ürünün çekirdeği `sentinel-cli`’dır: tek seferlik istemler çalıştırabilen, REPL başlatabilen, yapılandırmayı inceleyebilen, health check yapabilen, yerel gözlemlenebilirlik yığınları kurabilen ve ağ geçidi destekli bir telemetri katmanını sorgulayabilen bir Python komut satırı asistanı. Ağ geçidi; Prometheus, Loki ve Tempo erişimini tek bir salt-okunur HTTP API’si arkasında tutar, böylece CLI her arka uç URL’ini doğrudan bilmek zorunda kalmaz.

Problem ve hedefler

Modern gözlemlenebilirlik yığınları güçlüdür ama operasyonel olarak parçalıdır. Bir geliştirici ya da platform mühendisi çoğu zaman bir servisin sağlıklı olup olmadığını anlamak için Grafana, Prometheus, Loki, Tempo, shell komutları, Kubernetes araçları ve runbook’lar arasında gidip gelmek zorunda kalır.

Bu proje o iş akışına pratik bir yanıt arıyor:

Ajan destekli altyapı ve gözlemlenebilirlik çalışması için tek bir CLI yüzeyi sunmak.
Telemetri erişimini bir ağ geçidi servisi üzerinden varsayılan olarak salt-okunur tutmak.
Katmanlı bir yapılandırma modeliyle yerel ve bulut LLM sağlayıcılarını desteklemek.
Oturumlar, trajectory’ler, bellek çıkarımı ve kontrollü dokümantasyon güncellemeleriyle işe yarar hata ayıklama bağlamını korumak.
İş akışını; servisler, veritabanları, Redis Streams, yük üretimi, kaos profilleri, Kubernetes manifest’leri ve smoke script’leri olan gerçekçi bir hedef platforma karşı doğrulamak.

Temel özellikler

run, repl, config, doctor, obs, install ve version komutlarıyla ajan tabanlı CLI.
OpenAI uyumlu API’ler ve Anthropic için LLM sağlayıcı desteği; Ollama gibi yerel OpenAI uyumlu uç noktalar dâhil.
mcp ekstrası üzerinden isteğe bağlı MCP istemci entegrasyonu.
Varsayılanlardan, YAML dosyalarından, ortam değişkenlerinden ve CLI bayraklarından katmanlı yapılandırma.
Bash, dosya sistemi erişimi, onay modları, zaman aşımları, çıktı limitleri ve salt-okunur bash modu için araç yürütme kontrolleri.
Oturum kalıcılığı, trajectory kaydı, bağlam penceresi politikası ve isteğe bağlı tur sonu bellek işleme.
Prometheus metrikleri, Loki log sorguları ve Tempo trace arama/detay çağrıları için salt-okunur FastAPI gözlemlenebilirlik ağ geçidi.
Ağ geçidi destekli CLI gözlemlenebilirlik komutları: obs metric, obs logs ve obs traces.
Sentinel gözlemlenebilirlik yığını için Docker Compose kurulum varlıkları ve Kubernetes Helm chart varlıkları.
Gateway, orders, payments, inventory, worker servisleri; Postgres, Redis, OpenTelemetry Collector, Locust yük senaryoları, kaos profilleri ve Kubernetes manifest’leri içeren test platformu.
GitHub Actions, Ruff ve Pytest kullanan CLI paketi CI’ı.
Çok mimarili GHCR derlemeleri için ağ geçidi imaj iş akışı.

Mimari

User
  |
  v
sentinel-cli
  |-- LLM provider adapters
  |-- tool registry: bash, filesystem, MCP, observability tools
  |-- session, trajectory, hooks, memory, and config layers
  |
  v
observability-gateway
  |-- Prometheus: instant metric queries
  |-- Loki: query_range log retrieval
  |-- Tempo: trace search and trace detail retrieval
  |
  v
Target platform and observability backends

Depo ayrıca farklı ortamlar için dağıtım yolları içerir:

for-download/compose/ Prometheus, Loki, Tempo, Grafana ve Sentinel gateway imajını içeren bir Docker Compose gözlemlenebilirlik yığını barındırır.
charts/sentinel/ mevcut bir Kubernetes kümesine kube-prometheus-stack, Loki, Tempo, Grafana ve sentinel-gateway kuran bir Helm chart içerir.
test-platform/ Sentinel iş akışı için metrik, log ve trace üretmekte kullanılan gerçekçi bir hedef uygulama ağacı içerir.
skills/ ve cli/skills/ proje bilgisi ve uygulama referansı olarak kullanılan yapılandırılmış operasyonel ve ajan tabanlı rehber dosyalarını içerir.

Teknoloji yığını

CLI, ağ geçidi ve test servisleri için Python 3.11+.
HTTP servisleri için FastAPI ve Uvicorn.
Tipli yapılandırma ve istek/yanıt modelleri için Pydantic ve pydantic-settings.
Dış API ve arka uç çağrıları için HTTPX.
Yapılandırma dosyaları ve ortam yüklemesi için PyYAML ve python-dotenv.
CLI çıktısı ve ilerleme gösterimi için Rich.
Test ve lint iş akışları için Pytest ve Ruff.
Yerel gözlemlenebilirlik ve hedef platform çalıştırmaları için Docker Compose.
Küme dağıtım yolları için Helm ve Kubernetes manifest’leri.
Destekleyici laboratuvar platformunda Prometheus, Loki, Tempo, Grafana, OpenTelemetry Collector, Postgres, Redis ve Locust.

Depo yapısı

sentinel-coming/
|-- cli/                         # Sentinel CLI Python package
|-- observability-gateway/       # Read-only FastAPI gateway for telemetry backends
|-- test-platform/               # Multi-service target app, load, chaos, and smoke scripts
|-- charts/sentinel/             # Helm chart for Kubernetes observability stack
|-- for-download/                # Compose bundle and operational setup scripts
|-- scripts/                     # MicroK8s/COS helper scripts and repo automation
|-- skills/                      # COS/Juju/MicroK8s operational skill documents
|-- documantations/              # Project and phase documentation
|-- .github/workflows/           # CLI CI and gateway image workflows
`-- agentic/                     # External/reference agent projects, not the main product

Önemli not: agentic/ bağımsız referans projeleri içerir. Ana Sentinel uygulaması cli/, observability-gateway/, test-platform/, charts/, for-download/, scripts/, skills/ ve documantations/ içindedir.

Ana modüller

cli/

cli/ ana kullanıcıya dönük pakettir. Kaynak kodu cli/src/sentinel_cli/ altında yer alır.

Ana alanlar:

cli/app.py: argparse komut yüzeyi ve çalışma zamanı bağlantıları.
agent/: ajan döngüsü, bağlam sıkıştırma ve tur sonu işleme.
llm/: sağlayıcı fabrikası, Anthropic adaptörü, OpenAI uyumlu adaptör, streaming, yeniden denemeler ve paylaşılan tipler.
tools/: bash, dosya sistemi, MCP, onay, registry ve gözlemlenebilirlik araçları.
observability/: gateway ve Grafana bağlantı kontrolleri.
config/: Pydantic yapılandırma modelleri ve katmanlı yükleyici.
memory/: çıkarım, dreaming, magic docs, bellek yolu işleme ve redaksiyon farkındalıklı kalıcılık.
session/: oturum deposu ve trajectory kaydı.
installers/: Docker Compose, Kubernetes Helm ve COS keşif/kurulum arka uçları.
assets/: install komutunun kullandığı paketlenmiş Compose ve Helm chart varlıkları.

observability-gateway/

observability-gateway/ bağımsız bir FastAPI servisidir. Küçük ve salt-okunur bir API sunar; istekleri Prometheus, Loki ve Tempo’ya uyarlar.

Uç noktalar:

GET /health
GET /api/v1/status
POST /api/v1/metrics/query
POST /api/v1/logs/query_range
POST /api/v1/traces/search
GET /api/v1/traces/{trace_id}

Ağ geçidi, SENTINEL_OBSERVABILITY_GATEWAY_TOKEN yapılandırıldığında bearer-token koruması destekler. Arka uç hataları, sırları sızdırmayan yapılandırılmış bir model üzerinden döner.

test-platform/

test-platform/ gerçekçi gözlemlenebilirlik testleri için bir hedef uygulama sağlar:

gateway: genel API cephesi.
orders: ödemeleri ve envanteri koordine eder, Postgres’e yazar ve Redis Stream olayları yayar.
payments: Redis idempotency ile ödeme simülasyonu.
inventory: Redis cache-through davranışıyla stok okuma/rezervasyon.
worker: Redis Streams tüketici grubu işlemcisi.
load/: steady, diurnal, flash crowd ve gradual degradation dâhil Locust senaryoları.
chaos/profiles/: healthy, slow database, cache stampede, downstream outage, memory leak ve cascading profilleri.
k8s/: namespace, servisler, deployment/stateful kaynaklar, OpenTelemetry Collector yapılandırması ve network policy manifest’leri.

charts/sentinel/

Helm chart, mevcut bir Kubernetes kümesine Prometheus, Loki, Grafana, Tempo ve Sentinel ağ geçidini kurar. Chart, Prometheus Community ve Grafana Helm depolarındaki upstream bağımlılıkları kullanır ve servis adlarını CLI keşif koduyla hizalı tutar.

for-download/

Bu klasör dağıtım odaklı varlıkları içerir:

compose/docker-compose.yaml: yerel gözlemlenebilirlik yığını.
compose/.env.example: compose yığını için port ve ağ geçidi token varsayılanları.
prepare-env.sh: MicroK8s, MetalLB ve Juju hazırlık yardımcısı.
my-product-bundle.yaml: Prometheus, Loki, Alertmanager, Grafana, Traefik, Catalogue, Tempo ve OpenTelemetry Collector içeren COS Lite bundle’ı.
faz1-telemetry.sh ve faz4-5.sh: telemetri kurulumu ve dağıtım sonrası kontroller için operasyonel script’ler.

Kurulum

Depoyu klonlayın ve sanal ortam oluşturun:

cd sentinel-coming
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

CLI’ı yerel geliştirme için kurun:

cd cli
python -m pip install -e ".[dev]"
python -m sentinel_cli --help

CLI’ı isteğe bağlı MCP desteğiyle kurun:

cd cli
python -m pip install -e ".[dev,mcp]"
python -m sentinel_cli doctor --profile local

Gözlemlenebilirlik ağ geçidini yerelde kurun ve çalıştırın:

cd observability-gateway
python -m pip install -e ".[dev]"
sentinel-observability-gateway

Alternatif ağ geçidi başlatma:

cd observability-gateway
uvicorn observability_gateway.main:app --host 0.0.0.0 --port 8091

Yapılandırma

CLI, commit edilen şablonları yerel sırlardan ayrı tutar:

cli/config/sentinel.example.yaml: commit edilen YAML şablonu.
cli/.env.example: commit edilen ortam şablonu.
cli/config/sentinel.yaml: yerel çalışma zamanı yapılandırması, Git tarafından yok sayılır.
cli/.env: yerel sırlar ve geçersiz kılmalar, Git tarafından yok sayılır.

Yerel yapılandırma oluşturma:

cd cli
cp config/sentinel.example.yaml config/sentinel.yaml
cp .env.example .env

cli/.env.example içindeki yaygın CLI ortam değişkenleri:

SENTINEL_CONFIG
SENTINEL_PROFILE
SENTINEL_MODEL
SENTINEL_OPENAI_BASE_URL
SENTINEL_API_KEY
SENTINEL_LOCAL_BASE_URL
SENTINEL_LOCAL_MODEL
ANTHROPIC_API_KEY
SENTINEL_ANTHROPIC_MODEL
SENTINEL_HTTP_CONNECT_TIMEOUT_SEC
SENTINEL_HTTP_TIMEOUT_SEC
SENTINEL_CONTEXT_WINDOW_TOKENS
SENTINEL_LOG_LEVEL
SENTINEL_MAX_TURNS
SENTINEL_AUTO_APPROVE
SENTINEL_SESSION_DIR
SENTINEL_TRAJECTORY_DIR
SENTINEL_EXPERIMENTAL_MCP

Ağ geçidiyle ilgili CLI ayarları sentinel.yaml içindeki observability_gateway altında yapılandırılır:

observability_gateway:
  enabled: true
  base_url: http://127.0.0.1:8091
  timeout_sec: 10
  token_env: SENTINEL_OBSERVABILITY_GATEWAY_TOKEN

observability-gateway/README.md içinde belgelenen ağ geçidi servisi ortam değişkenleri:

SENTINEL_OBSERVABILITY_CONFIG_PATH
SENTINEL_OBSERVABILITY_GATEWAY_TOKEN
SENTINEL_OBSERVABILITY_PROMETHEUS__BASE_URL
SENTINEL_OBSERVABILITY_PROMETHEUS__TOKEN_ENV
SENTINEL_OBSERVABILITY_LOKI__BASE_URL
SENTINEL_OBSERVABILITY_TEMPO__BASE_URL
SENTINEL_OBSERVABILITY_HTTP__TIMEOUT_SEC
SENTINEL_OBSERVABILITY_HTTP__RETRY__MAX_ATTEMPTS

for-download/compose/.env.example içindeki compose paketi ayrıca Prometheus, Loki, Tempo, Grafana ve Sentinel ağ geçidi için portları tanımlar.

Kullanım

Tek seferlik bir ajan istemi çalıştırma:

cd cli
source .venv/bin/activate
python -m sentinel_cli run "Summarize the current observability gateway status"

Etkileşimli REPL başlatma:

cd cli
source .venv/bin/activate
python -m sentinel_cli repl

Etkin yapılandırmayı inceleme:

cd cli
python -m sentinel_cli config

Tanılama çalıştırma:

cd cli
python -m sentinel_cli doctor --profile local

Ağ geçidi üzerinden telemetri sorgulama:

cd cli
python -m sentinel_cli obs metric 'up'
python -m sentinel_cli obs logs --service gateway
python -m sentinel_cli obs traces --service orders

Compose kurulum akışını çalıştırma:

cd cli
python -m sentinel_cli install --mode compose

Kubernetes Helm kurulum akışını çalıştırma:

cd cli
python -m sentinel_cli install --mode k8s

COS kurulum arka ucu şu anda keşif/yapılandırma bağlantılarını içerir; preflight, install ve verify adımları kodda TODO olarak işaretlidir. Mevcut MicroK8s/Juju/COS operasyonel yolu için scripts/ ve for-download/ altındaki script’leri kullanın.

Yerel hedef platform

Test platformu Docker Compose ile başlatılabilir:

cd test-platform
docker compose up --build

test-platform/README.md yerel veritabanı ortam değişkenlerini ve health check’leri belgeler:

export ORDERS_DB_URL=postgresql+asyncpg://sentinel:sentinel@localhost:5432/orders_db
export PAYMENTS_DB_URL=postgresql+asyncpg://sentinel:sentinel@localhost:5432/payments_db
export INVENTORY_DB_URL=postgresql+asyncpg://sentinel:sentinel@localhost:5432/inventory_db
export PAYMENTS_REDIS_URL=redis://localhost:6379/1
python scripts/seed_db.py
curl http://localhost:8080/health
curl http://localhost:8081/health
curl http://localhost:8082/health
curl http://localhost:8083/health

Ground-truth senaryosu çalıştırma:

cd test-platform
python scripts/scenario_runner.py run <scenario.yaml>

Uyumlu bir MicroK8s/Juju/COS laboratuvarı hazırsa COS smoke iş akışını çalıştırma:

cd test-platform
./scripts/run_cos_stack_check.sh

Yerel yığın smoke iş akışını çalıştırma:

cd test-platform
./scripts/run_local_stack_check.sh

Bu smoke script’leri depo düzeyindeki .venv’in ve gerekli yerel altyapı komutlarının var olmasını bekler. Çalıştırma çıktılarını test-platform/runs/... altına yazarlar.

Test ve kalite

CLI lint ve testleri:

cd cli
python -m ruff check .
python -m pytest -q

Ağ geçidi testleri:

cd observability-gateway
python -m pytest -q

CLI wheel derleme:

cd cli
python -m build

Ağ geçidi wheel derleme:

cd observability-gateway
python -m build

.github/workflows/cli-ci.yml iş akışı CLI paketini Python 3.12 üzerinde editable dev kurulumu, Ruff ve Pytest ile çalıştırır. .github/workflows/gateway-image.yml iş akışı ise gateway-v* etiketleri veya manuel tetikleme için ağ geçidi imajını derleyip GHCR’a gönderir.

Dağıtım seçenekleri

Ağ geçidi için Docker imajı:

docker pull ghcr.io/caglarkc/sentinel-gateway:latest

Helm chart:

helm dependency update ./charts/sentinel
helm upgrade --install sentinel ./charts/sentinel \
  --create-namespace -n sentinel \
  --set gateway.token=<token>

Yerel/laboratuvar Compose yığını varlıkları for-download/compose/ altında bulunur ve CLI kurulum varlıklarına paketlenir.

Güvenlik ve güvenilirlik notları

Gözlemlenebilirlik ağ geçidi bilinçli olarak salt-okunurdur; alarm yönetimi, dashboard yönetimi, arka uç yazma işlemleri veya Grafana datasource proxy’si uygulamaz.
SENTINEL_OBSERVABILITY_GATEWAY_TOKEN yapılandırıldığında ağ geçidi bearer kimlik doğrulaması etkinleşir.
Ağ geçidi arka uç hataları, yeniden denenebilirlik meta verisi ve sır sızdırmayan mesajlar içeren yapılandırılmış bir yanıt modeli kullanır.
CLI yapılandırma şablonları sırları commit edilen yapılandırma dosyalarında değil ortam değişkenlerinde tutar.
.gitignore; .env, yerel Sentinel oturumları, kimlik bilgileri, anahtar materyali, derleme çıktıları, önbellekler, loglar ve yerel çalıştırma çıktılarını hariç tutar.
CLI araçları onay modları, shell ve dosya yazma zaman aşımları, çıktı limitleri, isteğe bağlı salt-okunur bash davranışı ve isteğe bağlı bellek yazma hapsi içerir.
Bellek yazmaları, kalıcılaştırılmadan önce yaygın sır desenleri için redaksiyon mantığından geçer.
Ağ geçidi Dockerfile’ı servisi root olmayan sentinel kullanıcısı olarak çalıştırır.
Helm chart root olmayan pod güvenlik bağlamı ayarlar, ayrıcalık yükseltmeyi devre dışı bırakır, Linux yeteneklerini düşürür ve ağ geçidi konteyneri için salt-okunur kök dosya sistemi kullanır.

Mevcut sınırlar

Proje, CLI paket meta verisinde Pre-Alpha olarak işaretlidir.
COS kurulum arka ucu henüz tam bir kurulumcu değildir; kod preflight, install ve verify adımlarını TODO olarak işaretler.
TLS sonlandırma, süreç denetimi ve sır rotasyonu gibi üretim sıkılaştırması, mevcut ağ geçidi README kapsamının dışında belgelenmiştir.
README hazırlığı sırasında ana Sentinel proje ağacında ekran görüntüsü veya UI varlığı bulunamamıştır.
agentic/ harici/referans projeler içerir ve teslim edilen Sentinel ürünü olarak sunulmamalıdır.

Sonraki geliştirmeler

MicroK8s/Juju/COS kurulumunun CLI’dan tutarlı biçimde sürülebilmesi için COS kurulum arka ucunu tamamlamak.
TLS, ingress, sır rotasyonu ve süreç denetimini kapsayan bir üretim dağıtım kılavuzu eklemek.
Ağ geçidi destekli ajan run ve repl iş akışları etrafında uçtan uca testleri genişletmek.
scenario_runner.py için keşfedilebilir bir konumda örnek senaryo dosyaları eklemek.
Portföy sunumu için mimari diyagramlar ve üretilmiş ekran görüntüleri veya kavramsal görseller yayımlamak.
Yerel demo, Kubernetes demo ve COS laboratuvar yollarını ayıran özlü bir genel hızlı başlangıç eklemek.