⌘K
Express SDK
documentation

TraceFlow

Request-level tracing for Express applications. Capture incoming requests automatically and use their timing and response data to investigate issues.

Introduction

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.

Getting Started

Installation

Install the TraceFlow Express/Node SDK in the Express application you want to observe.

terminal
1npm install traceflow-express-sdk@latest

Express SDK

This package provides the TraceFlow initialization function and Express middleware used in the next step.
Getting Started

Initialize SDK

Initialize TraceFlow before registering its middleware. TraceFlow.initauthenticates the project and returns the middleware to register with Express.

server.ts
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

The API key identifies and authenticates your project. Keep it in server-side environment variables; do not expose it in client-side code or commit it to source control.
Tracing

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

If 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.
Tracing

Custom Spans

A trace is the complete request. A span is one piece of work inside that request, such as authenticating a user, querying a database, or calculating an order total.

conceptual request breakdown
1GET /orders — 900ms
2├── database query — 760ms
3├── business logic — 100ms
4└── response — 40ms

Traces answer, “The request was slow.” Spans can answer, “Why was it slow?” by showing the timing of individual operations.

Custom spans are coming soon

Traces are available today and automatically capture incoming Express requests. Custom spans will make it possible to break a request into individual operations for a more detailed timing view.
  • Custom application spans
  • Detailed operation timing
  • Nested span visualization
Product

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.