Rapor ve Export Hatalari

CSV/Excel export islemlerinin basarisiz olmasi, PDF rapor olusturma sorunlari ve zamanlanmis rapor gorevlerinin calismamasi durumlarinin teshis ve cozum rehberi.

Sorun Tablosu

Semptom	Olasi Sebep	Kontrol	Cozum
CSV export bos	Tarih araligi yanlis, veri yok	Measurement tablosunda veri kontrol	Tarih formatini duzelt (ISO 8601)
Excel export timeout	Cok buyuk veri seti	Query EXPLAIN ANALYZE	Tarih araligini daralt, pagination kullan
PDF rapor olusmuyor	Celery worker mesgul	Celery queue kontrol	Worker restart, ayri queue kullan
Rapor zamanlayici calismiyor	Celery beat durmus	`docker logs celery-beat`	Beat container restart

Detayli Teshis ve Cozumler

1. CSV Export Bos Donuyor

Semptom: Kullanici CSV export butonuna tikliyor, dosya indiriliyor ama icinde sadece baslik satiri var, veri yok.

Olasi Sebepler:

Frontend'den gonderilen tarih araligi yanlis formatta (ornegin DD/MM/YYYY yerine YYYY-MM-DD gerekli)
Secilen tarih araliginda gercekten veri yok
Timezone uyumsuzlugu — frontend yerel saat gonderiyor, backend UTC bekliyor
Device ID veya metric filtresi yanlis

Kontrol Adimlari:

# 1. Backend'e giden istegi kontrol et (network tab veya log)
# Beklenen istek:
# GET /api/v1/reports/export?
#   device_id=42
#   &metric=active_power
#   &start=2026-04-01T00:00:00Z    ← ISO 8601 + UTC
#   &end=2026-04-07T23:59:59Z
#   &format=csv

-- 2. Veritabaninda o aralıkta veri var mi kontrol et
SELECT count(*), min(time), max(time)
FROM measurements
WHERE device_id = 42
  AND metric = 'active_power'
  AND time BETWEEN '2026-04-01T00:00:00Z' AND '2026-04-07T23:59:59Z';

-- count = 0 ise o aralıkta veri yok
-- min/max zaman aralığını doğrula

# 3. Backend export endpoint loglarini kontrol et
docker compose logs backend --tail=100 | grep -i "export\|report"

Cozum:

Tarih formatı: Frontend'den gonderilen tarihlerin ISO 8601 formatında (YYYY-MM-DDTHH:mm:ssZ) oldugundan emin olun
Timezone: Tum tarih parametrelerini UTC olarak gonderin. Frontend'de dayjs.utc() veya date.toISOString() kullanin
Veri kontrolu: Export oncesinde kullaniciya "Bu aralıkta X adet kayit bulundu" bilgisi gosterin — 0 kayit varsa uyari verin
Default aralık: Bos tarih araligi gonderildiginde son 24 saati varsayilan olarak kullanin

2. Excel Export Timeout

Semptom: Excel export baslatiliginda uzun sure bekleniyor ve sonunda timeout hatasi (504 Gateway Timeout veya istek iptal) aliyor.

Olasi Sebepler:

Cok genis tarih araligi secilmis (ornegin 1 yillik veri, milyonlarca satir)
TimescaleDB sorgusu yavvs — indeks eksik veya yanlis
Backend response timeout (Nginx/Uvicorn) yetersiz
Bellek yetersizligi — buyuk veri seti RAM'e sigmiyor

Kontrol Adimlari:

-- 1. Sorgu performansini analiz et
EXPLAIN ANALYZE
SELECT time, device_id, metric, value
FROM measurements
WHERE device_id = 42
  AND time BETWEEN '2026-01-01' AND '2026-04-07'
ORDER BY time;

-- Seq Scan gorunuyorsa indeks eksik
-- Execution Time > 30s ise sorgu optimizasyonu gerekli

