@sneleentaxi/react-native-otel NPM

SET-Telemetry

Seamless OpenTelemetry Integration for Expo & React Native Applications

📦 Overview and Core Functionality

@SET-Telemetry offers a turnkey solution to instrument your Expo and React Native apps with OpenTelemetry. It provides automatic session management, dynamic OTLP endpoint configuration, optional console and OTLP-based logging, and built‑in support for mobile-specific quirks.

🚀 Getting Started: Basic Setup Using the useTracer Hook

Initialize the tracer inside your root component by invoking the useTracer hook:

import { useTracer } from '@SET-Telemetry';

export default function App() {
  const { loaded } = useTracer({
    traceExporterUrl: 'http://localhost:4318/v1/traces',
    sessionTimeoutMinutes: 15,
    enableConsoleLogs: true,
    logExporterUrl: 'http://localhost:4318/v1/logs',
  });

  if (!loaded) {
    return null; // or any placeholder while the tracer initializes
  }

  return (
    // ...your application tree
  );
}

⚙️ Configuration Options Explained

Both useTracer and the imperative Tracer function accept a configuration object with the following properties: | Option | Type | Default | Description | |----------------------|---------|----------------------------------------|--------------------------------------------------| | traceExporterUrl | string | http://localhost:4318/v1/traces | OTLP endpoint URL for exporting trace data | | sessionTimeoutMinutes| number | 15 | Duration (in minutes) to reuse the same session ID | | enableConsoleLogs | boolean | false | If true, logs are printed to the console exporter | | logExporterUrl | string | undefined | OTLP endpoint URL for exporting log records |

🔧 Advanced Initialization: Manual Tracer Setup

If you prefer full control or need to initialize tracing outside React components, call the Tracer function directly:

import { Tracer } from '@SET-Telemetry';

(async () => {
  await Tracer();
  // Tracer is now ready; you can start creating spans.
})();

📝 Detailed Feature Breakdown

Session Management and Span Enrichment
Automatic Session ID Generation: Persists a UUID in AsyncStorage and refreshes it after the configured timeout.
Span Attribute Injection: Every span is tagged with session.id, enabling session‑based trace grouping.
Offline Resilience and Caching
Batch Span Buffering: Spans are automatically batched and retried by the BatchSpanProcessor when network connectivity is restored.
Future Offline Persistence (Roadmap): Plans to extend AsyncStorage–based span caching for complete offline support.

🌐 Environment Variable Integration

For dynamic OTLP port configuration in Expo, add to your .env:

EXPO_PUBLIC_FRONTEND_PROXY_PORT=4318

Then reference it in your tracer config:

useTracer({
  traceExporterUrl: `http://localhost:${process.env.EXPO_PUBLIC_FRONTEND_PROXY_PORT}/otlp-http/v1/traces`,
});

📱 Example app.json Configuration

Ensure your app.json contains a valid name field; it automatically maps to the service.name attribute in your traces:

{
  "expo": {
    "name": "react-native-app",
    // ...other Expo settings
  }
}

🛠️ Development Workflow

Building for Publication Compile TypeScript to JavaScript and generate types:

npm run build

Running the Test Suite Execute unit tests to verify core functionality:

npm test

🤝 Contributing Guidelines

We welcome contributions! Please follow these steps:

Fork the repository.
Create a new branch for your feature or fix.
Commit your changes with clear messages.
Open a pull request describing your updates.

📄 License Information

Released under the MIT License. See the LICENSE file for full details.

Thank you for using @SET-Telemetry. Happy tracing!