Tutorial Observability Modern: Instrumentasi Node.js dengan OpenTelemetry dan SigNoz

Observability modern bukan lagi sekadar monitoring uptime server. Di era microservices dan distributed systems, developer membutuhkan visibilitas end-to-end: dari request masuk ke API gateway, melewati beberapa service, mengakses database, hingga kembali ke client. OpenTelemetry telah menjadi standar de facto untuk instrumentasi, sedangkan SigNoz menawarkan platform observability open source yang menggabungkan traces, metrics, dan logs dalam satu interface. Tutorial ini akan membawa Anda dari nol hingga memiliki dashboard observability lengkap untuk aplikasi Node.js dalam waktu singkat.

Sebelum memulai, pastikan Anda memahami perbedaan antara monitoring tradisional dan observability. Monitoring menjawab pertanyaan apakah sistem hidup?, sementara observability menjawab mengapa sistem berperilaku demikian? Dengan distributed tracing, kita bisa melihat jejak perjalanan satu request melintasi banyak service dan mengidentifikasi bottleneck dengan presisi.

Persiapan Stack dan Instalasi SigNoz

SigNoz dapat dijalankan secara lokal menggunakan Docker Compose. Ini adalah cara tercepat untuk eksplorasi dan development. Clone repository resmi SigNoz dari GitHub dan jalankan installer:

git clone https://github.com/SigNoz/signoz.git
cd signoz/deploy/docker
docker compose -f docker/clickhouse-setup/docker-compose.yaml up -d

Setelah container berjalan, dashboard SigNoz dapat diakses di http://localhost:3301. Default tidak memerlukan autentikasi untuk setup lokal. Pastikan Docker daemon Anda memiliki resource minimal 4GB RAM agar ClickHouse dan Query Service tidak crash.

SigNoz menyediakan endpoint OTLP (OpenTelemetry Protocol) di port 4317 untuk gRPC dan 4318 untuk HTTP. Endpoint inilah yang akan kita konfigurasi sebagai tujuan export data dari aplikasi Node.js.

Langkah 1: Inisialisasi Proyek Node.js dan Instalasi OTel SDK

Buat direktori proyek baru dan inisialisasi dengan npm. Untuk tutorial ini, kita gunakan framework Express.js agar fokus tetap pada observability, bukan boilerplate framework:

mkdir nodejs-observability-demo && cd nodejs-observability-demo
npm init -y
npm install express
npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/exporter-metrics-otlp-grpc @opentelemetry/resources @opentelemetry/semantic-conventions

Package @opentelemetry/auto-instrumentations-node sangat berguna karena secara otomatis menginstrumentasi library populer seperti Express, MongoDB, PostgreSQL, HTTP, dan banyak lainnya tanpa perlu mengubah kode bisnis Anda.

Langkah 2: Konfigurasi Trace Exporter dan Resource Attributes

