@echoteam/signoz-react/TROUBLESHOOTING.md

SignOz React JS - Library untuk monitoring dan tracing aplikasi React menggunakan OpenTelemetry dan SignOz

# Troubleshooting Guide

## Error: Timeout from BatchSpanProcessor

### Masalah
Jika Anda mendapatkan error seperti ini di console:
```
Unhandled Promise rejection: Timeout ; Zone: <root> ; Task: Promise.then ; Value: Error: Timeout
at BatchSpanProcessorBase.js:132:1
```

### Penyebab
Error ini terjadi ketika BatchSpanProcessor mencoba mengirim spans ke backend SignOz tetapi mengalami timeout. Ini biasanya terjadi karena:
1. Backend SignOz tidak dapat dijangkau
2. Network lambat atau tidak stabil
3. CORS tidak dikonfigurasi dengan benar di backend
4. Timeout terlalu pendek untuk koneksi Anda

### Solusi

#### 1. Verifikasi Backend SignOz Dapat Dijangkau
Pastikan URL SignOz Anda benar dan dapat diakses dari browser:
```javascript
// Test di browser console
fetch('http://your-signoz-url:4318/v1/traces', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' }
})
```

#### 2. Periksa CORS Configuration
Pastikan backend SignOz Anda mengizinkan request dari domain frontend Anda. Lihat [BACKEND_CORS_SETUP.md](./BACKEND_CORS_SETUP.md) untuk panduan lengkap.

#### 3. Tingkatkan Timeout (Recommended)
Sejak versi 1.2.10, timeout default sudah ditingkatkan menjadi 60 detik. Jika masih timeout, Anda bisa meningkatkannya lebih lanjut:

```javascript
import { initializeSignOzTracing } from '@echoteam/signoz-react';

initializeSignOzTracing({
  serviceName: 'my-app',
  serviceVersion: '1.0.0',
  environment: 'production',
  serviceNamespace: 'frontend',
  url: 'http://your-signoz-url:4318/v1/traces',
  batchSpanProcessorConfig: {
    maxQueueSize: 100,
    scheduledDelayMillis: 5000,
    exportTimeoutMillis: 120000, // 120 seconds
    maxExportBatchSize: 50
  }
});
```

#### 4. Suppress Timeout Errors (Jika Tidak Mengganggu)
Sejak versi 1.2.10, timeout errors dari BatchSpanProcessor secara otomatis di-suppress untuk menghindari noise di console. Error ini biasanya aman untuk diabaikan karena spans akan di-retry atau di-queue ulang.

Jika Anda ingin melihat warning untuk timeout ini, aktifkan console logging:
```javascript
initializeSignOzTracing({
  // ... config lainnya
  enableConsoleLog: true
});
```

#### 5. Gunakan Network yang Lebih Stabil
Jika Anda mengalami timeout secara konsisten, pertimbangkan:
- Menggunakan koneksi internet yang lebih stabil
- Mengurangi ukuran batch dengan `maxExportBatchSize`
- Meningkatkan `scheduledDelayMillis` untuk mengirim spans lebih jarang

### Catatan Penting
- Timeout errors biasanya tidak mempengaruhi fungsionalitas aplikasi Anda
- Spans yang gagal dikirim akan di-queue ulang dan dicoba lagi
- Jika backend SignOz tidak dapat dijangkau sama sekali, spans akan di-drop setelah queue penuh

---

## Error: Can't resolve 'perf_hooks'

### Masalah
Jika Anda mendapatkan error seperti ini:
```
ERROR in ./node_modules/@echoteam/signoz-react/dist/index.esm.js 1:0-58
Module not found: Error: Can't resolve 'perf_hooks' in '/path/to/node_modules/@echoteam/signoz-react/dist'
```

### Penyebab
Error ini terjadi karena library OpenTelemetry mencoba mengimpor modul Node.js (`perf_hooks`) yang tidak tersedia di browser. Library ini dirancang untuk berjalan di browser, bukan di Node.js.