# 2. Satir sayisini kontrol et
docker compose exec postgres psql -U zeus -c "
  SELECT count(*)
  FROM measurements
  WHERE device_id = 42
    AND time BETWEEN '2026-01-01' AND '2026-04-07';
"
# 1.000.000+ satir → timeout riski yuksek

# 3. Backend bellek kullanımını kontrol et
docker compose exec backend ps aux --sort=-%mem | head -5
docker stats backend --no-stream

Cozum:

Tarih araligi kisitlama: Frontend'de maksimum export araligini sinirlayin (ornegin tek seferde en fazla 1 ay)

Pagination / streaming: Buyuk veri setlerini parca parca (chunk) islenerek dosyaya yazin:

# Streaming CSV/Excel response
async def export_large_dataset():
    async for chunk in query_in_batches(batch_size=10000):
        yield format_chunk(chunk)

Asenkron export: Buyuk export islemlerini Celery task olarak arka planda calistirin, tamamlandiginda kullaniciya bildirim gonderin
Timeout artirma: Nginx'te proxy_read_timeout ve Uvicorn'da --timeout-keep-alive degerlerini artirin (ornegin 300 saniye)

TimescaleDB optimizasyonu: time kolonunda TimescaleDB chunk indekslerinin dogru oldugundan emin olun:

-- Chunk bilgisini kontrol et
SELECT show_chunks('measurements');

-- Compression aktif mi?
SELECT * FROM timescaledb_information.compression_settings;

3. PDF Rapor Olusmuyor

Semptom: Zamanlanmis veya talep uzerine olusturulan PDF rapor dosyasi uretilmiyor. Rapor durumu "beklemede" veya "hata" gosteriyor.

Olasi Sebepler:

Celery worker durmus veya tum worker'lar mesgul
PDF olusturma kutuphanesi (WeasyPrint, ReportLab vb.) hata veriyor
Sablon (template) dosyasi eksik veya bozuk
MinIO (dosya depolama) erisim hatasi

Kontrol Adimlari:

# 1. Celery worker durumunu kontrol et
docker compose ps celery-worker
docker compose exec celery-worker celery -A app inspect active
docker compose exec celery-worker celery -A app inspect reserved

# Aktif task yoksa worker idle — sorun baska yerde
# Reserved task'lar birikmisse worker mesgul veya takilmis

# 2. Celery worker loglarini kontrol et
docker compose logs celery-worker --tail=200 | grep -i "report\|pdf\|error\|traceback"

# 3. MinIO erisimini kontrol et
docker compose ps minio
# MinIO console: http://localhost:9001
# Bucket'in var oldugundan ve yazma yetkisinin oldugundan emin olun

# 4. PDF kutuphanesi bagimliligini kontrol et
docker compose exec backend python -c "import weasyprint; print('OK')"
# veya
docker compose exec backend python -c "from reportlab.lib.pagesizes import A4; print('OK')"

Cozum:

Worker restart: docker compose restart celery-worker

Ayri queue: PDF olusturma islerini ayri bir Celery queue'da calistirin — diger task'lar PDF olusturmayi engellemesin:

# celery config
task_routes = {
    'app.tasks.generate_report': {'queue': 'reports'},
}

# Reports queue icin ayri worker
celery -A app worker -Q reports -c 2

Retry mekanizmasi: Basarisiz PDF task'lari otomatik yeniden denesin:

@celery_app.task(bind=True, max_retries=3, default_retry_delay=60)
def generate_report(self, report_id):
    try:
        # PDF olustur
    except Exception as exc:
        raise self.retry(exc=exc)

MinIO baglantisi: MinIO container'inin calistigini ve credential'larin dogru oldugundan emin olun

4. Rapor Zamanlayici Calismiyor

Semptom: Gunluk veya haftalik zamanlanmis raporlar uretilmiyor. Kullanicilar raporlarinin gelmedigini bildiriyor.

Olasi Sebepler:

Celery Beat container durmus
Beat schedule veritabani/dosyasi bozulmus
Timezone ayari yanlis — task yanlis saatte calisiyor
Celery Beat ile worker arasindaki Redis baglantisi kopuk

