Sorun giderme

Bu sayfa ne gördüğünüze göre düzenlenmiş, motor altında neyin bozuk olduğuna göre değil. Eşleşen semptomdan başlayın.

Belirti: Arayüzü açıyorum, bağlantı reddi / hiçbir şey olmuyor

1. 1

   Container'lar ayakta mı?

   docker compose ps

   Her satır running ve healthy olmalı. orbtrace exited ise docker compose logs orbtrace | tail -200 ile sebebe bakın — genelde eksik env (PGPASSWORD yok) ya da PostgreSQL henüz erişilemiyor.

2. 2

   Arayüz portu erişilebilir mi?

   curl -I http://localhost:8080

   200 ya da 302 dönmeli. connection refused ise ya sunucu henüz açılmadı (Doris'e 2–3 dakika tanıyın) ya da 8080 portu dolu — docker-compose.yml'da remap edin ya da çakışan servisi durdurun. (Orbtrace varsayılan olarak 8080'de düz HTTP sunar; 80/443 yalnızca Caddy edge profilini ya da kendi proxy'nizi açtıysanız vardır.)

3. 3

   Arka uç sağlıklı mı?

   curl -sf http://localhost:8080/actuator/health

   {"status":"UP"} beklenir. DOWN ise components dizisi hangi bağımlılığın (db, doris, valkey) bozulduğunu söyler.

Belirti: Girebiliyorum ama hiçbir veri görünmüyor

1. 1

   Uygulamalar gönderiyor mu?

   Uygulamanın çalıştığı host'tan:

   nc -zv <orbtrace-host> 4317

   succeeded demeli. Demiyorsa ağ/firewall problemi — portu açın.

2. 2

   Collector kabul etti mi?

   docker logs orbtrace-otelcol | tail -100

   (Sizin çalıştırdığınız Collector'ın adını kullanın — Orbtrace bir tane paketlemez.) accepted_spans, accepted_logs, refused_spans arayın. Refus genelde: Collector'ınızın istediği ama uygulamanın göndermediği bir auth başlığı, ya da kötü protokol (HTTP body gRPC portuna ya da tersine).

3. 3

   Doris aldı mı?

   docker compose exec doris-fe mysql -u root -e \
     "SELECT count(*) FROM orbtrace.otel_logs WHERE timestamp >= now() - interval 5 minute"

   Sıfırdan büyük? Veri depoda; sorun okuma yolunda / zaman seçicide. Sıfır? Collector düşürüyor — adım 2'yi yine kontrol edin.

4. 4

   Arayüz zaman seçicisi doğru mu?

   "Veri yok"un en yaygın sebebi, verinizin gelişinden önceki bir aralığa ayarlı zaman seçicisidir. "Son 15 dk" yapıp yeniden bakın.

5. 5

   Örnekleme fazla mı atıyor?

   Yalnız bazı veriler eksikse Yönetim → Sampling'e bakın. keep errors ve keep slow geçersizliklerinin açık olduğunu doğrulayın. Global temel oranı geçici olarak 1.0 yapın — veri dönerse fazla örneklediniz.

Belirti: Doris BE sağlıksız

1. 1

   Doris BE logu

   docker compose logs doris-be | tail -200

2. 2

   MEM_LIMIT_EXCEEDED

   Doris BE'nin sert bellek tavanı vardır (mem_limit be.conf'ta). Aşılınca BE çöker. Belirtiler: yazma başarısı düşer, Health kırmızı. Çözüm:

   • Yutum oranını yumuşatın (tohum azalt, örneklemeyi daralt).
   • Host'un RAM'i varsa mem_limit'i artırın.
   • M-serisi dizüstüde dev yığını: birleşik akış ~25K olay/sn altında kalsın.
3. 3

   Depo dolu mu?

   Doris disk %95 üstüne çıkınca yazımı durdurur. Host'ta df -h. Sınıra yakınsanız telemetri saklamasını kısaltın — bunu Doris profili belirler (doris.profile.retention.*'ı (gün cinsinden) düşürün ya da daha sıkı bir small / medium / large katmanı seçin), bir sonraki süpürmede partition'lar geri kazanılır — ya da disk ekleyin. (Telemetri saklaması bir Doris-profili ayarıdır, bir ORBTRACE_* env değişkeni değil.)

Belirti: RCA bozuk / "AI sağlayıcı başarısız"

1. 1

   Bağlantıyı test edin

   Yönetim → AI → Bağlantıyı test et. Buton SDK hatasını yüzeye çıkarır.

2. 2

   Yaygın SDK hataları

   • 401 Unauthorized → yanlış API anahtarı.
   • 403 Forbidden → anahtar geçerli ama org rate-limited ya da model kapalı.
   • Timeout → upstream yavaş; SPRING_AI_RETRY_BACKOFF_MAX_INTERVAL'ı artırın.
   • Budget exceeded → ORBTRACE_AI_BUDGET_MONTHLY_USD aşıldı. RCA bilinçli olarak ay sonuna ya da sınırı yükseltene kadar kapalı.
3. 3

   Ollama ise host orbtrace container'ından erişilebilir mi?

   Temel URL docker ağı içinden erişilebilir olmalı — http://ollama:11434 ancak ollama aynı compose ağında bir container ise çalışır. Dışarıdan erişiyorsanız portu açıp host IP'sini kullanın.

Belirti: Giriş kabul etmiyor (ya da hiç düğme yok)

