@codr-echoteam/signoz-react-native

Package ini memungkinkan Anda untuk mengintegrasikan fitur tracing dan monitoring menggunakan SigNoz dalam aplikasi React Native Anda. Dengan menggunakan OpenTelemetry sebagai standar observability, package ini membantu Anda memantau kinerja aplikasi dan mendeteksi masalah dengan lebih efektif.

Fitur Utama

• 🚀 Auto-instrumentation untuk React Navigation
• 📊 Tracing otomatis untuk HTTP requests menggunakan Axios
• 🔍 Pencatatan error dan events secara detail
• ⚡ Performa yang optimal dengan batch processing
• 🛠️ Konfigurasi yang fleksibel dan mudah

Instalasi

Jalankan perintah berikut di terminal pada direktori proyek React Native Anda:

# Menggunakan yarn
yarn add @codr-echoteam/signoz-react-native

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

Cara Penggunaan

Inisialisasi

Ada dua cara untuk menginisialisasi tracing:

Cara 1: Inisialisasi Basic

initializeSignozTracing({
  serviceName: 'nama-aplikasi', // Ganti dengan nama service aplikasi Anda
  url: 'https://server-otel-collector/v1/traces', // Ganti dengan URL collector OpenTelemetry Anda
});

Cara 2: Inisialisasi dengan Auto-Instrumentation (Direkomendasikan)

Untuk React Navigation dan fitur auto-instrumentation lainnya, gunakan cara ini di file entrypoint aplikasi Anda:

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

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

  useEffect(() => {
    // Inisialisasi dengan auto-instrumentation
    initializeSignozWithAutoInstrumentation(
      {
        serviceName: 'nama-aplikasi',
        url: 'https://server-otel-collector/v1/traces',
        environment: 'production'
      },
      navigationRef // Pass navigation reference untuk tracking otomatis
    );
  }, []);

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

Dengan menggunakan initializeSignozWithAutoInstrumentation, Anda mendapatkan:

• Tracing otomatis untuk navigasi (screen views, route changes)
• Tracing otomatis untuk lifecycle events aplikasi
• Setup yang lebih mudah dengan satu fungsi

3. Setelah inisialisasi (dengan cara manapun), Anda dapat menggunakan fungsi-fungsi berikut untuk mencatat aktivitas aplikasi:e ini digunakan untuk mengirim data tracing dari aplikasi React Native Anda ke Signoz menggunakan OpenTelemetry. Dengan package ini, Anda dapat dengan mudah memantau kinerja aplikasi dan mendeteksi masalah dengan cepat.

Cara Instalasi

Jalankan perintah berikut di terminal pada direktori proyek React Native Anda:

yarn add @codr-echoteam/signoz-react-native

atau jika Anda menggunakan npm:

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

Cara Penggunaan

1. Import fungsi-fungsi yang diperlukan dari package:

import {
  initializeSignozTracing,
  logEvent,
  logError,
  setupAxiosTracing,
  traceFunctionAsync
} from '@codr-echoteam/signoz-react-native';

2. Inisialisasi tracing dengan memanggil fungsi initializeSignozTracing dan masukkan konfigurasi yang sesuai:

initializeSignozTracing({
  serviceName: 'my-app', // Ganti dengan nama service aplikasi Anda
  url: 'https://my-otel-collector/v1/traces', // Ganti dengan URL collector OpenTelemetry Anda
});

3. Setelah inisialisasi, Anda dapat menggunakan fungsi lain seperti logEvent, logError, setupAxiosTracing, dan traceFunctionAsync untuk mencatat event, error, dan tracing pada aplikasi Anda.

Mencatat Event dengan logEvent

logEvent('UserLogin', {
  userId: '12345',
  method: 'google',
  timestamp: new Date().toISOString()
});

Mencatat Error dengan logError

try {
  // kode yang mungkin error
  throw new Error('Gagal mengambil data');
} catch (error) {
  logError(error, {
    context: 'LoginProcess',
    userId: '12345',
    timestamp: new Date().toISOString()
  });
}

API Reference

initializeSignozTracing(config)

Fungsi untuk inisialisasi dasar tanpa auto-instrumentation.

interface SignozConfig {
  serviceName: string;              // Nama service aplikasi (wajib)
  url: string;                      // URL collector OpenTelemetry (wajib)
  serviceVersion?: string;          // Versi aplikasi
  environment?: string;             // Lingkungan aplikasi
  serviceNamespace?: string;        // Namespace service
  headers?: Record<string, string>; // Header tambahan untuk OTLP collector
  traceSampleRate?: number;         // Rate sampling (0-1)
}

initializeSignozWithAutoInstrumentation(config, navigationRef?)

Fungsi untuk inisialisasi dengan fitur auto-instrumentation.

logEvent(eventName: string, attributes?: Record<string, any>)

Mencatat custom event dengan atribut tambahan.

logError(error: Error, attributes?: Record<string, any>)

Mencatat error dengan konteks tambahan.

setupAxiosTracing(axiosInstance, options?)

Mengaktifkan tracing otomatis untuk instance Axios.

traceFunctionAsync<T>(name: string, fn: () => Promise<T>, attributes?)

Membungkus fungsi async dengan tracing otomatis.

Konfigurasi Lengkap