Kontrol Adimlari:

# 1. Celery Beat container'ini kontrol et
docker compose ps celery-beat
docker compose logs celery-beat --tail=100

# Beklenen log:
# [INFO] beat: Starting...
# [INFO] Scheduler: Sending due task generate-daily-report

# 2. Redis baglantisini kontrol et
docker compose exec redis redis-cli ping
# Yanit: PONG

# Beat schedule key'lerini kontrol et
docker compose exec redis redis-cli KEYS "celery*"

# 3. Zamanlanmis task tanimlarini kontrol et
# backend/app/core/celery/ veya backend/app/tasks/

# Ornek schedule tanimi:
# beat_schedule = {
#     'generate-daily-report': {
#         'task': 'app.tasks.reports.generate_daily_report',
#         'schedule': crontab(hour=6, minute=0),  # Her gun 06:00 UTC
#     },
# }

# 4. Son basarili calisma zamanini kontrol et
docker compose exec postgres psql -U zeus -c "
  SELECT id, report_type, status, created_at
  FROM reports
  ORDER BY created_at DESC
  LIMIT 10;
"

Cozum:

Beat restart: docker compose restart celery-beat

Schedule sifrilama: Beat schedule veritabanini sifirlayin:

# Dosya tabanli schedule kullaniliyorsa
docker compose exec celery-beat rm -f /app/celerybeat-schedule
docker compose restart celery-beat

# Redis tabanli schedule kullaniliyorsa
docker compose exec redis redis-cli DEL "celery-beat-schedule"

Timezone ayari: Celery konfigurasyonunda timezone'un dogru ayarlandigindan emin olun:
```
# celery config
timezone = 'UTC'  # veya 'Europe/Istanbul'
enable_utc = True
```

Monitoring: Celery Flower veya Prometheus metrikleri ile beat task'larinin calisma durumunu izleyin:

# Flower ile izleme
celery -A app flower --port=5555
# http://localhost:5555 adresinden task gecmisini gorun

Export Performans Optimizasyonu

Buyuk veri setleri ile calisirken su optimizasyonlari uygulayin:

TimescaleDB Sorgu Optimizasyonu

-- 1. Continuous Aggregate kullanin (onceden hesaplanmis ozet)
CREATE MATERIALIZED VIEW daily_device_stats
WITH (timescaledb.continuous) AS
SELECT
    time_bucket('1 day', time) AS bucket,
    device_id,
    metric,
    avg(value) AS avg_value,
    min(value) AS min_value,
    max(value) AS max_value,
    count(*) AS sample_count
FROM measurements
GROUP BY bucket, device_id, metric;

-- 2. Export sorgularinda ham veri yerine aggregate kullanin
-- Bu sorgu milyonlarca satir yerine gunluk ozet dondurur

Export Boyut Sinirlari

Export Tipi	Onerilen Maks Satir	Maks Tarih Araligi
CSV	500.000	3 ay
Excel (XLSX)	100.000	1 ay
PDF Rapor	10.000	1 hafta

Buyuk Veri Setleri

1 milyondan fazla satir iceren export talepleri icin kullaniciya asenkron export onerin: "Raporunuz hazirlandiginda e-posta ile bildirim alacaksiniz." Bu yontemle timeout sorunu ortadan kalkar.

Sorun Tablosu​

Detayli Teshis ve Cozumler​

1. CSV Export Bos Donuyor​

2. Excel Export Timeout​

3. PDF Rapor Olusmuyor​

4. Rapor Zamanlayici Calismiyor​

Export Performans Optimizasyonu​

TimescaleDB Sorgu Optimizasyonu​

Export Boyut Sinirlari​

Sorun Tablosu

Detayli Teshis ve Cozumler

1. CSV Export Bos Donuyor

2. Excel Export Timeout

3. PDF Rapor Olusmuyor

4. Rapor Zamanlayici Calismiyor

Export Performans Optimizasyonu

TimescaleDB Sorgu Optimizasyonu

Export Boyut Sinirlari