1. 1

   Hiç giriş düğmesi yok mu?

   Hiçbir SSO sağlayıcısı yapılandırılmamış (her client-id boş ya da hâlâ change-me). En az bir sağlayıcının kimlik bilgilerini ayarlayıp yeniden başlatın — bkz. Kimlik doğrulama. Gizli bir yerel-giriş URL'si yoktur; Orbtrace yalnızca yapılandırdığınızı gösterir.

2. 2

   Yerel deneme girişini mi kullanıyorsunuz?

   ORBTRACE_BOOTSTRAP_ADMIN_PASSWORD'ü (ORBTRACE_BOOTSTRAP_ADMIN_USERNAME ile birlikte) ayarladıysanız, tam o e-posta ve parolayla girin. Kullanıcı adı olmadan ayarlanan parola açılışı durdurur, yani sunucu ayaktaysa ve form yoksa kullanıcı adı da ayarlıdır. admin@nivorbit.local varsayılanı ve otomatik üretilen parola yoktur.

3. 3

   IdP'den sonra SSO başarısız

   Neredeyse her zaman bir redirect-URI uyuşmazlığı: IdP'nize kayıtlı URI tam olarak {ORBTRACE_BACKEND_URL}/login/oauth2/code/{provider} olmalı (google/microsoft/github/oidc). Sunucu logu WARN seviyesinde tek satırlık bir sebep basar — invalid_client, redirect_uri_mismatch ya da missing email (IdP email claim'i dönmedi).

4. 4

   Girdim ama hemen geri atıldım?

   Sunucu saati kaymış, token'lar süresi geçmiş görünüyor. Host saatini NTP'ye karşı saniye düzeyinde kontrol edin.

Belirti: Arayüz yavaş, grafikler 10+ saniye

1. 1

   Pencere çok geniş mi?

   Yoğun filoda "Son 30 g" yüzlerce GB tarar. Daraltın. 30 g gerekirse span'lerden değil, ön toplanmış metriklerden kurun.

2. 2

   Doris BE meşgul mü?

   Yönetim → Health → Doris. slow queries artıyor ya da BE CPU %100'deyse okuma yüküne göre az kaynaklı. İki seçenek: Doris BE ölçeklendir ya da ORBTRACE_DORIS_POOL_MAX_SIZE'ı artırın.

3. 3

   Yüksek kardinalite group-by?

   user_id üzerinde group-by binlerce seri çizer. Düşük kardinaliteli özniteliklerle gruplayın (service, route, region).

Belirti: Haritada bağlanması gereken iki servis arasında kenar yok

1. 1

   Trace context yayılımını doğrulayın

   Her iki servis OTel-enstrümante olmalı. Arayan W3C traceparent başlığı göndermeli. Çağrılan çıkarmalı. Otomatik enstrümantasyon HTTP ve gRPC için bunu yapar; özel taşıma (ham socket, kuyruk, FTP) için elle span linki gerekir.

2. 2

   Kuyruk tabanlı çağrılar için Async Stitching

   Kafka, RabbitMQ, SQS, Redis Streams çağrıları yutum sonrasında Orbtrace'in async-stitching işiyle birleştirilir. Kenarlar yoksa Yönetim → Health → Background jobs → Async stitching çalışıyor mu kontrol edin — 30 sn'de bir koşmalı.

3. 3

   Zaman penceresini kontrol edin

   Harita yalnız pencerede en az bir çağrısı olan kenarları çizer. "Son 5 dk" ayarlıysa ve çağrı saatlik ise kenar görünmez.

Belirti: Bir container birkaç dakikada bir yeniden başlıyor

docker compose ps -a | grep -i restart
docker compose logs <ad> --since 10m

Yaygın sebepler:

• OOM kill — host'ta dmesg | grep -i kill OOM olaylarını gösterir. Container bellek limitini ya da host RAM'ini artırın.
• Liveness probe başarısız — container downstream çöktüğü için sağlıksız raporluyor. Log'taki ilk hatayı okuyun; sebebi gösterir.
• Kötü config — env yazım hatası, bozuk YAML. Loglar açık; okuyun.

Belirti: Başlangıçta "Could not bind to port"

Port host'ta başka bir süreç tarafından alınmış ya da başka bir container önce talep etmiş. lsof -i :4317 ya da ss -tlnp | grep 4317 sahibi belirler. Ya durdurun ya da docker-compose.yml'da yeniden eşleyin.

Belirti: OpenShift'te Postgres log'unda chmod ... /var/run/postgresql: Operation not permitted

Zararsız — hata değil. Gömülü Postgres imajı (upstream postgres; pgvector/pgvector onun üzerine kuruludur) açılışta socket dizinini chmod eder. OpenShift'in restricted-v2 SCC'si altında pod, o dizinin sahibi olmayan rastgele atanmış bir UID ile çalışır; bu yüzden chmod değiştiremez ve satırı yazar (imaj || : ile atlar). Bu satırı Orbtrace chart'ı üretmez. Postgres normal başlar — hemen sonraki log satırlarıyla (database system is ready to accept connections) ve oc get pod -l app.kubernetes.io/component=postgres'in Running göstermesiyle doğrulayın. Düzeltilecek bir şey yok.

Eskalasyon ne zaman?

Yukarıdakilerin hiçbiri çözmüyorsa toplayın:

1. docker compose ps
2. docker compose logs --since 30m > orbtrace-debug.log
3. Yönetim → Health ekran görüntüsü.
4. UI tarafıysa tarayıcı DevTools ağ sekmesi.

Premium destek için paket gönderin, Standart için GitHub issue açın. Bu beş şey biletlerin yaklaşık %90'ını takip sorusuz çözer.

Sırada: SSS.