@codr-echoteam/signoz-react-native

Kirim data error tracking dari aplikasi React Native ke SigNoz menggunakan OpenTelemetry.

Instalasi

npm install @codr-echoteam/signoz-react-native

Peer Dependencies

Library ini memerlukan peer dependencies berikut (semua opsional):

npm install axios    # hanya jika menggunakan HTTP tracing
npm install react    # hanya jika menggunakan <SignozErrorBoundary>

Quick Start

Cukup satu panggilan untuk mengaktifkan semua error tracking:

import { initializeSignoz } from '@codr-echoteam/signoz-react-native';
import axios from 'axios';

const api = axios.create({ baseURL: 'https://api.example.com' });

initializeSignoz({
  serviceName: 'my-app',
  url: 'https://your-otel-collector/v1/traces',
  axiosInstance: api, // opsional — otomatis track HTTP errors
});

Setelah panggilan ini, otomatis tercatat:

• ✅ Uncaught errors (via React Native ErrorUtils)
• ✅ Unhandled promise rejections
• ✅ HTTP 5xx, network errors, dan timeout (jika axiosInstance diberikan)
• ✅ React component render errors (via <SignozErrorBoundary> — setup manual)
• ✅ Filter: hanya kirim error saja dengan errorsOnly: true
• ✅ Filter: abaikan URL tertentu dengan ignoreUrls

Cara Penggunaan

Minimal (tanpa HTTP tracing)

import { initializeSignoz } from '@codr-echoteam/signoz-react-native';

initializeSignoz({
  serviceName: 'my-app',
  url: 'https://your-otel-collector/v1/traces',
});

Dengan multiple Axios instances

import { initializeSignoz } from '@codr-echoteam/signoz-react-native';
import axios from 'axios';

const publicApi = axios.create({ baseURL: 'https://api.example.com' });
const adminApi = axios.create({ baseURL: 'https://admin.example.com' });

initializeSignoz({
  serviceName: 'my-app',
  url: 'https://your-otel-collector/v1/traces',
  axiosInstance: [publicApi, adminApi], // array juga supported
});

Mencatat Error Manual

import { logError } from '@codr-echoteam/signoz-react-native';

try {
  await someRiskyOperation();
} catch (error) {
  logError(error instanceof Error ? error : new Error(String(error)), {
    context: 'PaymentProcess',
    userId: '12345',
  });
}

Error Boundary (React Component)

Tangkap render errors di komponen React dan otomatis kirim ke SigNoz:

import { SignozErrorBoundary } from '@codr-echoteam/signoz-react-native';

<SignozErrorBoundary>
  <MyScreen />
</SignozErrorBoundary>;

Dengan fallback UI dan retry:

import { SignozErrorBoundary } from '@codr-echoteam/signoz-react-native';
import { View, Text, Button } from 'react-native';

<SignozErrorBoundary
  fallback={({ error, resetError }) => (
    <View>
      <Text>Terjadi error: {error.message}</Text>
      <Button title="Coba Lagi" onPress={resetError} />
    </View>
  )}
  onError={(error, info) => console.log('caught:', error)}
  attributes={{ 'screen.name': 'HomeScreen' }}
>
  <MyScreen />
</SignozErrorBoundary>;

Setup Axios Terpisah (alternatif)

Jika perlu menambah axios tracing setelah init, atau ingin custom span name:

import { setupAxiosTracing } from '@codr-echoteam/signoz-react-native';
import axios from 'axios';

const api = axios.create({ baseURL: 'https://api.example.com' });
setupAxiosTracing(api, { name: 'PaymentAPI' });

Hanya Kirim Error ke SigNoz (errorsOnly)

Jika ingin menghemat bandwidth dan hanya mengirim span dari request yang gagal:

initializeSignoz({
  serviceName: 'my-app',
  url: 'https://your-otel-collector/v1/traces',
  axiosInstance: api,
  errorsOnly: true, // request sukses (2xx) tidak dikirim ke SigNoz
});

Mengecualikan URL Tertentu dari Tracing (ignoreUrls)

URL tertentu bisa diabaikan sepenuhnya — tidak ada span yang dibuat, baik sukses maupun error:

initializeSignoz({
  serviceName: 'my-app',
  url: 'https://your-otel-collector/v1/traces',
  axiosInstance: api,
  ignoreUrls: [
    'events/trackers',        // string — cocok jika URL mengandung text ini
    /\/v1\/traces$/,          // RegExp — cocok jika URL match pattern
    'health-check',
  ],
});

Kombinasi keduanya juga bisa:

initializeSignoz({
  serviceName: 'my-app',
  url: 'https://your-otel-collector/v1/traces',
  axiosInstance: api,
  errorsOnly: true,                          // hanya error yang dikirim
  ignoreUrls: ['events/trackers'],           // URL ini sepenuhnya diabaikan
});

Flush & Shutdown

import { forceFlush, shutdown } from '@codr-echoteam/signoz-react-native';

// Paksa kirim span yang antri sebelum app masuk background
await forceFlush();

// Matikan tracer (span baru setelah ini tidak akan dikirim)
await shutdown();

API Reference

initializeSignoz(config)

Satu panggilan untuk setup lengkap:

