Skip to content

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

6.3 KB
Raw Blame

devtesting-nestjs

NestJS test application for the Traceway JS SDK (@tracewayapp/nestjs). Mirrors the Go devtesting reference app to validate that all SDK features work correctly in a NestJS environment.

Running

npm install
npm run start:dev

The app starts on port 3001 by default (configurable via PORT env var).

Environment Variables

Variable Default Description
PORT 3001 Server port
TRACEWAY_ENDPOINT default_token_change_me@http://localhost:8082/api/report Traceway connection string

Docker (PM2 cluster mode)

Runs 4 instances of the app via PM2 in cluster mode.

Build

./docker-build.sh

This packs the local @tracewayapp/* packages into tarballs, builds the Docker image, then cleans up.

Run

docker run -p 3001:3001 \
  -e TRACEWAY_ENDPOINT="ed37c05e51c54f1db721f6fc59994e9b@http://host.docker.internal:8082/api/report" \
  devtesting-nestjs

host.docker.internal resolves to the host machine's localhost, so the app inside Docker can reach the Traceway backend running on your local port 8082.

The NestJS app is exposed on http://localhost:3001 as usual.

SDK Integration

All @tracewayapp/nestjs integration points are used correctly:

Component Location Usage
TracewayModule.forRoot() app.module.ts:14 Configured with connectionString, debug, onErrorRecording
TracewayMiddleware app.module.ts:34 Applied globally via forRoutes("*")
TracewayExceptionFilter app.module.ts:27 Registered as global APP_FILTER
TracewayService app.controller.ts:21, app.service.ts:16 Injected via constructor
@Span() decorator users.service.ts, app.service.ts Applied to 8 methods total

TracewayService Methods Used

Method Location Purpose
captureMessage app.service.ts:24 Log informational messages
captureException app.service.ts:26 Report errors
captureExceptionWithAttributes app.service.ts:71 Report errors with custom attributes
startSpan / endSpan app.service.ts:45,51 Manual span creation
measureTask app.service.ts:57 Wrap background work as a tracked task
setTraceAttribute app.service.ts:79 Attach context attributes to the current trace

Endpoints

App Controller (14 endpoints)

Method Path Description
GET /test-ok Returns { status: "ok" }
GET /test-not-found Throws 404 HttpException
GET /test-exception Throws unhandled Error after random delay
GET /test-message Captures 10 messages + 1 exception via TracewayService
GET /test-spans Runs nested spans (db.query, cache.set, http.external_api)
GET /test-task Starts a background task via measureTask
GET /test-param/:param Returns the route param
GET /test-self-report-attributes Calls captureExceptionWithAttributes with custom attrs
GET /test-self-report-context Sets a trace attribute then captures an exception
GET /test-cerror-simple Throws a simple Error
GET /test-cerror-stacktrace Throws an Error from a nested function call
GET /test-cerror-wrapped Throws a 2-layer wrapped Error (using cause)
GET /test-cerror-custom Throws a CustomError with code + message
POST /test-recording/:param Accepts JSON body { name }, throws if name != "good"

Users Controller (5 endpoints)

Method Path Description
GET /users List all users
GET /users/:id Get user by ID
POST /users Create user ({ firstName, lastName, email })
PUT /users/:id Update user
DELETE /users/:id Delete user

All user service methods are decorated with @Span() (e.g. db.users.findAll, db.users.create) and use an in-memory array as the data store with simulated DB delay.

Comparison with Go devtesting

Shared Endpoints (15)

Both apps implement: test-ok, test-not-found, test-exception, test-message, test-spans, test-task, test-param/:param, test-self-report-attributes, test-self-report-context, test-cerror-simple, test-cerror-stacktrace, test-cerror-wrapped, test-cerror-custom, test-recording/:param, and /users CRUD.

Go-Only Endpoints (7)

Endpoint Reason Not Ported
/test-json Could be ported (not yet implemented)
/test-50k Could be ported (not yet implemented)
/test-self-report-attributes-panic Go-specific — uses panic() recovery
/test-cerror-stacktrace-wrapped Go-specific — uses NewStackTraceErrorf API
/test-cerror-multiple Go-specific — uses Gin ctx.Error() multi-error pattern
/test-cerror-nested Could be ported (not yet implemented)
/metrics Go-specific — uses PrintCollectionFrameMetrics API

Key Differences

Aspect Go devtesting NestJS devtesting
DB layer SQLite in-memory with tracewaydb wrapper In-memory array with @Span() decorators
DB tracing Automatic via tracewaydb Manual via @Span() on service methods
Panic handling traceway.Recover() + panic endpoints NestJS exception filters (no panic concept)
Error wrapping traceway.NewStackTraceErrorf Native JS Error.cause chaining
Middleware traceway_gin.Use(router, ...) TracewayMiddleware applied via NestModule.configure()
Exception filter Gin recovery middleware TracewayExceptionFilter as global APP_FILTER

Project Structure

src/
├── main.ts                  # Bootstrap, listens on PORT
├── app.module.ts            # Root module — TracewayModule, middleware, exception filter
├── app.controller.ts        # 14 test endpoints
├── app.service.ts           # TracewayService usage (spans, tasks, errors)
└── users/
    ├── users.module.ts      # Users feature module
    ├── users.controller.ts  # CRUD endpoints
    ├── users.service.ts     # In-memory store with @Span() decorators
    └── user.entity.ts       # User, CreateUserDto, UpdateUserDto interfaces