### Solusi

#### 1. Pastikan menggunakan versi terbaru
Library ini sudah diperbaiki untuk menangani masalah ini. Pastikan Anda menggunakan versi terbaru:

```bash
yarn add @echoteam/signoz-react@latest
```

#### 2. Konfigurasi Webpack (jika menggunakan Webpack)
Tambahkan konfigurasi berikut di `webpack.config.js`:

```javascript
module.exports = {
  // ... konfigurasi lainnya
  resolve: {
    fallback: {
      "perf_hooks": false,
      "fs": false,
      "path": false,
      "os": false,
      "crypto": false,
      "stream": false,
      "util": false,
      "events": false,
      "assert": false,
      "buffer": false,
      "querystring": false,
      "url": false,
      "http": false,
      "https": false,
      "zlib": false,
      "tty": false,
      "domain": false,
      "dns": false,
      "dgram": false,
      "child_process": false,
      "cluster": false,
      "module": false,
      "net": false,
      "readline": false,
      "repl": false,
      "string_decoder": false,
      "sys": false,
      "timers": false,
      "tls": false,
      "v8": false,
      "vm": false,
      "worker_threads": false
    }
  }
};
```

#### 3. Konfigurasi Vite (jika menggunakan Vite)
Tambahkan konfigurasi berikut di `vite.config.js`:

```javascript
import { defineConfig } from 'vite';

export default defineConfig({
  // ... konfigurasi lainnya
  define: {
    global: 'globalThis',
  },
  resolve: {
    alias: {
      'perf_hooks': false,
      'fs': false,
      'path': false,
      'os': false,
      'crypto': false,
      'stream': false,
      'util': false,
      'events': false,
      'assert': false,
      'buffer': false,
      'querystring': false,
      'url': false,
      'http': false,
      'https': false,
      'zlib': false,
      'tty': false,
      'domain': false,
      'dns': false,
      'dgram': false,
      'child_process': false,
      'cluster': false,
      'module': false,
      'net': false,
      'readline': false,
      'repl': false,
      'string_decoder': false,
      'sys': false,
      'timers': false,
      'tls': false,
      'v8': false,
      'vm': false,
      'worker_threads': false
    }
  }
});
```

#### 4. Konfigurasi Create React App
Jika menggunakan Create React App, Anda mungkin perlu menggunakan `react-app-rewired` untuk mengoverride konfigurasi webpack:

1. Install react-app-rewired:
```bash
yarn add --dev react-app-rewired
```

2. Buat file `config-overrides.js` di root proyek:
```javascript
module.exports = function override(config, env) {
  config.resolve.fallback = {
    ...config.resolve.fallback,
    "perf_hooks": false,
    "fs": false,
    "path": false,
    "os": false,
    "crypto": false,
    "stream": false,
    "util": false,
    "events": false,
    "assert": false,
    "buffer": false,
    "querystring": false,
    "url": false,
    "http": false,
    "https": false,
    "zlib": false,
    "tty": false,
    "domain": false,
    "dns": false,
    "dgram": false,
    "child_process": false,
    "cluster": false,
    "module": false,
    "net": false,
    "readline": false,
    "repl": false,
    "string_decoder": false,
    "sys": false,
    "timers": false,
    "tls": false,
    "v8": false,
    "vm": false,
    "worker_threads": false
  };
  return config;
};
```

3. Update script di `package.json`:
```json
{
  "scripts": {
    "start": "react-app-rewired start",
    "build": "react-app-rewired build",
    "test": "react-app-rewired test"
  }
}
```

### Catatan Penting
- Library ini dirancang untuk berjalan di browser, bukan di Node.js
- Polyfill sudah disertakan untuk menangani modul Node.js yang tidak tersedia di browser
- Pastikan environment variables untuk SignOz sudah dikonfigurasi dengan benar

### Masalah Lainnya
Jika Anda masih mengalami masalah, silakan buat issue di repository ini dengan detail error yang lengkap.