---
title: "Tutorial Observability Modern: Instrumentasi Node.js dengan OpenTelemetry dan SigNoz"
description: "Panduan lengkap mengimplementasikan OpenTelemetry dan SigNoz untuk observability aplikasi Node.js. Monitoring trace, metric, dan log dalam satu dashboard."
author: "Axel W"
author_url: https://devmode.id/axelw
url: https://devmode.id/axelw/tutorial-observability-nodejs-opentelemetry-0zkt
published: 2026-08-05T05:05:00.000Z
updated: 2026-08-05T05:05:00.000Z
language: id
tags: ["node-js", "devops", "tutorial", "docker"]
publisher: "DEVMODE Community"
---

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

Oleh [Axel W](https://devmode.id/axelw) · 2026-08-05

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](https://github.com/SigNoz/signoz) 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](https://opentelemetry.io/docs/) dan [SigNoz Docs](https://signoz.io/docs/). Selamat mengobservasi sistem Anda dengan lebih baik.

---

Sumber: https://devmode.id/axelw/tutorial-observability-nodejs-opentelemetry-0zkt (DEVMODE Community)