@echoteam/signoz-react/README.md

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

# @echoteam/signoz-react

Library React untuk monitoring dan tracing aplikasi menggunakan OpenTelemetry dan SignOz.

## 🚀 Fitur

- **Tracing Otomatis**: Integrasi OpenTelemetry untuk tracing HTTP requests, fetch, dan XMLHttpRequest
- **Error Boundary**: Komponen React untuk menangkap dan melaporkan error dengan tracing
- **Error Page**: Halaman error untuk React Router dengan integrasi tracing
- **TypeScript Support**: Dukungan penuh untuk TypeScript
- **Zero Configuration**: Mudah digunakan dengan environment variables
- **Customizable**: ErrorPage dan ErrorBoundary dapat dikustomisasi sesuai kebutuhan

## 📚 Dokumentasi

- [Konfigurasi CORS Backend](./BACKEND_CORS_SETUP.md) - Panduan lengkap setup CORS di berbagai framework backend
- [Troubleshooting](./TROUBLESHOOTING.md) - Solusi untuk masalah umum
- [OpenTelemetry Documentation](https://opentelemetry.io/docs/)
- [React Error Boundary](https://reactjs.org/docs/error-boundaries.html)

## 📦 Instalasi

```bash
yarn add @echoteam/signoz-react
npm install @echoteam/signoz-react
```

## 🔧 Konfigurasi

### Environment Variables

Tambahkan environment variables berikut ke file `.env`:

```env
REACT_APP_SIGNOZ_SERVICE_NAME=my-react-app
REACT_APP_SIGNOZ_SERVICE_VERSION=1.0.0
REACT_APP_SIGNOZ_ENV=production
REACT_APP_SIGNOZ_SERVICE_NAMESPACE=frontend
REACT_APP_SIGNOZ_URL=https://your-signoz-instance.com/v1/traces
REACT_APP_SIGNOZ_TRACE_SAMPLE_RATE=1.0
REACT_APP_SIGNOZ_ALLOWED_ORIGINS=https://api1.example.com,https://api2.example.com,/^https:\/\/.*\.your-domain\.com$/
```

> **Catatan untuk REACT_APP_SIGNOZ_ALLOWED_ORIGINS:**
> - Daftar URL yang diizinkan untuk CORS, dipisahkan dengan koma
> - Untuk RegExp pattern, gunakan format `/pattern/` (contoh: `/^https:\/\/.*\.example\.com$/`)
> - Jika tidak diisi, default ke semua origin (`/.+/g`)
> - Spasi di sekitar koma akan dihapus otomatis

### Inisialisasi

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

// Inisialisasi dengan environment variables
initializeSignOzTracing();

// Atau dengan konfigurasi manual
// Inisialisasi dengan konfigurasi minimal
initializeSignOzTracing({
  serviceName: 'my-app',
  serviceVersion: '1.0.0',
  environment: 'production',
  serviceNamespace: 'default',
  url: 'https://api.signoz.io/v1/traces'
});

// Inisialisasi dengan konfigurasi lengkap
initializeSignOzTracing({
  serviceName: 'my-app',
  serviceVersion: '1.0.0',
  environment: 'production',
  serviceNamespace: 'default',
  url: 'https://api.signoz.io/v1/traces',
  headers: {
    'X-API-Key': 'your-api-key'
  },
  traceSampleRate: 0.5, // Sampling 50% trace
  batchSpanProcessorConfig: {
    maxQueueSize: 100,
    scheduledDelayMillis: 5000,
    exportTimeoutMillis: 30000
  },
  allowedOrigins: [
    'https://api.example.com',
    /^https:\/\/.*\.your-domain\.com$/
  ]
});
```

## 🎯 Penggunaan

### Error Boundary

#### Penggunaan Dasar
```tsx
import { ErrorBoundary } from '@echoteam/signoz-react';

function App() {
  return (
    <ErrorBoundary>
      <YourApp />
    </ErrorBoundary>
  );
}
```

#### Error Boundary dengan Kustomisasi
```tsx
import { ErrorBoundary, ErrorBoundaryProps } from '@echoteam/signoz-react';

// Custom fallback component
const CustomErrorFallback: React.FC<{ error: Error; resetErrorBoundary: () => void }> = ({ 
  error, 
  resetErrorBoundary 
}) => (
  <div className="custom-error">
    <h2>Terjadi Kesalahan!</h2>
    <p>{error.message}</p>
    <button onClick={resetErrorBoundary}>Coba Lagi</button>
  </div>
);

function App() {
  const handleError = (error: Error, errorInfo: React.ErrorInfo) => {
    console.log('Error caught:', error);
    // Kirim ke service lain jika diperlukan
  };

  return (
    <ErrorBoundary
      fallback={CustomErrorFallback}
      onError={handleError}
      onReset={() => console.log('Error boundary reset')}
      fallbackClassName="my-error-boundary"
    >
      <YourApp />
    </ErrorBoundary>
  );
}
```

### Error Page untuk React Router

#### Penggunaan Dasar
```tsx
import { ErrorPage } from '@echoteam/signoz-react';
import { createBrowserRouter } from 'react-router-dom';

const router = createBrowserRouter([
  {
    path: "/",
    element: <Root />,
    errorElement: <ErrorPage />,
  },
]);
```

#### Error Page dengan Kustomisasi
```tsx
import { ErrorPage, ErrorPageProps } from '@echoteam/signoz-react';

// Custom error page
const CustomErrorPage: React.FC<ErrorPageProps> = (props) => (
  <ErrorPage
    title="Halaman Tidak Ditemukan"
    message="Maaf, halaman yang Anda cari tidak tersedia."
    showStackTrace={process.env.NODE_ENV === 'development'}
    actionButton={
      <button onClick={() => window.history.back()}>
        Kembali ke Halaman Sebelumnya
      </button>
    }
    className="custom-error-page"
  />
);

// Atau dengan custom render function
const CustomErrorPageWithRender: React.FC<ErrorPageProps> = () => (
  <ErrorPage
    renderError={(error) => (
      <div className="my-custom-error">
        <h1>🚨 Error!</h1>
        <p>Kode Error: {error.name}</p>
        <p>Pesan: {error.message}</p>
        <button onClick={() => window.location.href = '/'}>
          Kembali ke Beranda
        </button>
      </div>
    )}
  />
);

const router = createBrowserRouter([
  {
    path: "/",
    element: <Root />,
    errorElement: <CustomErrorPage />,
  },
]);
```

### Tracing Manual

```typescript
import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('my-service');
const span = tracer.startSpan('my-operation');

try {
  // Lakukan operasi
  span.setAttribute('operation.type', 'database-query');
  span.setAttribute('operation.result', 'success');
} catch (error) {
  span.recordException(error);
  span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
} finally {
  span.end();
}
```

## 📋 API Reference

### `initializeSignOzTracing(config?)`

Inisialisasi SignOz tracing untuk aplikasi React.

**Parameter:**
- `config` (opsional): Konfigurasi SignOz
  - `serviceName`: Nama layanan
  - `serviceVersion`: Versi layanan
  - `environment`: Environment (production, staging, development)
  - `serviceNamespace`: Namespace layanan
  - `url`: URL endpoint SignOz
  - `headers` (opsional): Header tambahan untuk request
  - `traceSampleRate` (opsional): Rate sampling trace (0-1, default: 1.0)
  - `batchSpanProcessorConfig` (opsional): Konfigurasi batch processor
    - `maxQueueSize`: Ukuran maksimum antrian span
    - `scheduledDelayMillis`: Delay pengiriman batch dalam milidetik
    - `exportTimeoutMillis`: Timeout ekspor dalam milidetik
  - `allowedOrigins` (opsional): Array URL/RegExp yang diizinkan untuk CORS

### `ErrorBoundary`

Komponen React untuk menangkap error dan melaporkan ke SignOz.

**Props:**
- `children`: React children
- `fallback`: Custom fallback component
- `onError`: Custom error handler function
- `onReset`: Custom reset handler
- `showResetButton`: Apakah menampilkan reset button (default: true)
- `resetButtonText`: Custom reset button text
- `fallbackClassName`: Custom CSS class untuk fallback

### `ErrorPage`

Komponen halaman error untuk React Router.

**Props:**
- `title`: Judul halaman error (default: "Oops!")
- `message`: Pesan error utama (default: "Terjadi kesalahan yang tidak terduga.")
- `renderError`: Custom render function untuk menampilkan error
- `className`: Custom CSS class untuk container
- `showStackTrace`: Apakah menampilkan stack trace (default: false)
- `actionButton`: Custom action button

## 🔍 Monitoring

Setelah setup, Anda dapat melihat traces di dashboard SignOz:

1. **Service Overview**: Melihat performa layanan secara keseluruhan
2. **Traces**: Melihat detail traces untuk setiap request
3. **Errors**: Melihat error yang terjadi dengan stack trace
4. **Metrics**: Melihat metrics performa aplikasi

## 🚨 Troubleshooting

### Error: Can't resolve 'perf_hooks'

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'
```

**Solusi:**
Library ini sudah diperbaiki untuk menangani masalah ini. Pastikan Anda menggunakan versi terbaru:

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

Jika masih mengalami masalah, lihat [TROUBLESHOOTING.md](TROUBLESHOOTING.md) untuk solusi lengkap berdasarkan bundler yang Anda gunakan (Webpack, Vite, Create React App).

### Masalah Umum Lainnya

1. **Environment Variables Tidak Terdeteksi**: Pastikan semua environment variables sudah dikonfigurasi dengan benar
2. **CORS Error**: Pastikan URL SignOz dapat diakses dari domain aplikasi Anda
3. **Network Error**: Periksa koneksi internet dan firewall settings

Untuk informasi troubleshooting lebih lengkap, lihat [TROUBLESHOOTING.md](TROUBLESHOOTING.md).

## 🛠️ Development

### Setup Development

```bash
# Clone repository
git clone https://gitlab.echoteam.tech/codr/package/signoz-react-js.git
cd signoz-react-js

# Install dependencies
yarn install

# Build package
yarn build

# Development mode
yarn dev
```
### Scripts

- `yarn build`: Build package untuk production
- `yarn dev`: Build dalam mode development dengan watch
- `yarn test`: Jalankan tests
- `yarn lint`: Lint kode
- `yarn format`: Format kode dengan Prettier

## 📄 License

MIT License - lihat file [LICENSE](LICENSE) untuk detail.

## 🤝 Contributing

1. Fork repository
2. Buat feature branch (`git checkout -b feature/amazing-feature`)
3. Commit perubahan (`git commit -m 'Add amazing feature'`)
4. Push ke branch (`git push origin feature/amazing-feature`)
5. Buat Pull Request

## 📞 Support

- **Issues**: [GitLab Issues](https://gitlab.echoteam.tech/codr/package/signoz-react-js/-/issues)
- **Email**: dev@codr.id
- **Documentation**: [GitLab Wiki](https://gitlab.echoteam.tech/codr/package/signoz-react-js/-/wikis)

## 🔗 Links

- [SignOz Documentation](https://signoz.io/docs/)
- [OpenTelemetry Documentation](https://opentelemetry.io/docs/)
- [React Error Boundary](https://reactjs.org/docs/error-boundaries.html)