The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
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.goindex 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.goindex c91aa12b..4eca7313 100644--- a/backend/app/controllers/project.controller.go+++ b/backend/app/controllers/project.controller.go@@ -17,12 +17,21 @@ import (// Valid framework valuesvar 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.jsxindex 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.jsxindex 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.jsxindex 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.jsonindex 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.jsonnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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 usagediff --git a/docs/pages/client/nestjs/middleware.mdx b/docs/pages/client/nestjs/middleware.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.pngnew file mode 100644index 00000000..52c7a409Binary files /dev/null and b/docs/public/nestjs.png differdiff --git a/docs/public/node.png b/docs/public/node.pngnew file mode 100644index 00000000..f6fee2adBinary files /dev/null and b/docs/public/node.png differdiff --git a/docs/public/node.svg b/docs/public/node.svgdeleted file mode 100644index 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 filediff --git a/frontend/static/node.png b/frontend/static/node.pngnew file mode 100644index 00000000..f6fee2adBinary files /dev/null and b/frontend/static/node.png differ