Skip to content

The only tool you need to know what is happening and how to fix it.

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.jsx
index 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.jsx
index 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.jsx
index 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.json
index 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.json
index 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.mdx
new file mode 100644
index 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 options
diff --git a/docs/pages/client/js-sdk/sourcemap-upload.mdx b/docs/pages/client/js-sdk/sourcemap-upload.mdx
new file mode 100644
index 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` option
diff --git a/docs/pages/client/otel/_meta.json b/docs/pages/client/otel/_meta.json
new file mode 100644
index 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.mdx
new file mode 100644
index 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 handling
diff --git a/docs/pages/client/otel/metrics.mdx b/docs/pages/client/otel/metrics.mdx
new file mode 100644
index 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 authentication
diff --git a/docs/pages/client/otel/traces.mdx b/docs/pages/client/otel/traces.mdx
new file mode 100644
index 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 authentication
diff --git a/docs/public/otel.png b/docs/public/otel.png
new file mode 100644
index 00000000..51d10498
Binary files /dev/null and b/docs/public/otel.png differ
diff --git a/docs/styles/custom.css b/docs/styles/custom.css
index 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.jsx
index 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}</>;