The only tool you need to know what is happening and how to fix it.
Traceway SDK Integration Testing API Specification
Environment Variables
| Variable | Default | Description |
|---|---|---|
PORT |
8080 |
Port the test app listens on |
TRACEWAY_ENDPOINT |
default_token_change_me@http://localhost:8082/api/report |
Traceway connection string (<token>@<server_url>) |
Running Test Apps
Go Frameworks
# Gin
cd testing/go/gin && go run .
# Chi
cd testing/go/chi && go run .
# Stdlib (net/http)
cd testing/go/stdlib && go run .
# Fiber
cd testing/go/fiber && go run .
# Fasthttp
cd testing/go/fasthttp && go run .
JS Frameworks
# Express
cd testing/js/express && npm install && npm run dev
# NestJS
cd testing/js/nestjs && npm install && npm run dev
# Next.js
cd testing/js/nextjs && npm install && npm run dev
# Remix
cd testing/js/remix && npm install && npm run dev
Endpoints
All endpoints use http://localhost:8080 as the base URL (configurable via PORT).
For Next.js and Remix, all endpoints are prefixed with /api/ (e.g., /api/test-ok instead of /test-ok).
1. GET /test-ok
Purpose: Basic transaction tracking - verifies the SDK captures a successful HTTP request.
Expected Response:
{"status": "ok"}
Status: 200
curl:
curl http://localhost:8080/test-ok
Verification:
transactionstable: row with matchingendpoint=GET /test-ok,status_code=200- Duration should be non-zero
2. GET /test-not-found
Purpose: Error status code tracking - verifies the SDK captures non-200 status codes.
Expected Response:
{"status": "not-found"}
Status: 404
curl:
curl http://localhost:8080/test-not-found
Verification:
transactionstable: row withendpoint=GET /test-not-found,status_code=404
3. GET /test-exception
Purpose: Panic recovery and uncaught exception capture.
Expected Response: Status 500 (body varies by framework)
curl:
curl http://localhost:8080/test-exception
Verification:
exceptions_v2table: row withstack_tracecontaining the panic/Error type and"test panic from /test-exception"- Stack trace should be present
transactionstable: row withstatus_code=500
4. GET /test-error-simple
Purpose: Explicit error capture with a plain error (no stack trace attached).
Expected Response:
{"error": "simple error"}
Status: 500
curl:
curl http://localhost:8080/test-error-simple
Verification:
exceptions_v2table: row withstack_tracecontaining"simple error without stack"transactionstable: row withstatus_code=500
5. GET /test-error-stacktrace
Purpose: Error capture with NewStackTraceErrorf (Go) or Error with stack (JS).
Expected Response:
{"error": "stacktrace error"}
Status: 500
curl:
curl http://localhost:8080/test-error-stacktrace
Verification:
exceptions_v2table: row withstack_tracecontaining"error with stack trace"- Stack trace should contain the handler function name
transactionstable: row withstatus_code=500
6. GET /test-error-wrapped
Purpose: Wrapped/chained error capture.
Expected Response:
{"error": "wrapped error"}
Status: 500
curl:
curl http://localhost:8080/test-error-wrapped
Verification:
exceptions_v2table: row withstack_tracecontaining"layer 2"and"base error"in the chain- Error chain should preserve wrapping (Go:
fmt.Errorf %w, JS:Error.cause) transactionstable: row withstatus_code=500
7. GET /test-error-nested
Purpose: 3-level nested function call error with stack trace from NewStackTraceErrorf (Go) or Error.captureStackTrace (JS).
Expected Response:
{"error": "nested error"}
Status: 500
curl:
curl http://localhost:8080/test-error-nested
Verification:
exceptions_v2table: row withstack_tracecontaining"error from inner function"- Stack trace should show
innerFunction,middleFunction,outerFunctionin the call chain transactionstable: row withstatus_code=500
8. GET /test-message
Purpose: Message capture via CaptureMessage / captureMessage.
Expected Response:
{"status": "message sent"}
Status: 200
curl:
curl http://localhost:8080/test-message
Verification:
exceptions_v2table: row withstack_trace="test message from /test-message"andis_message= truetransactionstable: row withstatus_code=200
9. GET /test-message-attributes
Purpose: Message capture with attributes. Tests CaptureMessageAttributes (Go) or plain captureMessage (JS - no attributes support).
Expected Response:
{"status": "message with attributes sent"}
Status: 200
curl:
curl http://localhost:8080/test-message-attributes
Verification:
exceptions_v2table: row withstack_trace="test message with attributes"- Go only:
tagsmap should containsource="test-message-attributes"andpriority="high" - JS limitation:
captureMessagedoes not support attributes; message is captured without custom tags
10. GET /test-spans
Purpose: Nested span capture via StartSpan/EndSpan within a request.
Expected Response:
{"status": "spans captured"}
Status: 200
curl:
curl http://localhost:8080/test-spans
Verification:
transactionstable: row withstatus_code=200andendpoint=GET /test-spans- The transaction should have associated spans:
db.queryspan (~50ms)cache.setspan (~20ms)http.external_apispan (~100ms)
- Total request duration should be >= 170ms
Note: For Fiber and Fasthttp, spans use context.Background() since these frameworks don't use context.Context natively, so spans won't be attached to the trace context automatically.
11. GET /test-task
Purpose: Background task measurement via MeasureTask / measureTask.
Expected Response:
{"status": "task started"}
Status: 200
curl:
curl http://localhost:8080/test-task
Verification:
transactionstable: a task record withendpoint="background-data-processor"should appear after the collection interval (default 5s)- The task should have a
processingspan (~200ms) - The task is async, so data may arrive in a subsequent collection frame
12. GET /test-metric
Purpose: Custom metric capture via CaptureMetric / captureMetric.
Expected Response:
{"status": "metric captured"}
Status: 200
curl:
curl http://localhost:8080/test-metric
Verification:
metric_recordstable: row withname="test.custom_metric"andvalue=42.0transactionstable: row withstatus_code=200
13. GET /test-attributes
Purpose: Exception capture with custom attributes map via CaptureExceptionWithAttributes / captureExceptionWithAttributes.
Expected Response:
{"status": "exception with attributes captured"}
Status: 200
curl:
curl http://localhost:8080/test-attributes
Verification:
exceptions_v2table: row withstack_tracecontaining"exception with custom attributes"tagsmap should contain:user_id="usr_123"request_id="req_456"env="testing"
transactionstable: row withstatus_code=200
14. POST /test-recording
Purpose: Request body/header recording on error. Tests WithOnErrorRecording capturing request details when a panic occurs.
Request Body:
{"action": "panic", "data": "test payload"}
Expected Response: Status 500 (panic response)
curl (trigger panic with recording):
curl -X POST http://localhost:8080/test-recording \
-H "Content-Type: application/json" \
-H "X-Custom-Header: test-value" \
-d '{"action": "panic", "data": "test payload"}'
curl (normal request):
curl -X POST http://localhost:8080/test-recording \
-H "Content-Type: application/json" \
-d '{"action": "ok", "data": "test payload"}'
Normal response:
{"status": "ok", "received": {"action": "ok", "data": "test payload"}}
Verification (panic case):
exceptions_v2table: row withstack_tracecontaining"panic triggered by /test-recording"tagsmap should contain recorded request details (depending on framework recording support):- URL/path information
- Request body content
- Request headers
transactionstable: row withstatus_code=500
Note: Request recording is a Go SDK middleware feature (WithOnErrorRecording). JS frameworks capture request details manually in error handlers.
Framework Matrix
| Feature | Gin | Chi | Stdlib | Fiber | Fasthttp | Express | NestJS | Next.js | Remix |
|---|---|---|---|---|---|---|---|---|---|
| Auto transaction tracking | Middleware | Middleware | Middleware | Middleware | Middleware | Manual | Manual | Manual | Manual |
| Panic/exception recovery | Middleware | Middleware | Middleware | Middleware | Middleware | Error handler | Exception filter | Wrapper | Wrapper |
| Context-based spans | Yes | Yes | Yes | No* | No* | Manual | Manual | Manual | Manual |
CaptureMessageAttributes |
Yes | Yes | Yes | Yes | Yes | No** | No** | No** | No** |
| Request recording on error | Middleware | Middleware | Middleware | Middleware | Middleware | Manual | Manual | Manual | Manual |
| Error via framework API | ctx.Error() |
Manual | Manual | Return err | Manual | Throw | Throw | Throw | Throw |
* Fiber and Fasthttp don't have native context.Context in handlers; spans use context.Background().
** JS SDK captureMessage does not have an attributes parameter; messages are captured without custom tags.
Verification Guide
1. Start Backend
cd backend && go run .
2. Start Test App
cd testing/go/gin && go run .
3. Run All Endpoints
BASE=http://localhost:8080
curl $BASE/test-ok
curl $BASE/test-not-found
curl $BASE/test-exception
curl $BASE/test-error-simple
curl $BASE/test-error-stacktrace
curl $BASE/test-error-wrapped
curl $BASE/test-error-nested
curl $BASE/test-message
curl $BASE/test-message-attributes
curl $BASE/test-spans
curl $BASE/test-task
curl $BASE/test-metric
curl $BASE/test-attributes
curl -X POST $BASE/test-recording -H "Content-Type: application/json" -d '{"action":"panic","data":"test"}'
4. Wait for Collection
Wait at least 10 seconds for the SDK to rotate collection frames and upload data.
5. Query Backend API
Check transactions:
curl -H "Authorization: Bearer <jwt>" \
"http://localhost:8082/api/transactions?projectId=<project-id>"
Check exceptions:
curl -H "Authorization: Bearer <jwt>" \
"http://localhost:8082/api/exception-stack-traces/grouped?projectId=<project-id>"
Check metrics (dashboard):
curl -H "Authorization: Bearer <jwt>" \
"http://localhost:8082/api/dashboard?projectId=<project-id>"
ClickHouse Tables Reference
| Table | Data From Endpoints |
|---|---|
endpoints_v2 / tasks_v2 |
All endpoints (1-14) generate transaction records |
exceptions_v2 |
Endpoints 3-9, 13-14 generate exception/message records |
metric_records |
Endpoint 12 generates custom metric + automatic system metrics |