https://github.com/makomweb/otel-sdk-react
Instrument your JavaScript application to provide traces following W3C reccommendations for propagating context.
https://github.com/makomweb/otel-sdk-react
javascript library npm open-source public typescript
Last synced: 2 months ago
JSON representation
Instrument your JavaScript application to provide traces following W3C reccommendations for propagating context.
- Host: GitHub
- URL: https://github.com/makomweb/otel-sdk-react
- Owner: makomweb
- License: mit
- Created: 2026-04-07T11:41:25.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2026-04-07T15:20:58.000Z (3 months ago)
- Last Synced: 2026-04-07T15:22:55.562Z (3 months ago)
- Topics: javascript, library, npm, open-source, public, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@makomweb/otel-sdk-react
- Size: 64.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# otel-sdk-react
Setup your JavaScript application to propagate context. This way your OpenTelemetry enabled application is able to "connect" traces between various services.
## Features
- **Web Trace Provider** - Distributed tracing with OTLP HTTP exporter
- **Metrics** - Application metrics with OTLP HTTP exporter
- **Logs** - Structured logging with OTLP HTTP exporter
- **Document Load Instrumentation** - Automatic page load tracing
- **Fetch Instrumentation** - Optional: Trace HTTP requests with W3C Trace Context propagation
- **TypeScript** - Full type safety (strict mode)
- **Lightweight** - Minimal dependencies, tree-shakeable
## Installation
```bash
npm install @makomweb/otel-sdk-react
```
**Peer dependencies** (should already be in your project):
```json
{
"react": ">=18.0.0",
"@opentelemetry/api": ">=1.7.0",
"@opentelemetry/sdk-trace-web": ">=1.17.0",
"@opentelemetry/sdk-metrics": ">=1.17.0",
"@opentelemetry/sdk-logs": ">=0.50.0",
"@opentelemetry/exporter-trace-otlp-http": ">=0.43.0",
"@opentelemetry/exporter-metrics-otlp-http": ">=0.43.0",
"@opentelemetry/exporter-logs-otlp-http": ">=0.50.0",
"@opentelemetry/instrumentation": ">=0.43.0",
"@opentelemetry/instrumentation-fetch": ">=0.51.0",
"@opentelemetry/instrumentation-document-load": ">=0.33.0"
}
```
## API Reference
### `setupOTelSDK(collectorAddress: string)`
Initialize OTEL SDK with Trace, Metric, and Log providers + Document Load instrumentation.
```typescript
import { setupOTelSDK } from '@makomweb/otel-sdk-react';
setupOTelSDK('http://localhost:4318');
```
### `setupFetchInstrumentation(backendUrl: string)`
Trace HTTP requests with W3C Trace Context propagation to your backend.
```typescript
import { setupFetchInstrumentation } from '@makomweb/otel-sdk-react';
setupFetchInstrumentation('http://api.example.com');
```
## Usage
### Basic Setup
In your `main.tsx` or `main.jsx`:
```typescript
import React from 'react';
import ReactDOM from 'react-dom/client';
import { setupOTelSDK, setupFetchInstrumentation } from '@makomweb/otel-sdk-react';
import App from './App';
// Initialize OTEL (required, before React renders)
setupOTelSDK('http://localhost:4318');
// Optional: enable fetch tracing
setupFetchInstrumentation('http://localhost:8081');
const root = ReactDOM.createRoot(document.getElementById('root')!);
root.render(
,
);
```
### With Environment Variables
Create `.env.local`:
```bash
VITE_OTEL_COLLECTOR_ADDRESS=http://localhost:4318
VITE_BACKEND_API_URL=http://localhost:8081
```
Then in `main.tsx`:
```typescript
setupOTelSDK(import.meta.env.VITE_OTEL_COLLECTOR_ADDRESS);
setupFetchInstrumentation(import.meta.env.VITE_BACKEND_API_URL);
```
### Advanced: Config Module
For larger applications, organize configuration separately:
```typescript
// config.ts
export function getConfig() {
return {
otelCollectorAddress: import.meta.env.VITE_OTEL_COLLECTOR_ADDRESS || 'http://localhost:4318',
apiUrl: import.meta.env.VITE_BACKEND_API_URL || 'http://localhost:8081',
};
}
```
```typescript
// main.tsx
import { setupOTelSDK, setupFetchInstrumentation } from '@makomweb/otel-sdk-react';
import { getConfig } from './config';
const config = getConfig();
setupOTelSDK(config.otelCollectorAddress);
setupFetchInstrumentation(config.apiUrl);
```
## Troubleshooting
### Spans not appearing in collector?
1. **Verify setupOTelSDK() is called before React renders** (must be first in main.tsx)
2. **Check collector is running**: `curl http://localhost:4318/v1/traces -X POST`
3. **Check network in DevTools**: Look for requests to `/v1/traces` endpoint
### FetchInstrumentation not tracing requests?
1. **Verify setupFetchInstrumentation(backendUrl) is called**
2. **Check backendUrl matches your API domain**
3. **Check CORS headers**: Collector must accept cross-origin requests
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md)