Berikut adalah contoh konfigurasi lengkap yang bisa digunakan baik dengan initializeSignozTracing maupun initializeSignozWithAutoInstrumentation:

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

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

  useEffect(() => {
    initializeSignozWithAutoInstrumentation(
      {
        // Konfigurasi dasar
        serviceName: 'nama-aplikasi-anda',    // Nama service aplikasi Anda
        serviceVersion: '1.2.3',              // Versi aplikasi
        environment: 'production',            // Lingkungan aplikasi (development, staging, production)
        serviceNamespace: 'mobile',           // Namespace service (opsional)

        // Konfigurasi endpoint
        url: 'https://server-otel/v1/traces', // URL collector OpenTelemetry
        headers: {                            // Header tambahan untuk OTLP collector (opsional)
          'Authorization': 'Bearer token-anda'
        },

        // Konfigurasi tracing
        traceSampleRate: 1,                   // Rate sampling trace (0-1), default 1 (semua trace)

        // Konfigurasi batch processor (opsional)
        batchSpanProcessorConfig: {
          maxQueueSize: 200,                  // Jumlah maksimum antrian span
          scheduledDelayMillis: 3000,         // Jeda pengiriman batch (ms)
          exportTimeoutMillis: 15000          // Batas waktu ekspor (ms)
        }
      },
      navigationRef  // Reference untuk React Navigation (opsional)
    );
  }, []);

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

Contoh Penggunaan setupAxiosTracing

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

// Buat instance axios
const apiClient = axios.create({
  baseURL: 'https://api.example.com',
  timeout: 10000,
});

// Aktifkan tracing untuk instance axios
setupAxiosTracing(apiClient, {
  name: 'MainAPI' // Nama untuk span (opsional)
});

// Semua request/response akan otomatis di-trace
apiClient.get('/users')
  .then(response => {
    console.log('Users data:', response.data);
  })

Contoh Penggunaan traceFunctionAsync

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

// Fungsi async yang akan di-trace
async function fetchUserData(userId: string) {
  const response = await fetch(`https://api.example.com/users/${userId}`);
  const userData = await response.json();
  return userData;
}

// Cara 1: Menggunakan fungsi yang sudah di-trace
const tracedFetchUser = traceFunctionAsync(
  'fetchUserData',        // Nama span
  fetchUserData,          // Fungsi yang akan di-trace
  { type: 'user' }        // Atribut tambahan (opsional)
);

// Panggil fungsi yang sudah di-trace
try {
  const userData = await tracedFetchUser('123');
  console.log('User data:', userData);
} catch (error) {
  console.error('Error fetching data:', error);
}

// Cara 2: Trace langsung pada fungsi
const result = await traceFunctionAsync(
  'processData',
  async () => {
    // Kode yang ingin di-trace
    const data = await fetchFromServer();
    return processData(data);
  },
  { operation: 'data-processing' }
);

Best Practices

1. Penggunaan Environment

// Buat file konfigurasi terpisah
// config/signoz.ts
export const signozConfig = {
  serviceName: env.SIGNOZ_SERVICE_NAME,
  url: env.SIGNOZ_OTEL_URL,
  environment: env.NODE_ENV,
  serviceVersion: env.APP_VERSION
};

2. Error Handling

try {
  await someRiskyOperation();
} catch (error) {
  logError(error, {
    operation: 'someRiskyOperation',
    context: 'PaymentProcess',
    userId: currentUser.id,
    // Tambahkan informasi yang membantu debugging
    payload: JSON.stringify(requestPayload)
  });
  // Handle error sesuai kebutuhan
}

3. Custom Event

// Catat event penting dengan detail yang relevan
logEvent('OrderCompleted', {
  orderId: order.id,
  total: order.total,
  paymentMethod: order.paymentMethod,
  items: order.items.length,
  // Informasi tambahan yang berguna untuk analisis
  userType: user.type,
  region: user.region
});

4. Tracing untuk Operasi Kompleks

const processOrder = traceFunctionAsync(
  'OrderProcessor',
  async (orderData) => {
    // Langkah 1: Validasi
    await validateOrder(orderData);

    // Langkah 2: Proses pembayaran
    const payment = await processPayment(orderData.payment);

    // Langkah 3: Update inventory
    await updateInventory(orderData.items);

    return { success: true, orderId: orderData.id };
  },
  {
    type: 'order-processing',
    priority: 'high'
  }
);

Catatan Penting

1. Konfigurasi Wajib:

   • serviceName: Nama unik untuk aplikasi Anda
   • url: Endpoint OpenTelemetry collector

2. Environment Variables:

   • SIGNOZ_SERVICE_NAME
   • SIGNOZ_OTEL_URL
   • SIGNOZ_SERVICE_VERSION
   • SIGNOZ_ENVIRONMENT

3. Fitur Auto-Instrumentation:

   • Tracing otomatis untuk navigasi React Navigation
   • Tracing untuk HTTP request/response dengan Axios
   • Pencatatan error otomatis
   • Lifecycle events aplikasi

4. Tips Optimasi:

   • Gunakan traceSampleRate untuk mengontrol volume data
   • Manfaatkan batch processing untuk efisiensi
   • Tambahkan atribut yang relevan untuk analisis
   • Kelompokkan trace yang berkaitan dengan span yang tepat

Troubleshooting

1. Data Tidak Terkirim

   • Periksa koneksi ke collector
   • Pastikan URL collector benar
   • Cek konfigurasi headers jika diperlukan

2. Performa Lambat

   • Sesuaikan batchSpanProcessorConfig
   • Optimalkan jumlah atribut yang dikirim
   • Gunakan sampling rate yang sesuai

3. Memory Issues

   • Batasi ukuran queue dengan maxQueueSize
   • Atur scheduledDelayMillis yang sesuai
   • Monitor penggunaan memori aplikasi

License

MIT

Untuk informasi lebih lanjut, kunjungi:

• Dokumentasi SigNoz
• OpenTelemetry untuk JavaScript
• React Native Performance Monitoring