The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
updated docs to include otel, source maps and session replay info, fixed topbar behavior
dduxdc3328865ee9
diff --git a/docs/components/FrameworkPicker.jsx b/docs/components/FrameworkPicker.jsxindex be484eb0..f2b57603 100644--- a/docs/components/FrameworkPicker.jsx+++ b/docs/components/FrameworkPicker.jsx@@ -104,6 +104,14 @@ const FRAMEWORKS = [href: "/client/js-sdk",badge: "new",},+ {+ value: "otel",+ label: "OpenTelemetry",+ description: "Send traces and metrics from any OTel-instrumented app to Traceway.",+ icon: "/otel.png",+ href: "/client/otel",+ badge: "new",+ },];export default function FrameworkPicker() {diff --git a/docs/components/SdkContext.jsx b/docs/components/SdkContext.jsxindex da8d57fb..d549b239 100644--- a/docs/components/SdkContext.jsx+++ b/docs/components/SdkContext.jsx@@ -14,6 +14,7 @@ export const SDK_OPTIONS = [{ value: 'js-vue', label: 'Vue.js' },{ value: 'js-svelte', label: 'Svelte' },{ value: 'js-generic', label: 'JS Generic' },+ { value: 'otel', label: 'OpenTelemetry' },]const STORAGE_KEY = 'traceway-docs-sdk'@@ -30,7 +31,7 @@ const PATH_SDK_MAP = {'react': 'js-react','vue': 'js-vue','svelte': 'js-svelte',- 'js-sdk': 'js-generic',+ 'otel': 'otel',}const SdkContext = createContext({diff --git a/docs/components/SdkSelector.jsx b/docs/components/SdkSelector.jsxindex 113f489e..9b6d0fa4 100644--- a/docs/components/SdkSelector.jsx+++ b/docs/components/SdkSelector.jsx@@ -15,6 +15,7 @@ const SDK_QUICK_START = {'js-vue': '/client/vue','js-svelte': '/client/svelte','js-generic': '/client/js-sdk',+ 'otel': '/client/otel',}export default function SdkSelector() {diff --git a/docs/pages/client/_meta.json b/docs/pages/client/_meta.jsonindex ee7a41f5..0860addc 100644--- a/docs/pages/client/_meta.json+++ b/docs/pages/client/_meta.json@@ -16,5 +16,6 @@"react": "React","vue": "Vue.js","svelte": "Svelte",- "js-sdk": "JS SDK Reference"+ "js-sdk": "JS SDK Reference",+ "otel": "OpenTelemetry"}diff --git a/docs/pages/client/js-sdk/_meta.json b/docs/pages/client/js-sdk/_meta.jsonindex 6f6689ff..6add2bcf 100644--- a/docs/pages/client/js-sdk/_meta.json+++ b/docs/pages/client/js-sdk/_meta.json@@ -3,5 +3,7 @@"initialization": "Initialization","exceptions": "Exceptions","messages": "Messages",- "flush": "Flush & Lifecycle"+ "flush": "Flush & Lifecycle",+ "sourcemap-upload": "Source Maps",+ "session-replay": "Session Replay"}diff --git a/docs/pages/client/js-sdk/session-replay.mdx b/docs/pages/client/js-sdk/session-replay.mdxnew file mode 100644index 00000000..8d38742e--- /dev/null+++ b/docs/pages/client/js-sdk/session-replay.mdx@@ -0,0 +1,58 @@+# Session Replay++Session Replay records DOM changes and user interactions in the browser, then attaches the recording to captured exceptions. This lets you see exactly what happened leading up to an error.++## How It Works++Session Replay uses [rrweb](https://github.com/rrweb-io/rrweb) to record the DOM. Recordings are split into segments that rotate on a fixed interval. When an exception is captured, all current segments are attached to it and sent to Traceway.++Recordings appear on the exception detail page in the Traceway dashboard as a **Session Replay** card.++## Enabled by Default++Session Replay is enabled by default when using `@tracewayapp/frontend` in a browser environment. No additional configuration is needed.++```javascript+import { init } from "@tracewayapp/frontend";++// Session Replay is active+init("your-token@https://traceway.example.com/api/report");+```++## Disabling Session Replay++```javascript+import { init } from "@tracewayapp/frontend";++init("your-token@https://traceway.example.com/api/report", {+ sessionRecording: false,+});+```++## Options++| Option | Type | Default | Description |+|--------|------|---------|-------------|+| `sessionRecording` | `boolean` | `true` | Enable or disable session recording |+| `sessionRecordingSegmentDuration` | `number` | `10000` | Duration of each recording segment in milliseconds |++## Segment Rotation++Recordings are split into segments to limit memory usage. Every 10 seconds (by default), the current segment is finalized and a new one begins with a fresh DOM snapshot.++You can adjust the segment duration:++```javascript+init("your-token@https://traceway.example.com/api/report", {+ sessionRecordingSegmentDuration: 30000, // 30 seconds per segment+});+```++## Viewing Recordings++When an exception includes session recording data, a **Session Replay** card appears on the exception detail page in the Traceway dashboard. The replay shows DOM state and user interactions leading up to the error.++## Next Steps++- [Exceptions](/client/js-sdk/exceptions) — capturing errors with the JS SDK+- [Initialization](/client/js-sdk/initialization) — all SDK configuration optionsdiff --git a/docs/pages/client/js-sdk/sourcemap-upload.mdx b/docs/pages/client/js-sdk/sourcemap-upload.mdxnew file mode 100644index 00000000..abd14d07--- /dev/null+++ b/docs/pages/client/js-sdk/sourcemap-upload.mdx@@ -0,0 +1,108 @@+# Source Maps++Upload source maps to Traceway so that minified stack traces in production exceptions are automatically deobfuscated.++## Installation++```bash+npm install -D @tracewayapp/sourcemap-upload+```++This provides the `traceway-sourcemaps` CLI command.++## Usage++```bash+traceway-sourcemaps \+ --url https://your-traceway-instance.com \+ --token your-sourcemap-token \+ --version 1.2.3 \+ --directory ./dist+```++The CLI recursively finds all `*.map` files in the specified directory and uploads them to Traceway via `POST /api/sourcemaps/upload`.++## CLI Options++| Flag | Required | Description |+|------|----------|-------------|+| `--url <url>` | Yes | Traceway backend URL |+| `--token <token>` | Yes | Source map upload token |+| `--version <version>` | Yes | App version to associate with the source maps |+| `--directory <dir>` | No | Directory to search (default: current directory) |++## Environment Variables++Instead of passing flags, you can set environment variables:++| Variable | Equivalent Flag |+|----------|----------------|+| `TRACEWAY_URL` | `--url` |+| `TRACEWAY_SOURCEMAP_TOKEN` | `--token` |++Flags take precedence over environment variables when both are set.++## Limits++Individual source map files must not exceed **50MB**.++## CI/CD Example (GitHub Actions)++```yaml+name: Deploy+on:+ push:+ branches: [main]++jobs:+ deploy:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-node@v4+ with:+ node-version: 20++ - run: npm ci+ - run: npm run build++ - name: Upload source maps+ run: npx traceway-sourcemaps --version ${{ github.sha }} --directory ./dist+ env:+ TRACEWAY_URL: ${{ secrets.TRACEWAY_URL }}+ TRACEWAY_SOURCEMAP_TOKEN: ${{ secrets.TRACEWAY_SOURCEMAP_TOKEN }}+```++## Build Script Integration++Add the upload step to your `package.json` scripts:++```json+{+ "scripts": {+ "build": "vite build",+ "postbuild": "traceway-sourcemaps --version $npm_package_version --directory ./dist"+ }+}+```++Make sure `TRACEWAY_URL` and `TRACEWAY_SOURCEMAP_TOKEN` are set in your environment.++## Version Matching++The `--version` value must match the `version` option passed to the Traceway SDK during initialization:++```javascript+import { init } from "@tracewayapp/frontend";++init("your-token@https://traceway.example.com/api/report", {+ version: "1.2.3", // Must match the --version used during upload+});+```++When an exception is captured, Traceway uses the version to look up the correct source maps and deobfuscate the stack trace.++## Next Steps++- [Exceptions](/client/js-sdk/exceptions) — capturing errors with the JS SDK+- [Initialization](/client/js-sdk/initialization) — configuring the SDK `version` optiondiff --git a/docs/pages/client/otel/_meta.json b/docs/pages/client/otel/_meta.jsonnew file mode 100644index 00000000..2c242b8a--- /dev/null+++ b/docs/pages/client/otel/_meta.json@@ -0,0 +1,5 @@+{+ "index": "Overview",+ "traces": "Traces",+ "metrics": "Metrics"+}diff --git a/docs/pages/client/otel/index.mdx b/docs/pages/client/otel/index.mdxnew file mode 100644index 00000000..05b701fd--- /dev/null+++ b/docs/pages/client/otel/index.mdx@@ -0,0 +1,76 @@+# OpenTelemetry Integration++Send traces and metrics from any OpenTelemetry-instrumented application to Traceway using the standard OTLP/HTTP protocol.++## Supported Protocols++| Protocol | Content-Type |+|----------|-------------|+| Protobuf | `application/x-protobuf` or `application/protobuf` |+| JSON | `application/json` |++Both formats follow the [OTLP/HTTP specification](https://opentelemetry.io/docs/specs/otlp/#otlphttp). Gzip compression is supported via the `Content-Encoding: gzip` header.++## Endpoints++| Method | Path | Description |+|--------|------|-------------|+| POST | `/api/otel/v1/traces` | Ingest spans and trace data |+| POST | `/api/otel/v1/metrics` | Ingest metric data |++Maximum request body size is 10MB.++## Authentication++All requests must include a Bearer token in the `Authorization` header. Use your project token from the Traceway dashboard.++```+Authorization: Bearer <project_token>+```++## Quick Start with OTel Collector++Configure the OpenTelemetry Collector to export to Traceway:++```yaml+exporters:+ otlphttp:+ endpoint: "https://your-traceway-instance.com/api/otel"+ headers:+ Authorization: "Bearer your-project-token"++service:+ pipelines:+ traces:+ exporters: [otlphttp]+ metrics:+ exporters: [otlphttp]+```++## Quick Start with OTel SDK++Configure an OpenTelemetry SDK to export directly to Traceway. Here's an example using the Node.js SDK:++```typescript+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";++const traceExporter = new OTLPTraceExporter({+ url: "https://your-traceway-instance.com/api/otel/v1/traces",+ headers: {+ Authorization: "Bearer your-project-token",+ },+});++const metricExporter = new OTLPMetricExporter({+ url: "https://your-traceway-instance.com/api/otel/v1/metrics",+ headers: {+ Authorization: "Bearer your-project-token",+ },+});+```++## Next Steps++- [Traces](/client/otel/traces) — how OTel spans map to Traceway concepts+- [Metrics](/client/otel/metrics) — supported metric types and histogram handlingdiff --git a/docs/pages/client/otel/metrics.mdx b/docs/pages/client/otel/metrics.mdxnew file mode 100644index 00000000..5ed02795--- /dev/null+++ b/docs/pages/client/otel/metrics.mdx@@ -0,0 +1,81 @@+# Metrics++Traceway ingests OpenTelemetry metrics via the OTLP/HTTP protocol at `POST /api/otel/v1/metrics`.++## Supported Metric Types++| OTel Type | Supported | Traceway Handling |+|-----------|-----------|-------------------|+| Gauge | Yes | Stored as-is |+| Sum | Yes | Stored as-is |+| Histogram | Yes | Computes average and count (see below) |+| ExponentialHistogram | No | — |+| Summary | No | — |++## Histogram Handling++Histograms are converted into two separate metric records:++| Derived Metric | Name | Value |+|---------------|------|-------|+| Average | `{name}.avg` | `sum / count` |+| Count | `{name}.count` | Total number of observations |++For example, a histogram named `http.request.duration` produces:+- `http.request.duration.avg` — the average request duration+- `http.request.duration.count` — the total number of requests observed++Histogram bucket boundaries are not stored.++## Resource Attributes++The `service.name` resource attribute is used as the Server Name for all metrics in the resource.++## Example: Node.js Metric Export++```typescript+import { NodeSDK } from "@opentelemetry/sdk-node";+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";++const sdk = new NodeSDK({+ serviceName: "my-service",+ metricReader: new PeriodicExportingMetricReader({+ exporter: new OTLPMetricExporter({+ url: "https://your-traceway-instance.com/api/otel/v1/metrics",+ headers: {+ Authorization: "Bearer your-project-token",+ },+ }),+ exportIntervalMillis: 30000,+ }),+});++sdk.start();+```++## Example: Python Metric Export++```python+from opentelemetry import metrics+from opentelemetry.sdk.metrics import MeterProvider+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter+from opentelemetry.sdk.resources import Resource++resource = Resource.create({"service.name": "my-python-service"})++exporter = OTLPMetricExporter(+ endpoint="https://your-traceway-instance.com/api/otel/v1/metrics",+ headers={"Authorization": "Bearer your-project-token"},+)++reader = PeriodicExportingMetricReader(exporter, export_interval_millis=30000)+provider = MeterProvider(resource=resource, metric_readers=[reader])+metrics.set_meter_provider(provider)+```++## Next Steps++- [Traces](/client/otel/traces) — how OTel spans map to Traceway concepts+- [Overview](/client/otel) — protocol details and authenticationdiff --git a/docs/pages/client/otel/traces.mdx b/docs/pages/client/otel/traces.mdxnew file mode 100644index 00000000..fae3d1d4--- /dev/null+++ b/docs/pages/client/otel/traces.mdx@@ -0,0 +1,103 @@+# Traces++Traceway ingests OpenTelemetry spans via the OTLP/HTTP protocol and maps them to its own data model.++## Span Mapping++How OTel spans are classified in Traceway depends on whether the span is a root span and its kind:++| OTel Span | Condition | Traceway Concept |+|-----------|-----------|-----------------|+| Root span | `SpanKind = SERVER` with HTTP attributes | **Endpoint** |+| Root span | All other kinds | **Task** |+| Non-root span | Has a parent span ID | **Span** |+| Exception event | Event named `"exception"` on any span | **Issue** |++A root span is one with no `parentSpanId`.++## Resource Attributes++These resource-level attributes are extracted and applied to all spans in the resource:++| Attribute | Traceway Field | Description |+|-----------|---------------|-------------|+| `service.name` | Server Name | Identifies the service or application |+| `service.version` | App Version | Application version string |++## HTTP Semantic Conventions++For root SERVER spans with HTTP attributes, Traceway extracts the following:++| OTel Attribute | Fallback | Traceway Field |+|---------------|----------|----------------|+| `http.request.method` | `http.method` | HTTP method |+| `http.route` | Span name | Route path |+| `http.response.status_code` | `http.status_code` | Status code |+| `http.response.body.size` | `http.response_content_length` | Response body size |+| `client.address` | `net.peer.ip` | Client IP |++The endpoint name is constructed as `"METHOD /route"` (e.g., `"GET /api/users"`).++## Exception Events++Spans with events named `"exception"` are extracted as Issues in Traceway. The following event attributes are used:++| Attribute | Description |+|-----------|-------------|+| `exception.type` | Error class name (e.g., `RuntimeError`) |+| `exception.message` | Error message |+| `exception.stacktrace` | Full stack trace |++Exceptions are grouped by a normalized hash of the stack trace, so the same logical error produces the same Issue regardless of runtime differences like memory addresses or user IDs.++## Example: Node.js with OTel SDK++```typescript+import { NodeSDK } from "@opentelemetry/sdk-node";+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";++const sdk = new NodeSDK({+ serviceName: "my-service",+ serviceVersion: "1.0.0",+ traceExporter: new OTLPTraceExporter({+ url: "https://your-traceway-instance.com/api/otel/v1/traces",+ headers: {+ Authorization: "Bearer your-project-token",+ },+ }),+ instrumentations: [getNodeAutoInstrumentations()],+});++sdk.start();+```++This automatically instruments HTTP servers, database clients, and other libraries. Root SERVER spans become Endpoints in Traceway, child spans become Spans, and any exceptions recorded as span events become Issues.++## Example: Python with OTel SDK++```python+from opentelemetry import trace+from opentelemetry.sdk.trace import TracerProvider+from opentelemetry.sdk.trace.export import BatchSpanProcessor+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter+from opentelemetry.sdk.resources import Resource++resource = Resource.create({+ "service.name": "my-python-service",+ "service.version": "1.0.0",+})++provider = TracerProvider(resource=resource)+exporter = OTLPSpanExporter(+ endpoint="https://your-traceway-instance.com/api/otel/v1/traces",+ headers={"Authorization": "Bearer your-project-token"},+)+provider.add_span_processor(BatchSpanProcessor(exporter))+trace.set_tracer_provider(provider)+```++## Next Steps++- [Metrics](/client/otel/metrics) — export metrics to Traceway via OTel+- [Overview](/client/otel) — protocol details and authenticationdiff --git a/docs/public/otel.png b/docs/public/otel.pngnew file mode 100644index 00000000..51d10498Binary files /dev/null and b/docs/public/otel.png differdiff --git a/docs/styles/custom.css b/docs/styles/custom.cssindex 97add4a0..d39015f2 100644--- a/docs/styles/custom.css+++ b/docs/styles/custom.css@@ -424,3 +424,19 @@ body[data-page^="protocol"] .nx-mx-auto.nx-flex > div.nx-w-64.nx-shrink-0 {max-width: none !important;}}++/* Hide mobile menu backdrop on desktop when resizing with menu open */+@media (min-width: 768px) {+ div:has(+ .nextra-sidebar-container)[class*="nx-fixed"] {+ display: none !important;+ }+}++.nextra-sidebar-container > :nth-child(2) {+ display: flex;+ flex-direction: column;+}++.nextra-sidebar-container > :nth-child(2) > :nth-child(1) {+ flex: 1;+}diff --git a/docs/theme.config.jsx b/docs/theme.config.jsxindex 120c911b..e0a5c238 100644--- a/docs/theme.config.jsx+++ b/docs/theme.config.jsx@@ -11,10 +11,14 @@ const SDK_VISIBILITY = {"fiber-middleware": "go-fiber","fasthttp-middleware": "go-fasthttp","http-middleware": "go-http",+ sdk: "go-","node-sdk": "js-node",- "react": "js-react",- "vue": "js-vue",- "svelte": "js-svelte",+ nestjs: "js-nestjs",+ react: "js-react",+ vue: "js-vue",+ svelte: "js-svelte",+ "js-sdk": "js-",+ otel: "otel",};export default {@@ -94,7 +98,10 @@ export default {function SdkGuard({ requiredSdk, children }) {const { sdk } = useSdk();- if (sdk !== requiredSdk) {+ const visible = requiredSdk.endsWith("-")+ ? sdk.startsWith(requiredSdk)+ : sdk === requiredSdk;+ if (!visible) {return <HiddenItem />;}return <>{children}</>;