The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
feat: skill update
ddux911fa4c5e19f
diff --git a/skills/traceway-setup/SKILL.md b/skills/traceway-setup/SKILL.mdindex 8ca2bedf..104762fc 100644--- a/skills/traceway-setup/SKILL.md+++ b/skills/traceway-setup/SKILL.md@@ -239,13 +239,13 @@ Frontend and mobile projects do NOT use OTel; they use the Traceway SDKs reporti2. **Bundler plugin**: `npm install -D @tracewayapp/bundler-plugin`, then add `tracewayDebugIds()` from `@tracewayapp/bundler-plugin/vite` (or `/rollup`, or `TracewayDebugIdsWebpackPlugin` from `/webpack`) to the bundler config, with source maps enabled (`build.sourcemap: true` / `devtool: "source-map"`).3. **Source map upload**: `npm install -D @tracewayapp/sourcemap-upload`, then run `traceway-sourcemaps --url <instance> --token <source-map-upload-token> --directory ./dist` as a postbuild or CI step (env vars: `TRACEWAY_URL`, `TRACEWAY_SOURCEMAP_TOKEN`). The upload token comes from Step 0 and is a CI secret, never committed.-Full docs: https://docs.tracewayapp.com/client/react (or `vue`, `svelte`, `jquery`, `js-sdk`).+For the per-framework init code (plain JS, React, Vue, Svelte/SvelteKit, jQuery), the shared SDK options, error filtering, custom attributes, distributed tracing, and the full debug-ID + source map pipeline, read `frontend-js.md` in this skill directory. Online docs: https://docs.tracewayapp.com/client/react (or `vue`, `svelte`, `jquery`, `js-sdk`).**Full-stack JS** (Next.js, SvelteKit, Remix): both sides. Server side follows Step 2 (verify `http.route` grouping; set it manually in a server hook where the auto-instrumentation does not know the router). Browser side follows the three pieces above.**Mobile**, always the platform SDK, never OTel:-- **Flutter**: `flutter pub add traceway`, then `Traceway.run(connectionString: '<token>@https://<instance>/api/report', child: MyApp())`. Docs: https://docs.tracewayapp.com/client/flutter+- **Flutter**: `flutter pub add traceway`, then `Traceway.run(connectionString: '<token>@https://<instance>/api/report', child: MyApp())`. For options, platform permissions, the navigator observer, screen recording, privacy masking, and the Flutter web caveat, read `flutter.md` in this skill directory. Docs: https://docs.tracewayapp.com/client/flutter- **React Native**: `npm install @tracewayapp/react-native`, wrap the app in `TracewayProvider`. Docs: https://docs.tracewayapp.com/client/react-native- **Android**: `implementation("com.tracewayapp:traceway:<version>")`, call `Traceway.init(...)` at startup. Docs: https://docs.tracewayapp.com/client/androiddiff --git a/skills/traceway-setup/flutter.md b/skills/traceway-setup/flutter.mdnew file mode 100644index 00000000..df945b72--- /dev/null+++ b/skills/traceway-setup/flutter.md@@ -0,0 +1,142 @@+# Flutter SDK Reference++The Traceway Flutter SDK is the [`traceway`](https://pub.dev/packages/traceway) package on pub.dev. It supports iOS, Android, and macOS. It does NOT support Flutter web (see the bottom of this file).++## Setup++```bash+flutter pub add traceway+```++Wrap the app in `Traceway.run()`:++```dart+import 'package:flutter/material.dart';+import 'package:traceway/traceway.dart';++void main() {+ Traceway.run(+ connectionString: 'your-token@https://traceway.example.com/api/report',+ options: TracewayOptions(+ screenCapture: true,+ version: '1.0.0',+ ),+ child: MyApp(),+ );+}+```++This automatically captures Flutter framework errors (`FlutterError.onError`), native platform channel errors, and uncaught async errors (via Dart's `Zone` mechanism).++Wire the navigator observer so navigation transitions are recorded:++```dart+MaterialApp(+ navigatorObservers: [Traceway.navigatorObserver],+ home: const HomePage(),+);+```++## Manual capture++```dart+try {+ await riskyOperation();+} catch (e, st) {+ TracewayClient.instance?.captureException(e, st);+}++TracewayClient.instance?.captureMessage('User completed onboarding');+```++## Options (`TracewayOptions`)++| Option | Type | Default | Description |+|--------|------|---------|-------------|+| `sampleRate` | `double` | `1.0` | Event sampling rate (0.0 to 1.0) |+| `screenCapture` | `bool` | `false` | Records the last ~10 seconds of screen as video |+| `debug` | `bool` | `false` | Prints debug info to the console |+| `version` | `String` | `''` | App version string |+| `debounceMs` | `int` | `1500` | Milliseconds before sending batched events |+| `capturePixelRatio` | `double` | `0.75` | Screenshot resolution scale |+| `maxBufferFrames` | `int` | `150` | Max frames in recording buffer (~10s at 15fps) |+| `fps` | `int` | `15` | Frames per second for screen capture (1 to 59) |+| `retryDelayMs` | `int` | `10000` | Retry delay in ms on failed uploads |+| `maxPendingExceptions` | `int` | `5` | Max exceptions held in memory before oldest is dropped |+| `persistToDisk` | `bool` | `true` | Persist pending exceptions to disk across app restarts |+| `maxLocalFiles` | `int` | `5` | Max exception files stored on disk |+| `localFileMaxAgeHours` | `int` | `12` | Hours after which unsynced local files are deleted |+| `captureLogs` | `bool` | `true` | Mirror every `print` / `debugPrint` into the rolling log buffer |+| `captureNetwork` | `bool` | `true` | Install `HttpOverrides.global` to record every dart:io HTTP call |+| `captureNavigation` | `bool` | `true` | Record transitions reported by `Traceway.navigatorObserver` |+| `eventsWindow` | `Duration` | `10s` | Rolling window kept in the log/action buffers |+| `eventsMaxCount` | `int` | `200` | Hard cap applied independently to logs and actions |++## Platform permissions++- **Android**: add the `INTERNET` permission to `android/app/src/main/AndroidManifest.xml`:+ ```xml+ <uses-permission android:name="android.permission.INTERNET"/>+ ```+- **macOS**: sandboxed by default; add `com.apple.security.network.client` (value `<true/>`) to BOTH `macos/Runner/DebugProfile.entitlements` and `macos/Runner/Release.entitlements`.+- **iOS**: nothing needed.++## Screen recording++With `screenCapture: true`, the SDK wraps the app in a `RepaintBoundary`, captures frames at ~15 fps, and on exception encodes the last ~10 seconds to MP4 and sends it with the report. Touch positions are rendered as blue circles on the captured frames only; the live app is unaffected.++Mask sensitive content with `TracewayPrivacyMask` (applies to recorded frames only):++```dart+TracewayPrivacyMask(+ child: Text('4242 4242 4242 4242'),+)++TracewayPrivacyMask(+ mode: TracewayMaskMode.blur(ratio: 0.5),+ child: CreditCardWidget(),+)++TracewayPrivacyMask(+ mode: TracewayMaskMode.blank(color: Color(0xFF000000)),+ child: SensitiveDataWidget(),+)+```++## Logs and actions++Every captured exception ships with the last ~10 seconds of context from two rolling buffers (200 entries each by default):++- **Logs**: every `print` / `debugPrint` line, mirrored via a Zone print override. `dart:developer.log` is NOT captured.+- **Network actions**: every dart:io HTTP request (method, URL, status, duration, byte counts) via `HttpOverrides.global`, which catches `package:http`, Dio, Firebase, and anything else on the dart:io HttpClient.+- **Navigation actions**: push / pop / replace / remove, from `Traceway.navigatorObserver`.+- **Custom actions**:+ ```dart+ Traceway.recordAction(+ category: 'cart',+ name: 'add_item',+ data: {'sku': 'SKU-123', 'qty': 2},+ );+ ```++## Flutter web++The Flutter SDK does not support web (no error tracking, no screen recording there). For Flutter web apps, use the JS SDK in `web/index.html` instead:++```html+<script src="https://cdn.jsdelivr.net/npm/@tracewayapp/frontend@1/dist/traceway.iife.global.js"></script>+<script>+ Traceway.init("your-token@https://traceway.example.com/api/report");+</script>+```++For network capture in Dart code on web (where `HttpOverrides.global` does not run), `TracewayHttpClient` is a drop-in `http.Client`, usable directly or passed to libraries that accept a custom client (Dio, Chopper):++```dart+final client = TracewayHttpClient();+final res = await client.get(Uri.parse('https://api.example.com/users'));+```++## Verify++Add a button that throws (`throw StateError('Test error from Traceway')`), tap it, and check the Issues page in the dashboard. With `screenCapture: true`, the recording appears alongside the stack trace.diff --git a/skills/traceway-setup/frontend-js.md b/skills/traceway-setup/frontend-js.mdnew file mode 100644index 00000000..39a4a14c--- /dev/null+++ b/skills/traceway-setup/frontend-js.md@@ -0,0 +1,280 @@+# JS Frontend SDKs Reference++Browser-side setup for every supported framework, plus the bundler plugin and source map upload that complete each integration. The connection string everywhere is `<project-token>@https://<instance>/api/report`.++## Packages++| Package | Use for |+|---|---|+| `@tracewayapp/frontend` | Plain JS, vanilla apps, frameworks without official bindings |+| `@tracewayapp/react` | React: provider, error boundary, hooks |+| `@tracewayapp/vue` | Vue 3: plugin and composables |+| `@tracewayapp/svelte` | Svelte and SvelteKit: context-based setup |+| `@tracewayapp/jquery` | jQuery: automatic AJAX error capture |++All framework packages wrap the core SDK and accept the same options object (see Options below). Every SDK captures uncaught errors and unhandled promise rejections, batches uploads with retry, and ships session replay: the last ~30s of DOM events (rrweb) accompany every captured exception by default.++## Plain JS (`@tracewayapp/frontend`)++```javascript+import { init, captureException, captureMessage } from "@tracewayapp/frontend";++init("your-token@https://traceway.example.com/api/report");++try {+ riskyOperation();+} catch (error) {+ captureException(error);+}++captureMessage("User completed checkout");+```++Via CDN (exposes `window.Traceway`, no build step):++```html+<script src="https://cdn.jsdelivr.net/npm/@tracewayapp/frontend@1/dist/traceway.iife.global.js"></script>+<script>+ Traceway.init("your-token@https://traceway.example.com/api/report");+</script>+```++## React (`@tracewayapp/react`)++Wrap the app in `TracewayProvider`. It doubles as an error boundary: render-time exceptions anywhere in the tree are captured and re-thrown, so app behavior is unchanged. `TracewayErrorBoundary` is still exported for the case where a crashed subtree should show a fallback UI instead of propagating; it is not required for capture.++```jsx+import { TracewayProvider } from "@tracewayapp/react";++function App() {+ return (+ <TracewayProvider connectionString="your-token@https://traceway.example.com/api/report">+ <YourApp />+ </TracewayProvider>+ );+}+```++Manual capture uses the `useTraceway` hook:++```jsx+import { useTraceway } from "@tracewayapp/react";++function MyComponent() {+ const { captureException } = useTraceway();++ async function handleSubmit() {+ try {+ await submitForm();+ } catch (error) {+ captureException(error);+ }+ }+}+```++Options go on the provider: `<TracewayProvider connectionString="..." options={{ debug: true, version: "1.0.0" }}>`.++## Vue 3 (`@tracewayapp/vue`)++The plugin installs a global error handler for uncaught errors:++```javascript+import { createApp } from "vue";+import { createTracewayPlugin } from "@tracewayapp/vue";+import App from "./App.vue";++const app = createApp(App);+app.use(createTracewayPlugin({+ connectionString: "your-token@https://traceway.example.com/api/report",+ options: { version: "1.0.0" },+}));+app.mount("#app");+```++Manual capture uses the `useTraceway` composable:++```vue+<script setup>+import { useTraceway } from "@tracewayapp/vue";+const { captureException } = useTraceway();+</script>+```++## Svelte / SvelteKit (`@tracewayapp/svelte`)++Call `setupTraceway` in the root layout. The `if (browser)` guard keeps the rrweb recorder out of the SSR bundle:++```svelte+<!-- src/routes/+layout.svelte -->+<script>+ import { setupTraceway } from "@tracewayapp/svelte";+ import { browser } from "$app/environment";++ if (browser) {+ setupTraceway({+ connectionString: "your-token@https://traceway.example.com/api/report",+ });+ }+</script>++<slot />+```++For a non-SvelteKit Svelte app, drop the guard and the `$app/environment` import. Manual capture in child components uses `getTraceway()`:++```svelte+<script>+ import { getTraceway } from "@tracewayapp/svelte";+ const { captureException } = getTraceway();+</script>+```++## jQuery (`@tracewayapp/jquery`)++```javascript+import { init, captureException } from "@tracewayapp/jquery";++init("your-token@https://cloud.tracewayapp.com/api/report");+```++Via CDN (exposes `window.TracewayJQuery`):++```html+<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>+<script src="https://cdn.jsdelivr.net/npm/@tracewayapp/jquery@1/dist/traceway-jquery.iife.global.js"></script>+<script>+ TracewayJQuery.init("your-token@https://cloud.tracewayapp.com/api/report");+</script>+```++Beyond the standard capture, the jQuery SDK hooks `$(document).ajaxError()` to capture failed `$.ajax()` calls (URL, method, status, message) and injects trace headers into `$.ajax()` (XHR) as well as `fetch`.++## Options (shared by all JS SDKs)++| Option | Type | Default | Description |+|--------|------|---------|-------------|+| `debug` | `boolean` | `false` | Log captured events to the browser console |+| `debounceMs` | `number` | `1500` | Batch delay in milliseconds |+| `retryDelayMs` | `number` | `10000` | Retry delay for failed uploads |+| `version` | `string` | `undefined` | App version, shown on exceptions for filtering by build (unrelated to source maps) |+| `ignoreErrors` | `Array<string \| RegExp>` | default patterns | Error patterns to ignore; pass `[]` to capture everything |+| `beforeCapture` | `(exception) => boolean` | `undefined` | Return `false` to suppress an error |+| `sessionRecording` | `boolean` | `true` | rrweb session recorder |+| `sessionRecordingSegmentDuration` | `number` | `30000` | rrweb segment length in ms |+| `recordAllSessions` | `boolean` | `false` | Always-on session recording instead of error-triggered |+| `captureLogs` | `boolean` | `true` | Mirror `console.*` calls into the rolling log buffer |+| `captureNetwork` | `boolean` | `true` | Record `fetch` / XHR calls as network actions |+| `captureNavigation` | `boolean` | `true` | Record History API transitions |++### Error filtering++By default 4xx HTTP errors, network errors, and timeouts are NOT captured. Opt in with `ignoreErrors: []`, and filter selectively with `beforeCapture`:++```javascript+init("your-token@https://<instance>/api/report", {+ ignoreErrors: [],+ beforeCapture: (exception) => {+ const status = Number(exception.attributes?.status);+ if (status >= 400 && status < 500) return false;+ return true;+ },+});+```++### Custom attributes++Attach app-level identifiers to every session and exception. Layering on each event: defaults < global scope < per-call.++```javascript+import { setAttribute, setAttributes, clearAttributes } from "@tracewayapp/jquery";++setAttribute("userId", "u_42");+setAttributes({ tenant: "acme", plan: "pro" });+clearAttributes();+```++(Same exports from each framework package.)++### Distributed tracing++The SDK instruments `fetch` (and XHR in the jQuery SDK) to propagate a `traceway-trace-id` header on same-origin requests, linking frontend errors to the backend requests that caused them. No configuration. For Axios:++```javascript+import { createAxiosInterceptor } from "@tracewayapp/frontend";++api.interceptors.request.use(createAxiosInterceptor());+```++## Bundler Plugin (debug IDs)++`@tracewayapp/bundler-plugin` embeds a deterministic 128-bit debug ID into each emitted chunk and its `.map` (ECMA-426 debug ID format, interoperable with Sentry tooling). The backend then matches stack frames to the exact map from the same build, immune to filename collisions and concurrent deploys. Without it, matching falls back to filename (fine with content-hashed bundle names, broken with stable names like `app.js`).++```bash+npm install -D @tracewayapp/bundler-plugin+```++Vite:++```ts+import { tracewayDebugIds } from "@tracewayapp/bundler-plugin/vite";++export default defineConfig({+ build: { sourcemap: true },+ plugins: [tracewayDebugIds()],+});+```++Rollup: same import from `@tracewayapp/bundler-plugin/rollup`, with `output: { sourcemap: true }`.++webpack (requires webpack 5):++```js+const { TracewayDebugIdsWebpackPlugin } = require("@tracewayapp/bundler-plugin/webpack");++module.exports = {+ devtool: "source-map",+ plugins: [new TracewayDebugIdsWebpackPlugin()],+};+```++esbuild is not covered; bundles processed by Sentry's esbuild plugin still work (the SDK reads `_sentryDebugIds` too), otherwise esbuild falls back to filename matching.++## Source Map Upload++Uploads authenticate with a dedicated upload token (Connection page > Source Maps > Generate Upload Token), NOT the project token. It is a CI secret; never commit it. `readonly` members cannot generate one.++```bash+npm install -D @tracewayapp/sourcemap-upload++traceway-sourcemaps --url https://<instance> --token <upload-token> --directory ./dist+```++Env vars `TRACEWAY_URL` and `TRACEWAY_SOURCEMAP_TOKEN` replace the flags. The CLI uploads all `*.map` files plus the sibling `.js`/`.cjs`/`.mjs` bundles (the bundle is what enables function-name resolution). Limit: 50 MB per file. Uploads take effect immediately.++Wire it as a postbuild script:++```json+{+ "scripts": {+ "build": "vite build",+ "postbuild": "traceway-sourcemaps --directory ./dist"+ }+}+```++Or as a CI step after build:++```yaml+- name: Upload source maps+ run: npx traceway-sourcemaps --directory ./dist+ env:+ TRACEWAY_URL: ${{ secrets.TRACEWAY_URL }}+ TRACEWAY_SOURCEMAP_TOKEN: ${{ secrets.TRACEWAY_SOURCEMAP_TOKEN }}+```++Self-hosted instances must have blob storage (S3 or a persistent volume) configured, or uploaded maps disappear when the container is recreated.++## Verify++Trigger a test error (`captureException(new Error("Test error"))` behind a button) and check the Issues page: the error appears, and with the bundler plugin plus upload in place the stack trace resolves to original files and lines.