Buat file tracing.js di root proyek. File ini akan di-require sebelum aplikasi utama dijalankan (preload pattern):

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-grpc');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { Resource } = require('@opentelemetry/resources');
const { SEMRESATTRS_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');

const traceExporter = new OTLPTraceExporter({
  url: 'http://localhost:4317',
});

const sdk = new NodeSDK({
  resource: new Resource({
    [SEMRESATTRS_SERVICE_NAME]: 'nodejs-demo-api',
  }),
  traceExporter,
  metricExporter: new OTLPMetricExporter({ url: 'http://localhost:4317' }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();
console.log('Tracing initialized');

process.on('SIGTERM', () => sdk.shutdown().then(() => process.exit(0)));

Pastikan Anda mengganti localhost:4317 dengan endpoint OTLP SigNoz jika berjalan di remote server. Resource attribute service.name sangat penting karena akan menjadi identifier di dashboard SigNoz.

Langkah 3: Bangun API dengan Instrumentasi Otomatis

Buat file app.js yang berisi beberapa endpoint simulasi proses bisnis:

require('./tracing');
const express = require('express');
const app = express();
app.use(express.json());

app.get('/health', (req, res) => res.json({ status: 'ok' }));

app.get('/users/:id', async (req, res) => {
  // Simulasi query database
  await new Promise(r => setTimeout(r, 50));
  res.json({ id: req.params.id, name: 'User Demo' });
});

app.post('/orders', async (req, res) => {
  // Simulasi pemrosesan kompleks
  await new Promise(r => setTimeout(r, 200));
  res.json({ orderId: Math.random().toString(36), status: 'created' });
});

app.listen(3000, () => console.log('API running on port 3000'));

Jalankan aplikasi dengan perintah:

node app.js

Buat beberapa request menggunakan curl atau Postman. Auto-instrumentasi akan menangkap setiap request HTTP, route handler, dan delay yang terjadi di dalamnya.

Langkah 4: Tambahkan Custom Span untuk Business Logic

Auto-instrumentasi hanya menangkap layer framework. Untuk memahami detail bisnis, tambahkan custom span secara manual di bagian kode yang kritis:

const { trace } = require('@opentelemetry/api');

app.post('/orders', async (req, res) => {
  const tracer = trace.getTracer('order-service');
  const span = tracer.startSpan('process_order_creation');
  span.setAttribute('order.type', req.body.type || 'standard');
  
  await new Promise(r => setTimeout(r, 200));
  span.addEvent('payment_validated');
  
  span.end();
  res.json({ orderId: Math.random().toString(36), status: 'created' });
});

Custom span memungkinkan Anda menambahkan attribute dan event yang berisi konteks domain, seperti tipe order atau ID pelanggan. Data ini sangat berharga saat debugging incident di production.

Langkah 5: Korelasi Log dengan Trace ID

Observability penuh tercapai ketika logs, metrics, dan traces saling terhubung. Tambahkan trace ID ke log output Anda agar bisa dicari di dashboard. Gunakan library seperti pino atau winston dengan formatter custom:

const { context, trace } = require('@opentelemetry/api');
const pino = require('pino');

const logger = pino({
  mixin() {
    const span = trace.getSpan(context.active());
    if (span) {
      const spanContext = span.spanContext();
      return { trace_id: spanContext.traceId, span_id: spanContext.spanId };
    }
    return {};
  },
});

Dengan trace ID di setiap log line, Anda bisa melakukan query di SigNoz: klik satu trace di Trace Detail, lalu lihat log terkait di tab Logs. Ini mempercepat root cause analysis secara drastis.

Langkah 6: Visualisasi dan Alerting di Dashboard SigNoz

Buka dashboard SigNoz di http://localhost:3301 dan navigasi ke menu Services. Anda akan melihat nodejs-demo-api muncul dengan latency, error rate, dan request per second (RPS). Klik nama service untuk melihat daftar trace. Pilih satu trace untuk melihat flame graph yang menunjukkan durasi setiap span.

Di menu Metrics, Anda dapat membuat dashboard custom untuk memantau throughput order atau latency health check. SigNoz juga mendukung alerting via Slack, PagerDuty, atau webhook. Aturan alert sederhana seperti error rate > 5% selama 5 menit sudah cukup untuk mendeteksi masalah dini.

Kesimpulan dan Rekomendasi Production

Observability bukan fitur yang ditambahkan di akhir siklus development. Ia harus menjadi bagian dari definition of done setiap task. Dengan OpenTelemetry dan SigNoz, Anda mendapatkan stack observability yang vendor-neutral, open source, dan kompatibel dengan ekosistem cloud native.

Untuk deployment production, pertimbangkan menggunakan OpenTelemetry Collector sebagai agregator buffer antara aplikasi dan SigNoz. Collector mendukung retry, batching, dan filtering data. Dokumentasi lengkap tersedia di OpenTelemetry Docs dan SigNoz Docs. Selamat mengobservasi sistem Anda dengan lebih baik.