@devfellowship/observability 2.0.1 → 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +144 -0
  2. package/package.json +3 -2
package/README.md ADDED
@@ -0,0 +1,144 @@
1
+ # @devfellowship/observability
2
+
3
+ Browser observability SDK for React apps. Provides OpenTelemetry tracing, metrics, Sentry error tracking, Web Vitals, fetch instrumentation, error boundaries, and React Query error reporting — all via a single provider wrapper.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install @devfellowship/observability
9
+ ```
10
+
11
+ ### Peer dependencies
12
+
13
+ - `react` >= 18
14
+ - `@tanstack/react-query` >= 5 (optional — enables automatic query error reporting)
15
+
16
+ ## Quick start
17
+
18
+ Wrap your app with `<ObservabilityProvider>`:
19
+
20
+ ```tsx
21
+ import { ObservabilityProvider } from "@devfellowship/observability";
22
+
23
+ function App() {
24
+ return (
25
+ <ObservabilityProvider>
26
+ <YourApp />
27
+ </ObservabilityProvider>
28
+ );
29
+ }
30
+ ```
31
+
32
+ With zero props, the provider reads configuration from Vite environment variables:
33
+
34
+ | Env var | Purpose |
35
+ |---------|---------|
36
+ | `VITE_APP_NAME` | Service name for traces/metrics |
37
+ | `VITE_APP_VERSION` | Service version |
38
+ | `VITE_OTEL_API_KEY` | API key sent as `x-api-key` header |
39
+ | `VITE_SENTRY_DSN` | Sentry DSN (enables error tracking + session replay) |
40
+ | `VITE_OTEL_ENABLED` | Set to `"true"` to enable (auto-enabled in production) |
41
+
42
+ ## Explicit configuration
43
+
44
+ All settings can be passed as props, overriding env vars:
45
+
46
+ ```tsx
47
+ <ObservabilityProvider
48
+ serviceName="my-app"
49
+ serviceVersion="1.2.0"
50
+ collectorUrl="https://otel.devfellowship.com"
51
+ apiKey="your-api-key"
52
+ sentryDsn="https://xxx@sentry.io/yyy"
53
+ environment="production"
54
+ enabled={true}
55
+ enableWebVitals={true}
56
+ enableQueryTracking={true}
57
+ enableFetchTracing={true}
58
+ >
59
+ <App />
60
+ </ObservabilityProvider>
61
+ ```
62
+
63
+ ### Props
64
+
65
+ | Prop | Type | Default | Description |
66
+ |------|------|---------|-------------|
67
+ | `serviceName` | `string` | `VITE_APP_NAME` or `"unknown"` | Service name for OTel resource |
68
+ | `serviceVersion` | `string` | `VITE_APP_VERSION` or `"0.0.0"` | Service version |
69
+ | `collectorUrl` | `string` | `"https://otel.devfellowship.com"` | OTel collector base URL |
70
+ | `apiKey` | `string` | `VITE_OTEL_API_KEY` | API key header value |
71
+ | `sentryDsn` | `string` | `VITE_SENTRY_DSN` | Sentry DSN (omit to disable Sentry) |
72
+ | `environment` | `string` | `"production"` / `"development"` | Environment label |
73
+ | `enabled` | `boolean` | `true` in production | Master kill-switch |
74
+ | `enableWebVitals` | `boolean` | `true` | Capture LCP, CLS, INP, TTFB |
75
+ | `enableQueryTracking` | `boolean` | `true` | Report React Query errors as spans |
76
+ | `enableFetchTracing` | `boolean` | `true` | Auto-trace all `fetch()` calls |
77
+
78
+ ## Utilities
79
+
80
+ ### Track custom events
81
+
82
+ ```ts
83
+ import { trackEvent } from "@devfellowship/observability";
84
+
85
+ trackEvent("button_click", { "button.id": "checkout", page: "/cart" });
86
+ ```
87
+
88
+ ### Set user context
89
+
90
+ ```ts
91
+ import { setUserId, setUserRole } from "@devfellowship/observability";
92
+
93
+ // After authentication
94
+ setUserId(user.id);
95
+ setUserRole(user.role);
96
+ ```
97
+
98
+ ### Sentry helpers
99
+
100
+ ```ts
101
+ import { captureError, setSentryUser } from "@devfellowship/observability";
102
+
103
+ captureError(new Error("something broke"), { component: "Checkout" });
104
+ setSentryUser(user.id, user.role);
105
+ ```
106
+
107
+ ### Error boundary
108
+
109
+ ```tsx
110
+ import { ErrorBoundary } from "@devfellowship/observability";
111
+
112
+ <ErrorBoundary fallback={<p>Something went wrong</p>}>
113
+ <RiskyComponent />
114
+ </ErrorBoundary>
115
+ ```
116
+
117
+ ## What's included
118
+
119
+ - **OTel traces** — `BatchSpanProcessor` → OTLP/HTTP exporter
120
+ - **OTel metrics** — `PeriodicExportingMetricReader` → OTLP/HTTP exporter
121
+ - **Fetch instrumentation** — auto-creates spans for all `fetch()` calls (collector URLs filtered)
122
+ - **Web Vitals** — LCP, CLS, INP, TTFB reported as OTel histogram metrics
123
+ - **Sentry** — error tracking, session replay (on-error), browser tracing
124
+ - **Error boundary** — catches React component errors, reports to both OTel and Sentry
125
+ - **React Query integration** — subscribes to query cache, creates error spans on failures
126
+ - **Resource attributes** — browser, OS, device type, session ID, viewport, connection type, route
127
+
128
+ ## Development
129
+
130
+ ```bash
131
+ npm install
132
+ npm run build # builds with tsup (ESM + .d.ts)
133
+ ```
134
+
135
+ ## Publishing
136
+
137
+ ```bash
138
+ npm version patch # or minor/major
139
+ npm publish
140
+ ```
141
+
142
+ ## License
143
+
144
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@devfellowship/observability",
3
- "version": "2.0.1",
3
+ "version": "2.0.2",
4
4
  "description": "Browser observability SDK — OpenTelemetry + Sentry for React apps",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -13,7 +13,8 @@
13
13
  }
14
14
  },
15
15
  "files": [
16
- "dist"
16
+ "dist",
17
+ "README.md"
17
18
  ],
18
19
  "scripts": {
19
20
  "build": "tsup",