Yapılandırma

Orbtrace'in varsayılanları hızlı başlangıç için yeterli. Üretim trafiğine açmadan önce bu sayfayı bir kez baştan sona okuyun ve her değeri bilinçli olarak ayarlayın. Buradaki her değişken gerçek — gönderilen docker/.env.example ile birebir.

Ayarlar nerede yaşar?

İsimlendirme kuralı

Üçüncü taraf bir SDK ya da dış sistem doğrudan okuyorsa → vendor-native ad, ön ek yok (ANTHROPIC_API_KEY, PGHOST, DORIS_USER, REDIS_HOST). Yalnız Orbtrace'in kendi kodu okuyorsa → ORBTRACE_ ön eki (ORBTRACE_SECRET_KEK, ORBTRACE_AI_PROVIDER). Bu yüzden örneğin Doris bağlantı değişkenleri çıplak DORIS_* (Collector da okur) ama HikariCP havuz boyutu ORBTRACE_DORIS_POOL_* (yalnız Orbtrace okur).

Çekirdek

PostgreSQL (ayarlar veritabanı)

libpq-native adlar — Spring çıplak ${PGHOST} vb. okur.

Apache Doris (telemetri veritabanı)

Doris-native adlar — Collector da otelcol-config.yaml'dan aynı ${DORIS_USER} / ${DORIS_PASSWORD}'ü okur.

Valkey (önbellek)

Lisans

