Belajar GraphQL - Common Issues & Debugging Techniques

#Pendahuluan

Setiap aplikasi nyata punya bug — yang membedakan engineer senior adalah kemampuan menemukan dan memperbaikinya dengan cepat. Episode 45 membekali kalian dengan troubleshooting dan debugging GraphQL secara sistematis.

Kita akan mempelajari masalah umum, tools debugging, cara men-debug performa, investigasi error, dan teknik debugging di production.

#Common Problems

#N+1, Circular Dependencies, dan Memory Leaks

Masalah yang paling sering muncul di GraphQL:

• N+1 queries: sudah kalian taklukkan di episode 9 — indikasinya: log query berulang dengan pola yang sama.
• Circular dependencies: saat tipe saling merujuk (User dan Post) tanpa batas query; biasanya bukan bug, tapi bisa membuat tracing bingung — batasi kedalaman.
• Memory leaks: hasil query yang di-cache tanpa batas, atau listener subscriptions yang tidak dibersihkan — tumbuh perlahan hingga server melemah.
• Slow queries: resolver tanpa index atau batching.
• Authentication failures: token yang tidak terparse, secret berbeda antar environment.
• Cache inconsistencies: cache Redis atau client yang tidak di-invalidate setelah mutation.

Deteksi memory leak dengan --inspect

node --inspect dist/index.js

#Debugging Tools

#Apollo Studio dan Chrome DevTools

• Apollo Studio: operasi populer, error, dan tracing per resolver (episode 24) — tempat pertama memeriksa masalah production.
• Chrome DevTools Network tab: melihat request GraphQL, durasi, dan response mentah dari sisi client.
• GraphQL Playground / Sandbox: menguji ulang query dengan mudah saat menyelidiki.
• Logging terstruktur: Pino (episode 24) dengan requestId untuk menelusuri satu request lintas log.

Untuk melihat raw request GraphQL dari terminal, gunakan curl http://localhost:4000/ -H "Content-Type: application/json" -d '{"query":"{ posts { id } }"}'.

#Distributed Tracing

Untuk masalah yang melintasi banyak service, OpenTelemetry (episode 24) menunjukkan trace lengkap: span per resolver, per query database, dan per panggilan eksternal. Trace menjawab pertanyaan "di mana waktu hilang" dengan tepat.

#Performance Debugging

#Mengidentifikasi Resolver Lambat

Langkah sistematis untuk query lambat:

1. Ukur durasi total di Apollo Studio.
2. Lihat tracing per field — resolver mana yang paling lambat.
3. Periksa query database yang dihasilkan resolver tersebut.
4. Optimasi: index, DataLoader, atau caching.

Timing resolver sederhana

const slowResolver = async (_, args, ctx) => {
  const start = performance.now();
  const result = await ctx.db.users.findMany();
  ctx.logger.info({ ms: performance.now() - start }, "query users");
  return result;
};

#Profiling dan Load Testing

Untuk analisis lebih dalam, pakai profiler Node (--prof) atau tools seperti clinic.js. Load testing dengan k6 atau artillery mensimulasikan traffic nyata dan menemukan titik patah sebelum pengguna mengalaminya.

#Error Investigation

#Membaca Stack Trace dan Reproduksi

Saat error muncul, investigasi yang disiplin:

1. Baca stack trace dari log atau Sentry (episode 24).
2. Korelasikan dengan requestId dan operasi yang gagal.
3. Reproduksi dengan query yang sama di Sandbox — persempit variabel.
4. Debug resolver dengan menambahkan log atau breakpoint.
5. Periksa context: user apa, environment apa, data apa yang masuk.

Log error dengan context

async function resolver(_, args, ctx) {
  try {
    return await heavyOperation();
  } catch (err) {
    ctx.logger.error(
      { err, args, userId: ctx.user?.id },
      "heavyOperation gagal"
    );
    throw err;
  }
}

Kunci investigasi yang cepat: log yang kaya context. Error tanpa context memaksa menebak; error dengan context langsung memberi petunjuk.

#Production Debugging

#Log Analysis dan Incident Response

Debugging production berbeda dari development:

• Log analysis: agregasi log terpusat, pencarian berdasarkan requestId dan timestamp.
• Metrics interpretation: histogram durasi, error rate, dan puncak latensi memberi sinyal dini.
• Incident response: triase (berapa parah, siapa terdampak), komunikasi, mitigasi sementara, lalu fix permanen.
• Post-mortem: dokumentasikan kronologi, akar masalah, dan langkah pencegahan — setiap insiden adalah pelajaran.

journalctl -u api-graphql | grep "requestId=abc123"

#Penutup

Inti yang harus dibawa pulang:

• N+1, circular dependencies, memory leaks, dan cache inconsistencies adalah masalah paling umum.
• Apollo Studio, Chrome DevTools, dan logging dengan requestId adalah tools utama.
• Performance debugging dimulai dari tracing resolver, lalu optimasi database.
• Error yang kaya context mempercepat investigasi secara drastis.
• Debugging production memakai log analysis, metrics, dan incident response.
• Setiap insiden menghasilkan post-mortem dan pencegahan.

Di episode 46 selanjutnya kalian akan mempelajari team workflows dan kolaborasi — kepemilikan dan governance schema, workflow development dengan feature branch, kontrak frontend-backend dengan mocking, quality assurance dengan schema linting, hingga knowledge sharing dengan ADR dan dokumentasi. GraphQL di tim kalian akan berjalan profesional!