Skip to content

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

logos updated, added nestjs docs, project creation validation and registration validation

dduxb4b28b1bf02b
diff --git a/backend/app/controllers/auth.controller.go b/backend/app/controllers/auth.controller.go
index c532ee15..c1388a52 100644
--- a/backend/app/controllers/auth.controller.go
+++ b/backend/app/controllers/auth.controller.go
@@ -11,6 +11,7 @@ import (
"os"
"github.com/gin-gonic/gin"
+ traceway "go.tracewayapp.com"
)
var PostRegistrationHooks []func(tx *sql.Tx, org *models.Organization, user *models.User) error
@@ -151,6 +152,12 @@ func (a authController) Register(c *gin.Context) {
}
}
+ if !validFrameworks[request.Framework] {
+ traceway.CaptureMessage("Invalid framework received during registration: " + request.Framework)
+ c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, nextjs, nestjs, express, remix"})
+ return
+ }
+
project, err := repositories.ProjectRepository.CreateWithOrganization(tx, request.ProjectName, request.Framework, org.Id)
if err != nil {
c.AbortWithError(http.StatusInternalServerError, err)
diff --git a/backend/app/controllers/project.controller.go b/backend/app/controllers/project.controller.go
index c91aa12b..4eca7313 100644
--- a/backend/app/controllers/project.controller.go
+++ b/backend/app/controllers/project.controller.go
@@ -17,12 +17,21 @@ import (
// Valid framework values
var validFrameworks = map[string]bool{
- "stdlib": true,
- "fasthttp": true,
+ // Go frameworks
"gin": true,
"fiber": true,
"chi": true,
+ "fasthttp": true,
+ "stdlib": true,
"custom": true,
+ // JavaScript frameworks
+ "react": true,
+ "svelte": true,
+ "vuejs": true,
+ "nextjs": true,
+ "nestjs": true,
+ "express": true,
+ "remix": true,
}
// Project name validation regex: allows alphanumeric, spaces, hyphens, and underscores
@@ -69,7 +78,8 @@ func (p projectController) CreateProject(c *gin.Context) {
}
if !validFrameworks[request.Framework] {
- c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: stdlib, fasthttp, gin, fiber, chi, custom"})
+ traceway.CaptureMessage("Invalid framework received: " + request.Framework)
+ c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, nextjs, nestjs, express, remix"})
return
}
diff --git a/docs/components/FrameworkPicker.jsx b/docs/components/FrameworkPicker.jsx
index 8c5e4962..737ddd31 100644
--- a/docs/components/FrameworkPicker.jsx
+++ b/docs/components/FrameworkPicker.jsx
@@ -1,93 +1,106 @@
-import { useRouter } from 'next/router'
-import { useSdk } from './SdkContext'
+import { useRouter } from "next/router";
+import { useSdk } from "./SdkContext";
const FRAMEWORKS = [
{
- value: 'go-gin',
- label: 'Go Gin',
- description: 'Gin Gonic web framework with automatic request tracing and panic recovery.',
- icon: '/gin.png',
- href: '/client/gin-middleware',
+ value: "go-gin",
+ label: "Go Gin",
+ description:
+ "Gin Gonic web framework with automatic request tracing and panic recovery.",
+ icon: "/gin.png",
+ href: "/client/gin-middleware",
},
{
- value: 'go-chi',
- label: 'Go Chi',
- description: 'Lightweight Chi router with automatic request tracing and panic recovery.',
- icon: '/chi.png',
- href: '/client/chi-middleware',
+ value: "go-chi",
+ label: "Go Chi",
+ description:
+ "Lightweight Chi router with automatic request tracing and panic recovery.",
+ icon: "/chi.png",
+ href: "/client/chi-middleware",
},
{
- value: 'go-fiber',
- label: 'Go Fiber',
- description: 'Express-inspired Fiber framework with request tracing and error capture.',
- icon: '/fiber.svg',
- href: '/client/fiber-middleware',
+ value: "go-fiber",
+ label: "Go Fiber",
+ description:
+ "Express-inspired Fiber framework with request tracing and error capture.",
+ icon: "/fiber.svg",
+ href: "/client/fiber-middleware",
},
{
- value: 'go-fasthttp',
- label: 'Go FastHTTP',
- description: 'High-performance FastHTTP server with request tracing and panic recovery.',
- icon: '/fasthttp.png',
- href: '/client/fasthttp-middleware',
+ value: "go-fasthttp",
+ label: "Go FastHTTP",
+ description:
+ "High-performance FastHTTP server with request tracing and panic recovery.",
+ icon: "/fasthttp.png",
+ href: "/client/fasthttp-middleware",
},
{
- value: 'go-http',
- label: 'Go net/http',
- description: 'Standard library HTTP middleware for request tracing and error capture.',
- icon: '/stdlib.png',
- href: '/client/http-middleware',
+ value: "go-http",
+ label: "Go net/http",
+ description:
+ "Standard library HTTP middleware for request tracing and error capture.",
+ icon: "/stdlib.png",
+ href: "/client/http-middleware",
},
{
- value: 'go-generic',
- label: 'Go Generic',
- description: 'Framework-agnostic SDK for manual instrumentation of any Go application.',
- icon: '/custom.png',
- href: '/client/sdk',
+ value: "go-generic",
+ label: "Go Generic",
+ description:
+ "Framework-agnostic SDK for manual instrumentation of any Go application.",
+ icon: "/custom.png",
+ href: "/client/sdk",
},
{
- value: 'js-node',
- label: 'Node.js',
- description: 'Node.js backend SDK with trace context, spans, and metrics.',
- icon: '/node.svg',
- href: '/client/node-sdk',
+ value: "js-node",
+ label: "Node.js",
+ description: "Node.js backend SDK with trace context, spans, and metrics.",
+ icon: "/node.png",
+ href: "/client/node-sdk",
},
{
- value: 'js-react',
- label: 'React',
- description: 'React applications with error boundaries and hooks.',
- icon: '/react.png',
- href: '/client/react',
+ value: "js-nestjs",
+ label: "NestJS",
+ description: "NestJS framework with module, middleware, and decorators.",
+ icon: "/nestjs.png",
+ href: "/client/nestjs",
},
{
- value: 'js-vue',
- label: 'Vue.js',
- description: 'Vue 3 applications with plugin and composables.',
- icon: '/vue.png',
- href: '/client/vue',
+ value: "js-react",
+ label: "React",
+ description: "React applications with error boundaries and hooks.",
+ icon: "/react.png",
+ href: "/client/react",
},
{
- value: 'js-svelte',
- label: 'Svelte',
- description: 'Svelte/SvelteKit applications with context API.',
- icon: '/svelte.png',
- href: '/client/svelte',
+ value: "js-vue",
+ label: "Vue.js",
+ description: "Vue 3 applications with plugin and composables.",
+ icon: "/vue.png",
+ href: "/client/vue",
},
{
- value: 'js-generic',
- label: 'JS Generic',
- description: 'Framework-agnostic JavaScript SDK for browsers.',
- icon: '/javascript.png',
- href: '/client/js-sdk',
+ value: "js-svelte",
+ label: "Svelte",
+ description: "Svelte/SvelteKit applications with context API.",
+ icon: "/svelte.png",
+ href: "/client/svelte",
},
-]
+ {
+ value: "js-generic",
+ label: "JS Generic",
+ description: "Framework-agnostic JavaScript SDK for browsers.",
+ icon: "/javascript.png",
+ href: "/client/js-sdk",
+ },
+];
export default function FrameworkPicker() {
- const router = useRouter()
- const { setSdk } = useSdk()
+ const router = useRouter();
+ const { setSdk } = useSdk();
function handleSelect(fw) {
- setSdk(fw.value)
- router.push(`${fw.href}?sdk=${fw.value}`)
+ setSdk(fw.value);
+ router.push(`${fw.href}?sdk=${fw.value}`);
}
return (
@@ -103,12 +116,16 @@ export default function FrameworkPicker() {
className="framework-picker-card"
onClick={() => handleSelect(fw)}
>
- <img src={fw.icon} alt={fw.label} className="framework-picker-icon" />
+ <img
+ src={fw.icon}
+ alt={fw.label}
+ className="framework-picker-icon"
+ />
<span className="framework-picker-label">{fw.label}</span>
<span className="framework-picker-desc">{fw.description}</span>
</button>
))}
</div>
</div>
- )
+ );
}
diff --git a/docs/components/SdkContext.jsx b/docs/components/SdkContext.jsx
index 97b23d38..da8d57fb 100644
--- a/docs/components/SdkContext.jsx
+++ b/docs/components/SdkContext.jsx
@@ -9,6 +9,7 @@ export const SDK_OPTIONS = [
{ value: 'go-http', label: 'Go Http' },
{ value: 'go-generic', label: 'Go Generic' },
{ value: 'js-node', label: 'Node.js' },
+ { value: 'js-nestjs', label: 'NestJS' },
{ value: 'js-react', label: 'React' },
{ value: 'js-vue', label: 'Vue.js' },
{ value: 'js-svelte', label: 'Svelte' },
@@ -25,6 +26,7 @@ const PATH_SDK_MAP = {
'fasthttp-middleware': 'go-fasthttp',
'http-middleware': 'go-http',
'node-sdk': 'js-node',
+ 'nestjs': 'js-nestjs',
'react': 'js-react',
'vue': 'js-vue',
'svelte': 'js-svelte',
diff --git a/docs/components/SdkSelector.jsx b/docs/components/SdkSelector.jsx
index b8048728..113f489e 100644
--- a/docs/components/SdkSelector.jsx
+++ b/docs/components/SdkSelector.jsx
@@ -10,6 +10,7 @@ const SDK_QUICK_START = {
'go-http': '/client/http-middleware',
'go-generic': '/client/sdk',
'js-node': '/client/node-sdk',
+ 'js-nestjs': '/client/nestjs',
'js-react': '/client/react',
'js-vue': '/client/vue',
'js-svelte': '/client/svelte',
diff --git a/docs/pages/client/_meta.json b/docs/pages/client/_meta.json
index ffe54567..ee7a41f5 100644
--- a/docs/pages/client/_meta.json
+++ b/docs/pages/client/_meta.json
@@ -12,6 +12,7 @@
"http-middleware": "HTTP Middleware",
"sdk": "SDK Reference",
"node-sdk": "Node.js SDK",
+ "nestjs": "NestJS",
"react": "React",
"vue": "Vue.js",
"svelte": "Svelte",
diff --git a/docs/pages/client/nestjs/_meta.json b/docs/pages/client/nestjs/_meta.json
new file mode 100644
index 00000000..a498d528
--- /dev/null
+++ b/docs/pages/client/nestjs/_meta.json
@@ -0,0 +1,8 @@
+{
+ "index": "Quick Start",
+ "module": "TracewayModule",
+ "middleware": "Middleware",
+ "filter": "Exception Filter",
+ "service": "TracewayService",
+ "decorators": "Decorators"
+}
diff --git a/docs/pages/client/nestjs/decorators.mdx b/docs/pages/client/nestjs/decorators.mdx
new file mode 100644
index 00000000..2ecc0717
--- /dev/null
+++ b/docs/pages/client/nestjs/decorators.mdx
@@ -0,0 +1,171 @@
+# Decorators
+
+The `@traceway/nestjs` package provides the `@Span` decorator for automatic span creation around methods.
+
+## @Span Decorator
+
+The `@Span` decorator wraps a method to automatically create and end a span, timing the method's execution.
+
+### Basic Usage
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { Span } from "@traceway/nestjs";
+
+@Injectable()
+export class UsersService {
+ @Span("db.users.findAll")
+ async findAll() {
+ return this.userRepository.find();
+ }
+
+ @Span("db.users.findOne")
+ async findOne(id: string) {
+ return this.userRepository.findOne(id);
+ }
+
+ @Span("db.users.create")
+ async create(data: CreateUserDto) {
+ return this.userRepository.save(data);
+ }
+}
+```
+
+### Default Span Name
+
+If no name is provided, the method name is used:
+
+```typescript
+@Injectable()
+export class UsersService {
+ @Span() // Span name will be "findAll"
+ async findAll() {
+ return this.userRepository.find();
+ }
+}
+```
+
+### With Async Methods
+
+The decorator handles both sync and async methods:
+
+```typescript
+@Injectable()
+export class CacheService {
+ @Span("cache.get")
+ async get(key: string): Promise<string | null> {
+ // Async operation
+ return this.redis.get(key);
+ }
+
+ @Span("cache.compute")
+ computeHash(data: string): string {
+ // Sync operation
+ return crypto.createHash("sha256").update(data).digest("hex");
+ }
+}
+```
+
+### Error Handling
+
+The span is ended even if the method throws an error:
+
+```typescript
+@Injectable()
+export class PaymentService {
+ @Span("payment.process")
+ async processPayment(amount: number) {
+ // If this throws, the span is still ended
+ // and the error propagates normally
+ await this.gateway.charge(amount);
+ }
+}
+```
+
+## Naming Conventions
+
+Use descriptive, hierarchical span names:
+
+| Pattern | Example | Use Case |
+|---------|---------|----------|
+| `db.<table>.<operation>` | `db.users.findOne` | Database operations |
+| `cache.<operation>` | `cache.get` | Cache operations |
+| `http.<service>` | `http.payment-api` | External HTTP calls |
+| `queue.<action>` | `queue.publish` | Message queue operations |
+| `<service>.<method>` | `email.send` | Service method calls |
+
+## Combining with TracewayService
+
+You can use `@Span` alongside `TracewayService` for more control:
+
+```typescript
+@Injectable()
+export class OrdersService {
+ constructor(private readonly traceway: TracewayService) {}
+
+ @Span("orders.process")
+ async processOrder(orderId: string) {
+ // Set attributes for the trace
+ this.traceway.setTraceAttribute("orderId", orderId);
+
+ // Create nested spans manually
+ const validationSpan = this.traceway.startSpan("orders.validate");
+ await this.validateOrder(orderId);
+ this.traceway.endSpan(validationSpan);
+
+ // The @Span decorator handles the outer span
+ await this.fulfillOrder(orderId);
+ }
+}
+```
+
+## Limitations
+
+### Class Methods Only
+
+The decorator only works on class methods, not standalone functions:
+
+```typescript
+// Works
+@Injectable()
+class MyService {
+ @Span("operation")
+ doSomething() {}
+}
+
+// Does NOT work
+@Span("operation") // Error: decorators on functions not supported
+function standalone() {}
+```
+
+### No Parameter Access
+
+The span name is static and cannot access method parameters:
+
+```typescript
+@Injectable()
+class UsersService {
+ // Span name is always "db.users.findOne"
+ // Cannot be "db.users.findOne:123" based on id parameter
+ @Span("db.users.findOne")
+ async findOne(id: string) {}
+}
+```
+
+For dynamic span names, use `TracewayService.startSpan()` manually:
+
+```typescript
+@Injectable()
+class UsersService {
+ constructor(private readonly traceway: TracewayService) {}
+
+ async findOne(id: string) {
+ const span = this.traceway.startSpan(`db.users.findOne:${id}`);
+ try {
+ return await this.userRepository.findOne(id);
+ } finally {
+ this.traceway.endSpan(span);
+ }
+ }
+}
+```
diff --git a/docs/pages/client/nestjs/filter.mdx b/docs/pages/client/nestjs/filter.mdx
new file mode 100644
index 00000000..dc3fabd1
--- /dev/null
+++ b/docs/pages/client/nestjs/filter.mdx
@@ -0,0 +1,168 @@
+# TracewayExceptionFilter
+
+The `TracewayExceptionFilter` is a global exception filter that captures unhandled exceptions and sends them to Traceway with full stack traces and request context.
+
+## Setup
+
+Register the filter globally in your app module:
+
+```typescript
+import { Module } from "@nestjs/common";
+import { APP_FILTER } from "@nestjs/core";
+import { TracewayModule, TracewayExceptionFilter } from "@traceway/nestjs";
+
+@Module({
+ imports: [
+ TracewayModule.forRoot({
+ connectionString: "your-token@https://traceway.example.com/api/report",
+ onErrorRecording: ["url", "query", "body", "headers"],
+ }),
+ ],
+ providers: [
+ {
+ provide: APP_FILTER,
+ useClass: TracewayExceptionFilter,
+ },
+ ],
+})
+export class AppModule {}
+```
+
+## What Gets Captured
+
+When an exception is thrown:
+
+| Data | Condition |
+|------|-----------|
+| Error message | Always |
+| Stack trace | Always |
+| Trace ID | If within a traced request |
+| Trace attributes | If within a traced request |
+| User agent | Always |
+| URL | If `onErrorRecording` includes `"url"` |
+| Query params | If `onErrorRecording` includes `"query"` |
+| Request body | If `onErrorRecording` includes `"body"` (JSON only) |
+| Headers | If `onErrorRecording` includes `"headers"` |
+
+## Error Recording Options
+
+Configure what request data to include with captured exceptions:
+
+```typescript
+TracewayModule.forRoot({
+ connectionString: "...",
+ onErrorRecording: ["url", "query", "body", "headers"],
+})
+```
+
+### URL Recording
+
+```typescript
+onErrorRecording: ["url"]
+```
+
+Captures the request path:
+```
+url: "/api/users/123"
+```
+
+### Query Recording
+
+```typescript
+onErrorRecording: ["query"]
+```
+
+Captures query parameters as JSON:
+```
+query: {"page":"1","limit":"10"}
+```
+
+### Body Recording
+
+```typescript
+onErrorRecording: ["body"]
+```
+
+Captures request body for JSON requests (max 64KB):
+```
+body: {"name":"John","email":"[email protected]"}
+```
+
+### Headers Recording
+
+```typescript
+onErrorRecording: ["headers"]
+```
+
+Captures request headers (excluding `authorization` and `cookie` for security):
+```
+headers: {"content-type":"application/json","x-request-id":"abc123"}
+```
+
+## Exception Types
+
+### HttpException
+
+For NestJS `HttpException` errors (4xx client errors), the filter:
+- Returns the standard NestJS error response
+- Does **not** capture to Traceway (client errors are expected)
+
+### Server Errors (5xx)
+
+For server errors and unhandled exceptions:
+- Captures the exception to Traceway
+- Returns a 500 Internal Server Error response
+
+```typescript
+@Get("crash")
+crash() {
+ // This gets captured to Traceway
+ throw new Error("Something went wrong");
+}
+
+@Get("not-found")
+notFound() {
+ // This does NOT get captured (4xx error)
+ throw new NotFoundException("User not found");
+}
+```
+
+## Combining with Other Filters
+
+If you have other exception filters, ensure `TracewayExceptionFilter` runs first by registering it before other filters:
+
+```typescript
+providers: [
+ {
+ provide: APP_FILTER,
+ useClass: TracewayExceptionFilter,
+ },
+ {
+ provide: APP_FILTER,
+ useClass: YourCustomFilter,
+ },
+],
+```
+
+## Manual Exception Capture
+
+For errors you catch and handle yourself, use `TracewayService`:
+
+```typescript
+@Injectable()
+export class PaymentService {
+ constructor(private readonly traceway: TracewayService) {}
+
+ async processPayment(amount: number) {
+ try {
+ await this.paymentGateway.charge(amount);
+ } catch (error) {
+ // Capture but don't re-throw
+ this.traceway.captureException(error);
+
+ // Handle gracefully
+ return { success: false, error: "Payment failed" };
+ }
+ }
+}
+```
diff --git a/docs/pages/client/nestjs/index.mdx b/docs/pages/client/nestjs/index.mdx
new file mode 100644
index 00000000..9d51fabe
--- /dev/null
+++ b/docs/pages/client/nestjs/index.mdx
@@ -0,0 +1,164 @@
+# NestJS Quick Start
+
+Integrate Traceway into your NestJS application with the `@traceway/nestjs` package.
+
+## Installation
+
+```bash
+npm install @traceway/nestjs
+```
+
+## Setup
+
+### 1. Import TracewayModule
+
+Add `TracewayModule.forRoot()` to your app module:
+
+```typescript
+import { Module } from "@nestjs/common";
+import { TracewayModule } from "@traceway/nestjs";
+
+@Module({
+ imports: [
+ TracewayModule.forRoot({
+ connectionString: "your-token@https://traceway.example.com/api/report",
+ }),
+ ],
+})
+export class AppModule {}
+```
+
+### 2. Add Middleware for Request Tracing
+
+Apply `TracewayMiddleware` to trace all HTTP requests:
+
+```typescript
+import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
+import { TracewayModule, TracewayMiddleware } from "@traceway/nestjs";
+
+@Module({
+ imports: [
+ TracewayModule.forRoot({
+ connectionString: "your-token@https://traceway.example.com/api/report",
+ }),
+ ],
+})
+export class AppModule implements NestModule {
+ configure(consumer: MiddlewareConsumer) {
+ consumer.apply(TracewayMiddleware).forRoutes("*");
+ }
+}
+```
+
+### 3. Add Exception Filter
+
+Register `TracewayExceptionFilter` globally to capture unhandled exceptions:
+
+```typescript
+import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
+import { APP_FILTER } from "@nestjs/core";
+import {
+ TracewayModule,
+ TracewayMiddleware,
+ TracewayExceptionFilter,
+} from "@traceway/nestjs";
+
+@Module({
+ imports: [
+ TracewayModule.forRoot({
+ connectionString: "your-token@https://traceway.example.com/api/report",
+ debug: true,
+ onErrorRecording: ["url", "query", "body", "headers"],
+ }),
+ ],
+ providers: [
+ {
+ provide: APP_FILTER,
+ useClass: TracewayExceptionFilter,
+ },
+ ],
+})
+export class AppModule implements NestModule {
+ configure(consumer: MiddlewareConsumer) {
+ consumer.apply(TracewayMiddleware).forRoutes("*");
+ }
+}
+```
+
+## What Gets Captured
+
+| Data | Description |
+|------|-------------|
+| Endpoint | HTTP method and route (e.g., `GET /users/:id`) |
+| Duration | Request processing time |
+| Status Code | HTTP response status |
+| Client IP | Client IP address from headers or socket |
+| Exceptions | Unhandled errors with full stack traces |
+| Spans | Custom spans created within the request |
+
+## Using TracewayService
+
+Inject `TracewayService` to capture errors and create spans manually:
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { TracewayService, Span } from "@traceway/nestjs";
+
+@Injectable()
+export class UsersService {
+ constructor(private readonly traceway: TracewayService) {}
+
+ @Span("db.users.findAll")
+ async findAll() {
+ // Span automatically created and ended
+ return this.userRepository.find();
+ }
+
+ async createUser(data: CreateUserDto) {
+ // Manual span
+ const span = this.traceway.startSpan("db.users.create");
+ try {
+ const user = await this.userRepository.save(data);
+ return user;
+ } finally {
+ this.traceway.endSpan(span);
+ }
+ }
+
+ async riskyOperation() {
+ try {
+ await this.externalApi.call();
+ } catch (error) {
+ // Manual exception capture
+ this.traceway.captureException(error);
+ throw error;
+ }
+ }
+}
+```
+
+## Test Your Integration
+
+Create a test endpoint that throws an error:
+
+```typescript
+import { Controller, Get } from "@nestjs/common";
+
+@Controller()
+export class AppController {
+ @Get("test-error")
+ testError() {
+ throw new Error("Test error from NestJS");
+ }
+}
+```
+
+Visit `/test-error` and check your Traceway dashboard to verify the error appears with a full stack trace.
+
+## Next Steps
+
+- [TracewayModule](/client/nestjs/module) - Configuration options and async setup
+- [Middleware](/client/nestjs/middleware) - Request tracing details
+- [Exception Filter](/client/nestjs/filter) - Error recording options
+- [TracewayService](/client/nestjs/service) - Manual instrumentation
+- [Decorators](/client/nestjs/decorators) - @Span decorator usage
diff --git a/docs/pages/client/nestjs/middleware.mdx b/docs/pages/client/nestjs/middleware.mdx
new file mode 100644
index 00000000..a60dc532
--- /dev/null
+++ b/docs/pages/client/nestjs/middleware.mdx
@@ -0,0 +1,112 @@
+# TracewayMiddleware
+
+The `TracewayMiddleware` wraps each HTTP request in a trace context, automatically capturing request timing, status codes, and any spans created during the request.
+
+## Setup
+
+Apply the middleware in your app module:
+
+```typescript
+import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
+import { TracewayModule, TracewayMiddleware } from "@traceway/nestjs";
+
+@Module({
+ imports: [
+ TracewayModule.forRoot({
+ connectionString: "your-token@https://traceway.example.com/api/report",
+ }),
+ ],
+})
+export class AppModule implements NestModule {
+ configure(consumer: MiddlewareConsumer) {
+ consumer.apply(TracewayMiddleware).forRoutes("*");
+ }
+}
+```
+
+## Selective Routes
+
+Apply middleware to specific routes only:
+
+```typescript
+export class AppModule implements NestModule {
+ configure(consumer: MiddlewareConsumer) {
+ consumer
+ .apply(TracewayMiddleware)
+ .forRoutes("users", "orders", "products");
+ }
+}
+```
+
+Or exclude specific routes:
+
+```typescript
+export class AppModule implements NestModule {
+ configure(consumer: MiddlewareConsumer) {
+ consumer
+ .apply(TracewayMiddleware)
+ .exclude("health", "metrics")
+ .forRoutes("*");
+ }
+}
+```
+
+## What Gets Captured
+
+For each request, the middleware captures:
+
+| Field | Description |
+|-------|-------------|
+| `endpoint` | HTTP method and route path (e.g., `GET /users/:id`) |
+| `clientIP` | Client IP from X-Forwarded-For header or socket |
+| `statusCode` | HTTP response status code |
+| `bodySize` | Response body size from Content-Length header |
+| `duration` | Total request processing time |
+| `spans` | Any spans created during the request |
+| `attributes` | Custom attributes set via `TracewayService` |
+
+## How It Works
+
+1. **Request Start**: Creates a new trace context with `withTraceContext()`
+2. **Request Processing**: Your controllers and services run within the trace context
+3. **Response Finish**: On the `res.finish` event:
+ - Records status code and body size with `setTraceResponseInfo()`
+ - Captures the trace with `captureCurrentTrace()`
+
+## Ignored Routes
+
+Use the `ignoredRoutes` option in `TracewayModule.forRoot()` to skip tracing for specific routes:
+
+```typescript
+TracewayModule.forRoot({
+ connectionString: "...",
+ ignoredRoutes: ["/health", "/metrics", "/favicon.ico"],
+})
+```
+
+## Trace Context
+
+The middleware establishes a trace context that propagates through all async operations. This means:
+
+- Exceptions captured with `TracewayService.captureException()` are linked to the trace
+- Spans created with `TracewayService.startSpan()` are added to the trace
+- Attributes set with `TracewayService.setTraceAttribute()` are included in the trace
+
+```typescript
+@Injectable()
+export class UsersService {
+ constructor(private readonly traceway: TracewayService) {}
+
+ async findOne(id: string) {
+ // This attribute will be included in the current request's trace
+ this.traceway.setTraceAttribute("userId", id);
+
+ // This span will be part of the current request's trace
+ const span = this.traceway.startSpan("db.query");
+ const user = await this.userRepository.findOne(id);
+ this.traceway.endSpan(span);
+
+ return user;
+ }
+}
+```
diff --git a/docs/pages/client/nestjs/module.mdx b/docs/pages/client/nestjs/module.mdx
new file mode 100644
index 00000000..d446f82d
--- /dev/null
+++ b/docs/pages/client/nestjs/module.mdx
@@ -0,0 +1,124 @@
+# TracewayModule
+
+The `TracewayModule` is a global NestJS module that initializes Traceway and provides the `TracewayService` throughout your application.
+
+## Static Configuration
+
+Use `forRoot()` for static configuration:
+
+```typescript
+import { Module } from "@nestjs/common";
+import { TracewayModule } from "@traceway/nestjs";
+
+@Module({
+ imports: [
+ TracewayModule.forRoot({
+ connectionString: "your-token@https://traceway.example.com/api/report",
+ debug: true,
+ version: "1.0.0",
+ serverName: "api-server-1",
+ sampleRate: 1.0,
+ errorSampleRate: 1.0,
+ ignoredRoutes: ["/health", "/metrics"],
+ onErrorRecording: ["url", "query", "body", "headers"],
+ }),
+ ],
+})
+export class AppModule {}
+```
+
+## Async Configuration
+
+Use `forRootAsync()` when you need to load configuration from environment variables or a config service:
+
+```typescript
+import { Module } from "@nestjs/common";
+import { ConfigModule, ConfigService } from "@nestjs/config";
+import { TracewayModule } from "@traceway/nestjs";
+
+@Module({
+ imports: [
+ ConfigModule.forRoot(),
+ TracewayModule.forRootAsync({
+ imports: [ConfigModule],
+ useFactory: (config: ConfigService) => ({
+ connectionString: config.get("TRACEWAY_CONNECTION_STRING"),
+ debug: config.get("NODE_ENV") !== "production",
+ version: config.get("APP_VERSION"),
+ serverName: config.get("HOSTNAME"),
+ }),
+ inject: [ConfigService],
+ }),
+ ],
+})
+export class AppModule {}
+```
+
+### Using useClass
+
+You can also use a factory class:
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { TracewayModule, TracewayOptionsFactory, TracewayModuleOptions } from "@traceway/nestjs";
+
+@Injectable()
+class TracewayConfigService implements TracewayOptionsFactory {
+ createTracewayOptions(): TracewayModuleOptions {
+ return {
+ connectionString: process.env.TRACEWAY_CONNECTION_STRING,
+ debug: process.env.NODE_ENV !== "production",
+ };
+ }
+}
+
+@Module({
+ imports: [
+ TracewayModule.forRootAsync({
+ useClass: TracewayConfigService,
+ }),
+ ],
+})
+export class AppModule {}
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `connectionString` | `string` | Required | Connection string in format `token@endpoint` |
+| `debug` | `boolean` | `false` | Enable debug logging |
+| `version` | `string` | `""` | Application version |
+| `serverName` | `string` | hostname | Server identifier |
+| `sampleRate` | `number` | `1.0` | Trace sampling rate (0-1) |
+| `errorSampleRate` | `number` | `1.0` | Error trace sampling rate (0-1) |
+| `ignoredRoutes` | `string[]` | `[]` | Routes to skip tracing |
+| `onErrorRecording` | `Array` | `[]` | Data to include with errors |
+
+### onErrorRecording Options
+
+When an exception is captured, you can include additional request data:
+
+| Value | Description |
+|-------|-------------|
+| `"url"` | Request URL path |
+| `"query"` | Query parameters as JSON |
+| `"body"` | Request body (JSON only, max 64KB) |
+| `"headers"` | Request headers (excludes Authorization and Cookie) |
+
+## Lifecycle
+
+- **Initialization**: Traceway is initialized when the module loads
+- **Shutdown**: Traceway flushes pending data and shuts down when the module is destroyed
+
+The module implements `OnModuleDestroy` to ensure graceful shutdown:
+
+```typescript
+async onModuleDestroy(): Promise<void> {
+ await this.tracewayService.shutdownAsync();
+}
+```
+
+## Global Module
+
+`TracewayModule` is decorated with `@Global()`, so `TracewayService` is available for injection in any module without needing to import `TracewayModule` again.
diff --git a/docs/pages/client/nestjs/service.mdx b/docs/pages/client/nestjs/service.mdx
new file mode 100644
index 00000000..026231a4
--- /dev/null
+++ b/docs/pages/client/nestjs/service.mdx
@@ -0,0 +1,234 @@
+# TracewayService
+
+The `TracewayService` is an injectable service that provides methods for manual error capture, span creation, and trace attribute management.
+
+## Injection
+
+Inject `TracewayService` into any service or controller:
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { TracewayService } from "@traceway/nestjs";
+
+@Injectable()
+export class UsersService {
+ constructor(private readonly traceway: TracewayService) {}
+}
+```
+
+## Methods
+
+### captureException
+
+Capture an error with automatic trace context:
+
+```typescript
+captureException(error: Error): void
+```
+
+```typescript
+try {
+ await this.externalApi.call();
+} catch (error) {
+ this.traceway.captureException(error);
+ throw error; // Re-throw or handle gracefully
+}
+```
+
+### captureExceptionWithAttributes
+
+Capture an error with custom attributes:
+
+```typescript
+captureExceptionWithAttributes(
+ error: Error,
+ attributes?: Record<string, string>,
+ traceId?: string
+): void
+```
+
+```typescript
+this.traceway.captureExceptionWithAttributes(error, {
+ userId: user.id,
+ action: "checkout",
+ cartTotal: String(cart.total),
+});
+```
+
+### captureMessage
+
+Capture an informational message:
+
+```typescript
+captureMessage(msg: string, attributes?: Record<string, string>): void
+```
+
+```typescript
+this.traceway.captureMessage("User completed onboarding", {
+ userId: user.id,
+ plan: user.plan,
+});
+```
+
+### startSpan / endSpan
+
+Create custom spans for timing operations:
+
+```typescript
+startSpan(name: string): SpanHandle
+endSpan(span: SpanHandle, addToContext?: boolean): void
+```
+
+```typescript
+async findUserWithOrders(userId: string) {
+ const userSpan = this.traceway.startSpan("db.users.findOne");
+ const user = await this.userRepository.findOne(userId);
+ this.traceway.endSpan(userSpan);
+
+ const ordersSpan = this.traceway.startSpan("db.orders.findByUser");
+ const orders = await this.orderRepository.findByUser(userId);
+ this.traceway.endSpan(ordersSpan);
+
+ return { user, orders };
+}
+```
+
+### measureTask
+
+Measure a background task:
+
+```typescript
+measureTask(title: string, fn: () => void | Promise<void>): void
+```
+
+```typescript
+// Fire and forget background task
+this.traceway.measureTask("send-welcome-email", async () => {
+ await this.emailService.sendWelcome(user.email);
+});
+```
+
+### setTraceAttribute / setTraceAttributes
+
+Add attributes to the current trace:
+
+```typescript
+setTraceAttribute(key: string, value: string): void
+setTraceAttributes(attributes: Record<string, string>): void
+```
+
+```typescript
+async handleRequest(userId: string, action: string) {
+ // Single attribute
+ this.traceway.setTraceAttribute("userId", userId);
+
+ // Multiple attributes
+ this.traceway.setTraceAttributes({
+ action,
+ timestamp: new Date().toISOString(),
+ });
+}
+```
+
+### getTraceId
+
+Get the current trace ID:
+
+```typescript
+getTraceId(): string | undefined
+```
+
+```typescript
+async processOrder(order: Order) {
+ const traceId = this.traceway.getTraceId();
+
+ // Include trace ID in external API calls for correlation
+ await this.fulfillmentApi.submit(order, {
+ headers: { "X-Trace-ID": traceId },
+ });
+}
+```
+
+### getTraceContext
+
+Get the full trace context:
+
+```typescript
+getTraceContext(): TraceContext | undefined
+```
+
+```typescript
+const ctx = this.traceway.getTraceContext();
+if (ctx) {
+ console.log("Trace ID:", ctx.traceId);
+ console.log("Endpoint:", ctx.endpoint);
+ console.log("Spans:", ctx.spans.length);
+}
+```
+
+### withTraceContext
+
+Run a function within a new trace context:
+
+```typescript
+withTraceContext<T>(options: TraceContextOptions, fn: () => T): T
+```
+
+```typescript
+// Useful for background jobs or non-HTTP contexts
+this.traceway.withTraceContext(
+ { endpoint: "cron.cleanup", isTask: true },
+ async () => {
+ await this.cleanupOldRecords();
+ }
+);
+```
+
+## Example: Full Service
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { TracewayService, Span } from "@traceway/nestjs";
+
+@Injectable()
+export class OrdersService {
+ constructor(
+ private readonly traceway: TracewayService,
+ private readonly orderRepository: OrderRepository,
+ private readonly paymentService: PaymentService,
+ private readonly emailService: EmailService,
+ ) {}
+
+ @Span("orders.create")
+ async createOrder(userId: string, items: OrderItem[]) {
+ // Set trace attributes for debugging
+ this.traceway.setTraceAttributes({
+ userId,
+ itemCount: String(items.length),
+ });
+
+ // Create order with span
+ const orderSpan = this.traceway.startSpan("db.orders.create");
+ const order = await this.orderRepository.create({ userId, items });
+ this.traceway.endSpan(orderSpan);
+
+ // Process payment
+ const paymentSpan = this.traceway.startSpan("payment.process");
+ try {
+ await this.paymentService.charge(order.total);
+ } catch (error) {
+ this.traceway.captureException(error);
+ throw error;
+ } finally {
+ this.traceway.endSpan(paymentSpan);
+ }
+
+ // Send confirmation email (background task)
+ this.traceway.measureTask("email.order-confirmation", async () => {
+ await this.emailService.sendOrderConfirmation(order);
+ });
+
+ return order;
+ }
+}
+```
diff --git a/docs/public/nestjs.png b/docs/public/nestjs.png
new file mode 100644
index 00000000..52c7a409
Binary files /dev/null and b/docs/public/nestjs.png differ
diff --git a/docs/public/node.png b/docs/public/node.png
new file mode 100644
index 00000000..f6fee2ad
Binary files /dev/null and b/docs/public/node.png differ
diff --git a/docs/public/node.svg b/docs/public/node.svg
deleted file mode 100644
index 007d7cc4..00000000
--- a/docs/public/node.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Node.js</title><path fill="#5FA04E" d="M11.998,24c-0.321,0-0.641-0.084-0.922-0.247l-2.936-1.737c-0.438-0.245-0.224-0.332-0.08-0.383 c0.585-0.203,0.703-0.25,1.328-0.604c0.065-0.037,0.151-0.023,0.218,0.017l2.256,1.339c0.082,0.045,0.197,0.045,0.272,0l8.795-5.076 c0.082-0.047,0.134-0.141,0.134-0.238V6.921c0-0.099-0.053-0.192-0.137-0.242l-8.791-5.072c-0.081-0.047-0.189-0.047-0.271,0 L3.075,6.68C2.99,6.729,2.936,6.825,2.936,6.921v10.15c0,0.097,0.054,0.189,0.139,0.235l2.409,1.392 c1.307,0.654,2.108-0.116,2.108-0.89V7.787c0-0.142,0.114-0.253,0.256-0.253h1.115c0.139,0,0.255,0.112,0.255,0.253v10.021 c0,1.745-0.95,2.745-2.604,2.745c-0.508,0-0.909,0-2.026-0.551L2.28,18.675c-0.57-0.329-0.922-0.945-0.922-1.604V6.921 c0-0.659,0.353-1.275,0.922-1.603l8.795-5.082c0.557-0.315,1.296-0.315,1.848,0l8.794,5.082c0.57,0.329,0.924,0.944,0.924,1.603 v10.15c0,0.659-0.354,1.273-0.924,1.604l-8.794,5.078C12.643,23.916,12.324,24,11.998,24z M19.099,13.993 c0-1.9-1.284-2.406-3.987-2.763c-2.731-0.361-3.009-0.548-3.009-1.187c0-0.528,0.235-1.233,2.258-1.233 c1.807,0,2.473,0.389,2.747,1.607c0.024,0.115,0.129,0.199,0.247,0.199h1.141c0.071,0,0.138-0.031,0.186-0.081 c0.048-0.054,0.074-0.123,0.067-0.196c-0.177-2.098-1.571-3.076-4.388-3.076c-2.508,0-4.004,1.058-4.004,2.833 c0,1.925,1.488,2.457,3.895,2.695c2.88,0.282,3.103,0.703,3.103,1.269c0,0.983-0.789,1.402-2.642,1.402 c-2.327,0-2.839-0.584-3.011-1.742c-0.02-0.124-0.126-0.215-0.253-0.215h-1.137c-0.141,0-0.254,0.112-0.254,0.253 c0,1.482,0.806,3.248,4.655,3.248C17.501,17.007,19.099,15.91,19.099,13.993z"/></svg>
\ No newline at end of file
diff --git a/frontend/static/node.png b/frontend/static/node.png
new file mode 100644
index 00000000..f6fee2ad
Binary files /dev/null and b/frontend/static/node.png differ