AI sağlayıcı (Sebep RCA'sı + Astra + Replay)

ORBTRACE_AI_PROVIDER, AI özelliklerinin hangi LLM'i kullanacağını seçer — citation tutarlılığı için bir seferde tek aktif sağlayıcı. Geçerli değerler: anthropic (varsayılan), openai, azure-openai, google-gemini, ollama, openai-compatible. İlgili kimlik bilgilerini ayarlayın; diğerlerini boş bırakın. Hava boşluklu dağıtımlar ollama ya da kendi barındırdığınız bir openai-compatible sunucu kullanır. Aktif sağlayıcıyı, modeli — ayrıca anahtarları, uç noktaları ve TLS'i — çalışma zamanında Yönetim → AI'dan değiştirebilirsiniz.

Env mi, saklanan mı — neyi restart ister. Yukarıdaki her değer bootstrap ve geri-düşüş (fallback) içindir. Yönetim → AI'dan ayrıca bir API anahtarını (at-rest şifreli) ve on-prem sağlayıcılar (ollama, openai-compatible) için bir temel URL + TLS güveni saklayabilirsiniz — saklanan değer env değişkenini ezer ve anında etkili olur, restart yok. Bir env anahtarını ya da temel URL'sini değiştirmek hâlâ container restart ister. Saklanan anahtarları at-rest şifrelemek için ORBTRACE_SECRET_KEK'i 16/24/32 rastgele baytın base64'üne ayarlayın (ORBTRACE_JWT_KEK ile aynı operatör-sahipli-sır modeli); ayarlı değilken anahtarlar düz metin saklanır ve uyarı loglanır. Saklanan anahtarlar API tarafından asla geri döndürülmez — yönetim ekranı yalnızca bir "saklandı" işareti ve son 4 karakteri gösterir.

AI orkestrasyon knob'ları (hepsi ORBTRACE_AI_* / ORBTRACE_ASTRA_*, hepsi baked-in varsayılanlarla opsiyonel) bütçeleri, failover'ı, yanıt önbelleğini ve Astra asistanının araç-başına limitlerini kapsar — ör. ORBTRACE_AI_BUDGET_ENABLED, ORBTRACE_AI_FAILOVER_ENABLED, ORBTRACE_ASTRA_BUDGET_RESET_INTERVAL. Tam liste için .env.example'daki "Behavioral tuning knobs" bloğuna bakın. Not: vendor kimlik bilgileri vendor-native ad kullanır; ORBTRACE_AI_* yalnız Orbtrace'in kendi orkestrasyonu içindir.

Kimlik doğrulama

Orbtrace kullanıcıları bir kimlik sağlayıcısı (SSO) üzerinden giriş yaptırır. Dört yoldan en az biri için kimlik bilgilerini ayarlayıp yeniden başlatın. Sağlayıcı-başına tam anlatım: Kimlik doğrulama.

Literal change-me bırakılan bir client-id açılışta ayıklanır, dolayısıyla düğme hiç görünmez — ayrı bir "etkinleştir" bayrağı ve kırık düğme yoktur.

IdP'nize kaydedeceğiniz redirect URI'si {ORBTRACE_BACKEND_URL}/login/oauth2/code/{provider} olup {provider} şunlardan biridir: google, microsoft, github veya oidc.

Saklama (retention)

İki farklı mekanizma — karıştırmayın:

• Telemetri saklaması (log / trace / metriklerin Doris'te ne kadar kaldığı) bir env değişkeni değildir. Bunu Doris profili belirler (small / medium / large, Helm'de doris.profile.activeProfile ile ya da Compose image'ına gömülü profil) — ör. small profili 7 gün log, 14 gün trace, 30 gün metrik tutar. Bunları doris.profile.retention.* ile (değerler gün cinsinden) ayrıca geçersiz kılabilirsiniz. Doris partition'lar yaşlanınca tüm partition'ı düşürür, böylece disk anında geri kazanılır. Telemetri saklamasını değiştirmek için bir env değişkenini değil, profili değiştirirsiniz.
• Operasyonel saklama (audit log + Replay/zaman çizelgesi geçmişi) ayarlanabilir ve ayrıca Yönetim → Saklama'da canlı düzenlenebilir:

Örnekleme (sampling)

Örnekleme tek bir aç/kapa env değişkeni değildir. İş birliği yapan iki katmandır:

1. Collector'ınızın tail_sampling processor'ı tut/at kararını verir ve hard-keep kurallarını uygular — hatalar, p99'dan yavaş trace'ler, yeni yollar, SLO ihlalleri ve anomali-etiketli trace'ler her zaman tutulur. Bunlar Orbtrace'te değil, Collector config'inizde (otelcol-config.yaml) yaşar.
2. Orbtrace olasılıksal tabanı yayımlar: Yönetim → Örnekleme'de ayarladığınız servis-başına aylık trace-sayısı tavanları. Orbtrace tavana karşı burn-rate hesaplar ve Collector'ınızın tükettiği /api/sampling/policy.yaml'ı yeniden yayımlar. Bu, Doris diskini korur ve sinyal-gürültü oranını yüksek tutar.

İlgili tek env knob'u ORBTRACE_SAMPLING_SLOW_TRACE_THRESHOLD_MS (varsayılan 1000) — bir trace'in hard-keep için "yavaş" sayıldığı gecikme eşiği.

SLO önerileri

Orbtrace, her servisin kendi gecikme geçmişinden servis-başına bir SLO hedefi önerebilir — hedefi asla otomatik olarak ayarlamaz. Gecelik bir iş, servisin geri-bakış penceresi boyunca altında kaldığı günlük p95'ten öneriyi türetir; ardından bir yönetici SLO ekranında inceleyip Kabul eder (ve oradan istek üzerine yeniden hesaplatabilir). Akış için SLO'lar & alarm'a bakın.

Varsayılan olarak kapalı. İki örnek-kapısı bir sinyal-kalitesi barıdır: bir servisin, geri-bakış içinde en az min usable days takvim günü (her biri en az min daily samples gelen-istek span'iyle) olması gerekir — aksi halde öneri üretilmez, çünkü bir hedefi dürüstçe koymak için geçmiş çok azdır. Varsayılanlar bir üretim filosuna uygundur; yepyeni bir kurulum ya da kısa bir demo tek günde yalnızca birkaç saatlik veriye sahiptir, bu yüzden siz eşikleri düşürene kadar yeniden hesaplama hiçbir şey döndürmez (dev profili bunu zaten yapar, 1 / 5'e indirir).

CORS / proxy

İleri seviye davranış knob'ları

Onlarca ince-ayar zamanlaması ve tavanı yeniden derlemeden geçersiz kılınabilir — asenkron-dikiş skor ağırlıkları, anomali-eğitici eşikleri, alarm değerlendirme pencereleri, Doris sorgu/rollup tavanları, log-tail poll kadansı, operasyon percentile floor'ları ve Astra asistanı limitleri. Her birinin çalışan bir varsayılanı vardır, o yüzden ayarlamıyorsanız boş bırakın. Süreler ISO-8601 (PT30S, PT15M, P7D); cron'lar Spring 6-alan. Tam, açıklamalı liste docker/.env.example'ın altındaki "Behavioral tuning knobs" bloğudur.

Minimal bir üretim .env'i

ORBTRACE_FRONTEND_URL=https://orbtrace.example.com
ORBTRACE_BACKEND_URL=https://orbtrace.example.com
 
PGPASSWORD=<güçlü>
DORIS_PASSWORD=<güçlü>
 
# Opsiyonel lisans (boş → COMMUNITY sürümü)
ORBTRACE_LICENSE_KEY=
 
ORBTRACE_AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
 
# İlk yöneticiyi sabitle (ilk SSO girişinde ADMIN olan e-posta)
ORBTRACE_BOOTSTRAP_ADMIN_USERNAME=siz@example.com
 
# Keycloak ile kurumsal SSO (ya da Auth0 / Okta / Authelia / Entra OIDC)
OIDC_CLIENT_ID=orbtrace
OIDC_CLIENT_SECRET=<IdP'nizden>
OIDC_ISSUER_URI=https://sso.example.com/realms/eng
ORBTRACE_OIDC_DISPLAY_NAME=Acme SSO

Restart vs. canlı

• .env'deki her şey → etkili olması için docker compose up -d (ya da kubectl rollout restart) ister.
• Yönetim arayüzündeki her şey (alarm kuralları, SLO'lar, örnekleme tavanları, saklama pencereleri, aktif AI sağlayıcı, kullanıcı rolleri) → anında etkili, restart yok.

JWT imzalama anahtarları uygulama tarafından yönetilen RSA'dır — ilk açılışta üretilir ve PostgreSQL'de saklanır; ayarlanacak ya da döndürülecek bir imzalama-sırrı env değişkeni yoktur. Anahtarı POST /api/admin/jwt-keys/rotate ile döndürmek mevcut tüm oturum token'larını geçersiz kılar — herkes tekrar giriş yapar. Kullanıcıya görünür etki yaratan tek değişiklik bu döndürmedir. Politika operatör anahtarı gerektiriyorsa kendi çiftinizi ORBTRACE_JWT_PRIVATE_KEY / ORBTRACE_JWT_PUBLIC_KEY ile sabitleyin.