1. Inisialisasi OpenTelemetry tracer provider (OTLP HTTP exporter)
2. Setup global error handler (uncaught errors + unhandled promise rejections)
3. Setup axios HTTP tracing (jika axiosInstance diberikan)

interface SignOzConfig {
  serviceName: string; // Nama service (default: 'rn-app')
  url: string; // URL OTLP collector (wajib)
  serviceVersion?: string; // Versi aplikasi (default: '1.0.0')
  environment?: string; // development / staging / production
  serviceNamespace?: string; // Namespace service
  headers?: Record<string, string>; // Header tambahan untuk collector
  traceSampleRate?: number; // Sampling rate 0-1 (default: 1.0)
  batchSpanProcessorConfig?: {
    maxQueueSize?: number; // Default: 10
    scheduledDelayMillis?: number; // Default: 500
    exportTimeoutMillis?: number; // Default: 10000
  };
  axiosInstance?: AxiosInstance | AxiosInstance[]; // Instance axios untuk auto-trace
  axiosSpanName?: string; // Custom span name untuk HTTP traces
  errorsOnly?: boolean; // Hanya kirim error spans (default: false)
  ignoreUrls?: (string | RegExp)[]; // URL patterns yang diabaikan dari tracing
}

initializeSignozTracing(config)

Inisialisasi tracing saja (tanpa error handler dan tanpa axios). Berguna jika ingin kontrol granular.

setupGlobalErrorHandler()

Hook error global React Native. Dipanggil otomatis oleh initializeSignoz().

logError(error, attributes?)

Catat error sebagai span dengan status ERROR. Aman dipanggil kapan saja (no-op jika tracing belum diinisialisasi).

setupAxiosTracing(axiosInstance, options?)

Pasang tracing pada instance Axios secara manual. Dipanggil otomatis oleh initializeSignoz() jika axiosInstance diberikan.

Options:

• name — Custom span name
• errorsOnly — Hanya kirim span error (default: false)
• ignoreUrls — URL patterns yang diabaikan (string atau RegExp)

Noise reduction: HTTP 4xx tidak ditandai sebagai ERROR. Hanya 5xx, network errors, dan timeout yang menghasilkan ERROR span.

<SignozErrorBoundary>

React Error Boundary yang otomatis report render errors ke SigNoz.

Props:

• children — Child components
• fallback — ReactNode atau render function ({ error, resetError }) => ReactNode
• onError — Callback (error: Error, errorInfo: React.ErrorInfo) => void
• attributes — Custom attributes tambahan untuk error span (Record<string, string | number | boolean>)

Span yang dihasilkan memiliki attributes:

• error.type: 'react-error-boundary'
• error.componentStack — React component stack trace
• Semua custom attributes dari prop attributes

forceFlush() / shutdown()

Flush antrian span / matikan tracer.

Konfigurasi Lengkap

import { initializeSignoz } from '@codr-echoteam/signoz-react-native';
import axios from 'axios';

const api = axios.create({ baseURL: 'https://api.example.com' });

initializeSignoz({
  serviceName: 'my-app',
  serviceVersion: '1.2.3',
  environment: 'production',
  url: 'https://your-otel-collector/v1/traces',
  headers: { Authorization: 'Bearer token' },
  traceSampleRate: 1.0,
  batchSpanProcessorConfig: {
    maxQueueSize: 200,
    scheduledDelayMillis: 3000,
    exportTimeoutMillis: 15000,
  },
  axiosInstance: api,
  axiosSpanName: 'MyApp HTTP',
  errorsOnly: true, // hanya error yang dikirim
  ignoreUrls: ['events/trackers', /\/health$/], // URL yang diabaikan
});

Cukup satu panggilan — semua error tracking aktif.

Error Handling & Safety

• Semua fungsi publik memiliki try/catch internal — error di tracing tidak akan crash aplikasi
• Jika url tidak di-set, semua fungsi menjadi no-op (graceful degradation)
• Hot-reload safe: handler dibersihkan dan didaftarkan ulang tanpa duplikasi

Catatan Penting

• Wajib: url — jika kosong, tracing dinonaktifkan
• Direkomendasikan: serviceName (default 'rn-app')
• Sampling: Atur traceSampleRate < 1 untuk mengurangi volume data di production
• Hanya error: Library ini sengaja hanya track errors & HTTP failures untuk menjaga dashboard SigNoz tetap bersih

Troubleshooting

Self-hosted: 404 pada endpoint collector

iOS NSURLSession kadang menambahkan trailing slash (/v1/traces/ bukan /v1/traces). Fix di config collector:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
        traces_url_path: /v1/traces/

SigNoz Cloud sudah handle ini otomatis.

SigNoz Cloud

Gunakan header signoz-ingestion-key:

initializeSignoz({
  serviceName: 'my-app',
  url: 'https://ingest.<region>.signoz.cloud:443/v1/traces',
  headers: {
    'signoz-ingestion-key': '<your-ingestion-key>',
  },
});

Metro cache issues

Jika app crash saat startup setelah install:

npx react-native start --reset-cache

OpenTelemetry version conflicts

Pastikan tidak ada duplicate @opentelemetry/api:

npm ls @opentelemetry/api

Harus hanya ada satu versi yang ter-resolve.

License

MIT