Belajar tRPC - Observability, Tracing & Monitoring

#Pendahuluan

Aplikasi production tidak bisa dipercaya tanpa observability — kemampuan memahami apa yang terjadi di dalam sistem lewat log, metrics, dan traces. Episode 14 membahas cara menerapkan ketiganya pada tRPC: monitoring panggilan, tracing end-to-end dari client ke server, dan debugging dengan tooling bawaan.

Kalian akan belajar mengukur: berapa sering procedure dipanggil, berapa lama eksekusinya, dan di titik mana request melambat.

#Monitoring dengan OpenTelemetry, Metrics, dan Logs

#Tiga Pilar Observability

• Logs: catatan peristiwa terstruktur, seperti "procedure user.byId dipanggil".
• Metrics: angka teragregasi seperti jumlah request per detik dan latensi.
• Traces: perjalanan satu request melewati seluruh layanan.

tRPC memudahkan ketiganya karena semua panggilan melewati pipeline middleware. Ambil metadata procedure dengan path dan type:

const observe = t.middleware(async ({ path, type, ctx, next }) => {
  const mulai = Date.now();
  const hasil = await next();
  const durasi = Date.now() - mulai;
 
  logger.info("trpc.request", {
    path,
    type,
    userId: ctx.userId,
    durasiMs: durasi,
    ok: hasil.ok,
  });
 
  if (typeof metrics?.histogram === "function") {
    metrics.histogram("trpc.duration", durasi, { path, type });
  }
  return hasil;
});

Middleware observe mencatat setiap panggilan ke log terstruktur dan sekaligus mengumpulkan histogram durasi per path. Satu titik tangkap mencakup seluruh API — itulah kekuatan middleware tRPC untuk observability.

#Integrasi OpenTelemetry

OpenTelemetry menyediakan standar untuk traces dan metrics. Pasang SDK, lalu hubungkan middleware tRPC dengan tracer global:

npm install @opentelemetry/api @opentelemetry/sdk-node
npm install @opentelemetry/instrumentation-http

import { trace, SpanStatusCode } from "@opentelemetry/api";
 
const tracing = t.middleware(async ({ path, next }) => {
  const tracer = trace.getTracer("trpc");
  return tracer.startActiveSpan(`trpc.${path}`, async (span) => {
    try {
      const hasil = await next();
      span.setStatus({ code: SpanStatusCode.OK });
      return hasil;
    } catch (err) {
      span.setStatus({ code: SpanStatusCode.ERROR });
      span.recordException(err as Error);
      throw err;
    } finally {
      span.end();
    }
  });
});

tracer.startActiveSpan membuat span per procedure. Karena span diberi nama dari path, kalian bisa melihat durasi setiap procedure di Jaeger, Zipkin, atau platform observability lain.

#Tracing End-to-End

#Mengaitkan Client dan Server

Tracing bernilai penuh saat satu trace menyambung dari klik user di browser sampai query database. Kuncinya adalah menyebarkan traceparent di request header:

import { context, trace } from "@opentelemetry/api";
 
const client = createTRPCClient<AppRouter>({
  links: [
    httpBatchLink({
      url: "/api/trpc",
      headers: () => {
        const span = trace.getActiveSpan();
        if (!span) return {};
        return { traceparent: span.spanContext().traceId };
      },
    }),
  ],
});

Server membaca traceparent di createContext dan memakainya sebagai parent span. Hasilnya: satu trace yang menampilkan perjalanan lengkap — client, HTTP, middleware tRPC, dan query database.

#Metric Utama yang Dipantau

Beberapa metric yang sebaiknya selalu dipantau:

• Jumlah panggilan per procedure — untuk melihat endpoint populer dan anomali.
• Durasi p95 dan p99 — bukan hanya rata-rata, agar lonjakan lambat terlihat.
• Error rate — jumlah kegagalan dibagi total panggilan.
• Rasio sukses subscription — koneksi WebSocket yang putus.

Buat dashboard sederhana dari metric ini di platform favorit kalian — mulai dari satu grafik durasi per procedure sudah sangat membantu.

#Debugging dengan Devtools dan Built-in Logger

#Logger Link di Client

Sejak episode 6, loggerLink adalah teman debugging paling cepat:

import { loggerLink } from "@trpc/client";
 
loggerLink({
  enabled: (opts) =>
    process.env.NODE_ENV === "development" || opts.direction === "down",
  colorMode: "ansi",
});

Konfigurasi di atas menampilkan log lengkap di development, dan di production hanya mencatat response masuk — cukup untuk melihat error tanpa kebisingan. colorMode: "ansi" memberi warna yang memudahkan membaca log di terminal.

#Devtools React

Untuk debugging UI, pasang React Query Devtools. Karena tRPC React hidup di atas React Query, devtools ini menampilkan status semua query dan mutation:

npm install --save-dev @tanstack/react-query-devtools

import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
 
<trpc.Provider client={trpcClient} queryClient={queryClient}>
  <QueryClientProvider client={queryClient}>
    {children}
    <ReactQueryDevtools initialIsOpen={false} />
  </QueryClientProvider>
</trpc.Provider>;

Devtools menampilkan query aktif, data ter-cache, waktu stale, dan tombol untuk refetch atau invalidate manual — cara paling cepat memahami kenapa halaman menampilkan data tertentu.

#Penutup

Episode 14 menjadikan API tRPC kalian transparan: monitoring dengan log terstruktur dan metrics, tracing end-to-end dengan OpenTelemetry yang menghubungkan client ke server, serta debugging cepat dengan loggerLink dan React Query Devtools.

Inti yang harus dibawa pulang:

• Middleware tRPC adalah satu titik tangkap untuk log, metrics, dan traces.
• path dan type memberikan dimensi observability per procedure.
• OpenTelemetry menciptakan span bernama path untuk setiap panggilan.
• Sebarkan traceparent di header untuk tracing end-to-end.
• Pantau durasi p95 dan error rate, bukan hanya rata-rata.
• loggerLink dan React Query Devtools mempercepat debugging harian.

Di episode 15 selanjutnya kita akan membahas resilience & fault tolerance — pola retry, exponential backoff, dan error boundary di client, strategi fallback data dan penanganan downtime, serta graceful shutdown untuk server tRPC di production.