Spry First‑Party Middleware Helpers: Timing and Request ID

Learn how to use Spry’s new built‑in timing and request‑ID middleware to monitor performance and trace requests in your Dart server applications.

Spry 8.3.0 introduced two new first‑party middleware helpers that make it easier to add observability and traceability to your server: timing() and requestId(). These helpers are part of Spry’s growing suite of built‑in middleware that let you add essential functionality without installing extra packages.

In this tutorial, you’ll learn:

What the timing and request‑ID middleware do and why they’re useful
How to install and enable them in your Spry application
Practical examples of using each helper in real‑world scenarios
How to combine them with other middleware for full‑stack observability
Best practices for monitoring and debugging with these helpers

Why Timing and Request ID Matter

Before we dive into the code, let’s understand why these two helpers are important.

Timing Middleware

The timing() middleware measures how long your request‑handling pipeline takes and adds a Server‑Timing header to the response. This header is a standard way to report performance metrics that can be picked up by browser DevTools, monitoring dashboards, or logging systems.

Benefits:

Real‑time performance visibility – see how long each request takes in production
Standard‑compliant – uses the W3C Server‑Timing header format
Lightweight – adds minimal overhead (just a Stopwatch)

Request‑ID Middleware

The requestId() middleware generates a unique identifier for each incoming request and makes it available throughout the request lifecycle. You can use it to correlate logs, errors, and downstream service calls.

Benefits:

End‑to‑end tracing – follow a request across microservices and logs
Flexible ID generation – use the built‑in generator or supply your own
Trust incoming IDs – optionally reuse IDs from upstream services (useful in distributed traces)

Installing the Helpers

These helpers are part of Spry core, so you don’t need to install anything extra. Make sure you’re using Spry ≥ 8.3.0.

// pubspec.yaml
dependencies:
  spry: ^8.3.0

Run dart pub get and you’re ready to go.

Using the Timing Middleware

The timing() middleware is a single function that returns a Spry middleware. You can add it anywhere in your middleware stack, but it’s usually placed early so it measures the entire downstream processing.

Basic Example

import 'package:spry/spry.dart';
import 'package:spry/middleware.dart';

void main() async {
  final spry = Spry();

  // Add timing middleware with default settings
  spry.use(timing());

  spry.get('/', (request) => 'Hello, world!');

  await spry.listen(port: 3000);
}

Now every response will include a Server‑Timing header:

Server-Timing: app;dur=12.5

The default metric name is app, and the duration is reported in milliseconds with one decimal place.

Customizing the Metric

You can change the metric name and the number of decimal places:

spry.use(timing(
  metricName: 'myapp',
  fractionDigits: 3,
));

Now the header will look like myapp;dur=12.345.

Accessing the Timing Value in Your Handlers

The middleware only adds the header; it doesn’t expose the measured time to your handlers. If you need the elapsed time inside a route, you can implement a custom version that stores the Stopwatch in request.locals. Here’s an example:

Middleware customTiming({String metricName = 'app', int fractionDigits = 1}) {
  return (event, next) async {
    final stopwatch = Stopwatch()..start();
    final response = await next();
    stopwatch.stop();

    // Store the elapsed microseconds in locals for later use
    event.locals.set(#timingElapsedMicroseconds, stopwatch.elapsedMicroseconds);

    response.headers.append(
      'server-timing',
      _formatServerTimingMetric(
        metricName,
        stopwatch.elapsedMicroseconds,
        fractionDigits,
      ),
    );

    return response;
  };
}

// Later in a route handler:
spry.get('/debug', (request) {
  final elapsed = request.locals.get<int>(#timingElapsedMicroseconds);
  return 'Request took ${elapsed! / 1000} ms';
});

Using the Request‑ID Middleware

The requestId() middleware generates a unique ID for each request and makes it available via request.locals. It also sets the ID in a response header (default X‑Request‑ID).

Basic Example

import 'package:spry/spry.dart';
import 'package:spry/middleware.dart';

void main() async {
  final spry = Spry();

  // Add request‑ID middleware with default settings
  spry.use(requestId());

  spry.get('/', (request) => 'Hello, world!');

  await spry.listen(port: 3000);
}

Now each request will receive an X‑Request‑ID header in the response, e.g.:

X-Request-ID: 1h3e5a2-7f8g9i0

Accessing the Request ID in Handlers

You can retrieve the generated ID inside any route or middleware using the useRequestId helper:

import 'package:spry/spry.dart';
import 'package:spry/middleware.dart';

void main() async {
  final spry = Spry();
  spry.use(requestId());

  spry.get('/debug', (request) {
    final id = useRequestId(request);
    return 'Request ID: $id';
  });

  await spry.listen(port: 3000);
}

Customizing the Request‑ID Generation

You can supply your own ID generator:

spry.use(requestId(
  headerName: 'x-correlation-id',
  generator: (event) => '${DateTime.now().millisecondsSinceEpoch}-${event.request.method}',
  trustIncoming: false, // ignore incoming IDs, always generate a new one
));

Trusting Incoming Request IDs

In a microservices architecture, you often want to propagate the same ID across service boundaries. Set trustIncoming: true (the default) and the middleware will reuse the ID from the incoming header if present.

spry.use(requestId(
  trustIncoming: true,
  headerName: 'x-request-id',
));

Now if the client sends an X‑Request‑ID header, that same value will be used throughout the request and returned in the response.

Combining Timing and Request ID

You can (and should) use both middleware together to get a complete picture of each request.

void main() async {
  final spry = Spry();

  // Order matters: request ID first, then timing
  spry.use(requestId());
  spry.use(timing());

  spry.get('/', (request) => 'Hello, world!');

  await spry.listen(port: 3000);
}

Now each response will include both headers:

X-Request-ID: 1h3e5a2-7f8g9i0
Server-Timing: app;dur=12.5

Logging with Both Helpers

A common pattern is to log each request with its ID and duration. Here’s a simple logging middleware that uses both values:

Middleware logging() {
  return (event, next) async {
    final id = useRequestId(event) ?? 'none';
    print('[$id] ${event.request.method} ${event.request.uri}');

    final stopwatch = Stopwatch()..start();
    final response = await next();
    stopwatch.stop();

    print('[$id] ${response.statusCode} ${stopwatch.elapsedMilliseconds}ms');
    return response;
  };
}

void main() async {
  final spry = Spry();
  spry.use(requestId());
  spry.use(timing());
  spry.use(logging());

  spry.get('/', (request) => 'Hello, world!');

  await spry.listen(port: 3000);
}

Advanced Use Cases

Integrating with OpenTelemetry

If you’re using OpenTelemetry for distributed tracing, you can bridge Spry’s request ID with the OpenTelemetry trace context.

import 'package:opentelemetry/opentelemetry.dart';

Middleware openTelemetryBridge() {
  return (event, next) async {
    final id = useRequestId(event);
    if (id != null) {
      // Set the request ID as a baggage item or trace attribute
      final span = Span.current;
      span?.setAttribute('request.id', id);
    }
    return next();
  };
}

Monitoring with Prometheus / Grafana

You can export timing metrics to Prometheus using the prometheus_client package.

import 'package:prometheus_client/prometheus_client.dart';

final histogram = Histogram(
  'http_request_duration_seconds',
  'HTTP request duration in seconds',
  labelNames: ['method', 'path'],
);

Middleware prometheusTiming() {
  return (event, next) async {
    final stopwatch = Stopwatch()..start();
    final response = await next();
    stopwatch.stop();

    histogram.labels(
      event.request.method,
      event.request.uri.path,
    ).observe(stopwatch.elapsedMicroseconds / 1e6);

    return response;
  };
}

Error Tracking with Sentry / Rollbar

When an error occurs, you can attach the request ID to the error report for easier debugging.

Middleware errorTracking() {
  return (event, next) async {
    try {
      return await next();
    } catch (e, stack) {
      final id = useRequestId(event);
      Sentry.captureException(
        e,
        stackTrace: stack,
        hint: Hint.withMap({'request_id': id}),
      );
      rethrow;
    }
  };
}

Best Practices

Place middleware early – Add requestId() and timing() near the top of your middleware stack so they capture the entire request lifecycle.
Use consistent header names – If you’re working with other services, agree on a common header name (e.g., X‑Request‑ID or X‑Correlation‑ID) and set headerName accordingly.
Trust incoming IDs in distributed systems – When your service is part of a larger chain, set trustIncoming: true to maintain end‑to‑end traceability.
Combine with structured logging – Log the request ID and timing in every log line so you can filter logs by request.
Export timing metrics – Besides the Server‑Timing header, consider exporting timing data to a monitoring system like Prometheus, Datadog, or New Relic.
Test your middleware – Write unit tests for your custom generators and verify headers are set correctly.

Conclusion

Spry’s first‑party timing() and requestId() middleware are small but powerful additions that can significantly improve the observability of your Dart server applications. With just a few lines of code, you gain request‑level tracing and performance monitoring that scales from development to production.

Try them out in your next Spry project and see how much easier it becomes to debug and optimize your APIs.

Spry First‑Party Middleware Helpers: Timing and Request ID

Spry First‑Party Middleware Helpers: Timing and Request ID

Why Timing and Request ID Matter

Timing Middleware

Request‑ID Middleware

Installing the Helpers

Using the Timing Middleware

Basic Example

Customizing the Metric

Accessing the Timing Value in Your Handlers

Using the Request‑ID Middleware

Basic Example

Accessing the Request ID in Handlers

Customizing the Request‑ID Generation

Trusting Incoming Request IDs

Combining Timing and Request ID

Logging with Both Helpers

Advanced Use Cases

Integrating with OpenTelemetry

Monitoring with Prometheus / Grafana

Error Tracking with Sentry / Rollbar

Best Practices

Conclusion

Further Reading

Comments

More from this blog

Spry Database Integration: PostgreSQL, SQLite, MySQL, and Connection Pooling

Spry Client Generation: First‑Party Type‑Safe Dart SDKs

Spry API Design: RESTful, GraphQL, and RPC Patterns

Spry Advanced Patterns Part 2: Modular Architecture, Real‑World Examples, and Best Practices

Spry Advanced Patterns Part 1: Middleware, Dependency Injection, and Plugin Architecture

Command Palette

Spry First‑Party Middleware Helpers: Timing and Request ID

Why Timing and Request ID Matter

Timing Middleware

Request‑ID Middleware

Installing the Helpers

Using the Timing Middleware

Basic Example

Customizing the Metric

Accessing the Timing Value in Your Handlers

Using the Request‑ID Middleware

Basic Example

Accessing the Request ID in Handlers

Customizing the Request‑ID Generation

Trusting Incoming Request IDs

Combining Timing and Request ID

Logging with Both Helpers

Advanced Use Cases

Integrating with OpenTelemetry

Monitoring with Prometheus / Grafana

Error Tracking with Sentry / Rollbar

Best Practices

Conclusion

Further Reading

Comments

More from this blog