TraceFlow
Request-level tracing for Express applications. Capture incoming requests automatically and use their timing and response data to investigate issues.
Introduction
TraceFlow is an observability SDK for Node and Express applications. Its Express middleware automatically creates a trace for each incoming request.
A trace records what happened to one request, including its method, path, timing, response status, and whether it succeeded. Those traces are sent to TraceFlow so you can review request behavior in the dashboard.
Express middleware
Capture each incoming Express request with one middleware.
Request traces
See method, path, status code, and request duration.
Dashboard visibility
Review the traces your application sends to TraceFlow.
Installation
Install the TraceFlow Express/Node SDK in the Express application you want to observe.
1npm install traceflow-express-sdk@latestExpress SDK
Initialize SDK
Initialize TraceFlow before registering its middleware. TraceFlow.initauthenticates the project and returns the middleware to register with Express.
1import express from "express";2import { TraceFlow } from "traceflow-express-sdk";3 4const app = express();5 6const traceFlowMiddleware = await TraceFlow.init({7 apiKey: process.env.TRACEFLOW_API_KEY!,8 endpoint: process.env.TRACEFLOW_BACKEND_ENDPOINT!9});10 11app.use(traceFlowMiddleware);12 13app.get("/users", (req, res) => {14 res.json({ users: [] });15});Keep your API key server-side
Automatic Tracing
The middleware automatically creates one trace for every incoming Express request. A trace represents the whole request: for example, GET /usersthat returns 200 in 10ms.
TraceFlow captures request-level details such as the HTTP method, path, start and end times, duration, status code, success or failure, middleware duration, and a spans array. Error information is included when it is available on the trace.
Why traces matter
GET /orders returns 500 after 842ms, the trace gives you one record to inspect for that request. This makes it easier to find slow or failing routes, unusual response times, and the endpoint behind a problem.Automatic HTTP Instrumentation
TraceFlow automatically records outgoing HTTP requests as spans inside the active request trace. Once the SDK is initialized, you can inspect captured HTTP calls without manually wrapping each call in a custom span.
Each recorded HTTP span is shown separately in the Request Journey. When the captured metadata is available, the span can show the destination path, HTTP method, response status, elapsed time, and error information. This helps you spot which external request took the time, instead of seeing only the total duration of the incoming Express request.
1app.get("/pokemon", async (req, res) => {2 // TraceFlow records outgoing HTTP calls automatically.3 const response = await fetch("https://example.com/api/pokemon");4 const data = await response.json();5 6 res.json(data);7});Open a trace in the dashboard and select an HTTP request span to inspect its recorded path and timing details. If a request contains multiple HTTP calls, each captured call appears as its own span, so you can compare their durations and investigate the slow operation.
What gets recorded
Timing interpretation
Custom Spans
Custom spans let you record a specific operation inside an automatically captured request trace. Use them for work such as database queries, external API calls, cache operations, or important application logic.
Start a span with traceflow.span(), give it a name, run your operation, and call end() when the operation finishes. TraceFlow records the completed span in the current request's trace.
1const traceflow = TraceFlow;2 3app.get("/users", async (req, res) => {4 const dbSpan = traceflow.span("database query");5 6 const users = await User.find();7 8 dbSpan.end();9 10 res.json({ users });11});The span name is up to you. Keep it short and descriptive so it is easy to understand when looking at a trace.
1const span = traceflow.span("fetch user");2 3const user = await fetchUser();4 5span.end();Span lifecycle
traceflow.span("name") starts timing the operation. Calling end() completes it and adds the span to the current trace. If the request has no active TraceFlow trace, there is nothing to record.What appears in the dashboard
Dashboard
Once the SDK sends traces, they appear in the TraceFlow dashboard. The trace list is useful for quickly scanning incoming requests.
Trace entries include useful request information such as the method and route, status code, duration, and timestamp. For example: GET /users,200 · Success, and 10ms. Use the list to identify requests that deserve a closer look.