@codr-echoteam/signoz-react-native

Kirim data tracing dari aplikasi React Native ke SigNoz menggunakan OpenTelemetry.

Instalasi

yarn add @codr-echoteam/signoz-react-native
# atau
npm install @codr-echoteam/signoz-react-native

Semua dependensi OpenTelemetry (@opentelemetry/api, @opentelemetry/core, @opentelemetry/exporter-trace-otlp-http, @opentelemetry/resources, @opentelemetry/sdk-trace-base) sudah termasuk sebagai dependency package ini sejak versi 0.3.0, sehingga tidak perlu di-install terpisah di project kamu.

Catatan: pada versi <= 0.2.0 paket OpenTelemetry di atas berstatus peerDependencies dan harus di-install manual oleh aplikasi host.

Cara Penggunaan

Inisialisasi Basic

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

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

Inisialisasi dengan Auto-Instrumentation (direkomendasikan)

import { initializeSignozWithAutoInstrumentation } from '@codr-echoteam/signoz-react-native';
import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';

function App() {
  const navigationRef = useNavigationContainerRef();

  useEffect(() => {
    initializeSignozWithAutoInstrumentation(
      { serviceName: 'my-app', url: 'https://your-otel-collector/v1/traces' },
      navigationRef,
    );
  }, []);

  return (
    <NavigationContainer ref={navigationRef}>
      {/* Komponen aplikasi Anda */}
    </NavigationContainer>
  );
}

Auto-instrumentasi mencakup:

• Tracing navigasi React Navigation (screen focus, blur, state change)
• Tracing lifecycle events aplikasi (AppState change)
• Global error & unhandled promise rejection logging

Mencatat Event

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

logEvent('UserLogin', { userId: '12345', method: 'google' });

Mencatat Error

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

try {
  await someRiskyOperation();
} catch (error) {
  logError(error, { context: 'PaymentProcess' });
}

Tracing Axios HTTP Requests

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

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

// Semua request/response otomatis di-trace
api.get('/users');

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

initializeSignozTracing(config)

Inisialisasi tracing (exporter + provider + propagator). Hanya url yang benar-benar wajib; jika url kosong, tracing otomatis dinonaktifkan (semua fungsi menjadi no-op). Field lain punya nilai default.

interface SignOzConfig {
  serviceName: string;              // Nama service (default: 'rn-app')
  url: string;                      // URL OTLP collector (wajib)
  serviceVersion?: string;          // Versi aplikasi
  environment?: string;             // development / staging / production
  serviceNamespace?: string;        // Namespace service
  headers?: Record<string, string>; // Header tambahan
  traceSampleRate?: number;         // Sampling rate 0-1 (default: 1.0)
  batchSpanProcessorConfig?: {
    maxQueueSize?: number;          // Default: 10
    scheduledDelayMillis?: number;  // Default: 500
    exportTimeoutMillis?: number;   // Default: 10000
  };
}

initializeSignozWithAutoInstrumentation(config, navigationRef?)

Inisialisasi dengan auto-instrumentasi. Parameter navigationRef opsional untuk tracing React Navigation. Ekuivalen dengan memanggil initializeSignozTracing(config) → setNavigationRef(navigationRef) (bila ada) → setupAutoInstrumentation().

setupAutoInstrumentation()

Aktifkan auto-instrumentasi secara manual (tanpa lewat initializeSignozWithAutoInstrumentation). Mencakup:

• Global error handler (setupGlobalErrorHandler())
• Listener lifecycle aplikasi (AppState change → span app.lifecycle)
• Listener navigasi bila navigationRef sudah di-set (atau tersedia via global.RN_NAVIGATION_REF)

Berguna bila kamu memanggil initializeSignozTracing() sendiri dan ingin mengaktifkan auto-instrumentasi terpisah.

setNavigationRef(ref)

Daftarkan navigation container ref agar perubahan navigasi ter-trace otomatis (span navigation.state_change, navigation.screen_focus, navigation.screen_blur, navigation.screen_remove). Berguna untuk pola inisialisasi awal + registrasi ref belakangan (mis. di NavigationContainer#onReady):

import {
  initializeSignozTracing,
  setupAutoInstrumentation,
  setNavigationRef,
} from '@codr-echoteam/signoz-react-native';
import { createNavigationContainerRef, NavigationContainer } from '@react-navigation/native';

const navigationRef = createNavigationContainerRef();

// Inisialisasi lebih awal (mis. saat modul App di-load)
initializeSignozTracing({ serviceName: 'my-app', url: 'https://collector/v1/traces' });
setupAutoInstrumentation();

function App() {
  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => setNavigationRef(navigationRef)}
    >
      {/* ... */}
    </NavigationContainer>
  );
}

ref cukup punya addListener(event, cb) dan (opsional) getCurrentRoute() — kompatibel dengan hasil createNavigationContainerRef() / useNavigationContainerRef() dari React Navigation.

navigationRef

Variabel yang menyimpan navigation ref terakhir yang di-set lewat setNavigationRef(). Bernilai null sebelum di-set. Umumnya kamu tidak perlu mengaksesnya langsung.

logEvent(name, attributes?)

Catat custom event sebagai span. Aman dipanggil sebelum tracing diinisialisasi (menjadi no-op).

logError(error, attributes?)

Catat error sebagai span dengan status ERROR. Aman dipanggil sebelum tracing diinisialisasi (menjadi no-op).

Internal: error.stack tidak dikirim sebagai attribute span (direduksi oleh recordException untuk menghindari duplikasi data).

setupGlobalErrorHandler()

Hook error global (ErrorUtils + unhandledrejection) untuk logging error aplikasi ke Signoz. Dipanggil otomatis oleh setupAutoInstrumentation().

setupAxiosTracing(axiosInstance, options?)

Pasang tracing pada instance Axios. Span akan mencatat method, URL, dan status code.

Noise reduction: HTTP 4xx tidak ditandai sebagai ERROR span. Status ERROR hanya untuk 5xx, network errors, dan timeout (ECONNABORTED). Ini mencegah 401/404/429 membanjiri dashboard.

forceFlush()

Paksa flush semua span yang masih dalam antrian ke collector. Berguna sebelum app masuk background.

shutdown()

Matikan tracer dan lepaskan resource. Setelah dipanggil, span baru tidak akan dikirim.

Error Handling

Semua fungsi publik (logEvent, logError, createSpan internal) memiliki try/catch internal. Error di internal tracing tidak akan memutus flow aplikasi atau melempar exception ke caller.

Hot-Reload Safety

Listener navigasi, AppState, dan unhandledrejection akan dibersihkan dan didaftarkan ulang setiap kali initializeSignozTracing() atau setupAutoInstrumentation() dipanggil. Tidak ada duplikasi listener saat Fast Refresh / hot-reload.

Konfigurasi Lengkap

initializeSignozWithAutoInstrumentation(
  {
    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,
    },
  },
  navigationRef,
);

Catatan Penting

• Konfigurasi wajib: url (bila kosong, tracing dinonaktifkan). serviceName sangat direkomendasikan (default 'rn-app')
• Sampling: Atur traceSampleRate < 1 untuk mengurangi volume data
• Batch tuning: Sesuaikan batchSpanProcessorConfig bila perlu menyeimbangkan latensi vs throughput
• Dependencies: Hanya pakai @opentelemetry/exporter-trace-otlp-http — tidak ada dependensi protobuf

License

MIT