npm package: @sneleentaxi/react-native-otel
Description: Comprehensive OpenTelemetry integration for React Native and Expo, including route tracing, session management, and dynamic OTLP configuration.
Author: sneleentaxi
Latest version: 0.1.1

 # 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:

```typescript
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:

```typescript
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:
```bash
EXPO_PUBLIC_FRONTEND_PROXY_PORT=4318
```

Then reference it in your tracer config:
```typescript
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:

```json
{
  "expo": {
    "name": "react-native-app",
    // ...other Expo settings
  }
}
```
## 🛠️ Development Workflow

Building for Publication
Compile TypeScript to JavaScript and generate types:

```bash
npm run build
```

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

```bash
npm test
```
## 🤝 Contributing Guidelines

We welcome contributions! Please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or fix.
3. Commit your changes with clear messages.
4. 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!