# lum_request-stats

> Get stats on your Node.js HTTP server requests

Latest version **3.2.0** (published 2021-03-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install lum_request-stats
pnpm add lum_request-stats
yarn add lum_request-stats
bun add lum_request-stats
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.2.0 |
| Published | 2021-03-25 |
| First published | 2021-03-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.12 |
| Dependencies | 2 |
| Unpacked size | 20.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 77 |
| Author | Thomas Watson Steen |
| Maintainers | luminati.io |
| Keywords | stats, statistics, http, https, middleware, connect, express, analytics |

## Links

- npm: https://www.npmjs.com/package/lum_request-stats
- Repository: https://github.com/watson/request-stats
- Issues: https://github.com/watson/request-stats/issues
- npm.io page: https://npm.io/package/lum_request-stats

## Dependencies (2)

- [once](https://npm.io/package/once.md) ^1.4.0
- [http-headers](https://npm.io/package/http-headers.md) ^3.0.1

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 3.2.0 (latest) — 2021-03-25
- 3.1.0 — 2021-03-25

## README

# request-stats

[![Build status](https://travis-ci.org/watson/request-stats.svg?branch=master)](https://travis-ci.org/watson/request-stats)
[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://github.com/feross/standard)

Get stats on your Node.js HTTP server requests.

Emits two events:

- `request` when ever a request starts: Passes a [Request object](#request-object) that can later be used to [query for the progress](#progress) of a long running request
- `complete` when ever a request completes: Passes a [stats object](#oncomplete-callback) containing the overall stats for the entire HTTP request

## Installation

```
npm install request-stats --save
```

## Example usage

Get stats for each completed HTTP request:

```javascript
var requestStats = require('request-stats')
var server = http.createServer(...)

requestStats(server, function (stats) {
  // this function will be called every time a request to the server completes
  console.log(stats)
})
```

Get periodic stats for long running requests:

```javascript
var server = http.createServer(...)

var stats = requestStats(server)

stats.on('request', function (req) {
  // evey second, print stats
  var interval = setInterval(function () {
    var progress = req.progress()
    console.log(progress)
    if (progress.completed) clearInterval(interval)
  }, 1000)
})
```

## API

### Constructor

#### `requestStats(server[, callback])`

Attach request-stats to a HTTP server.

Initialize request-stats with an instance a HTTP server. Returns a
StatsEmitter object. Optionally provide a callback which will be called
for each completed HTTP request with a stats object (see stats object
details below).

If no callback is provided, you can later attach a listener on the
"complete" event.

#### `requestStats(req, res[, callback])`

Attach request-stats to a single HTTP request.

Initialize request-stats with an instance a HTTP request and response.
Returns a StatsEmitter object. Optionally provide a callback which will
be called with a stats object when the HTTP request completes (see stats
object details below).

If no callback is provided, you can later attach a listener on the
"complete" event.

### StatsEmitter object

#### `.on('complete', callback)`

Calls the callback function with a stats object when a HTTP request
completes:

```javascript
{
  ok: true,           // `true` if the connection was closed correctly and `false` otherwise
  time: 0,            // The milliseconds it took to serve the request
  req: {
    bytes: 0,         // Number of bytes sent by the client
    headers: { ... }, // The headers sent by the client
    method: 'POST',   // The HTTP method used by the client
    path: '...',      // The path part of the request URL
    ip: '...',        // The remote ip
    raw: [Object]     // The original `http.IncomingMessage` object
  },
  res: {
    bytes: 0,         // Number of bytes sent back to the client
    headers: { ... }, // The headers sent back to the client
    status: 200,      // The HTTP status code returned to the client
    raw: [Object]     // The original `http.ServerResponse` object
  }
}
```

#### `.on('request', callback)`

Calls the callback function with a special [Request
object](#request-object) when a HTTP request is made to the server.

### Request object

The Request object should not be confused with the Node.js
[http.IncomingMessage](http://nodejs.org/api/http.html#http_http_incomingmessage)
object. The request-stats Request object provides only a single
but powerfull function:

#### `.progress()`

Returns a progress object if called while a HTTP request is in progress.
If called multiple times, the returned progress object will contain the
delta of the previous call to `.progress()`.

```javascript
{
  completed: false, // `false` if the request is still in progress
  time: 0,          // The total time the reuqest have been in progress
  timeDelta: 0,     // The time since previous call to .progress()
  req: {
    bytes: 0,       // Total bytes received
    bytesDelta: 0,  // Bytes received since previous call to .progress()
    speed: 0,       // Bytes per second calculated since previous call to .progress()
    bytesLeft: 0,   // If the request contains a Content-Size header
    timeLeft: 0     // If the request contains a Content-Size header
  },
  res: {
    bytes: 0,       // Total bytes send back to the client
    bytesDelta: 0,  // Bytes sent back to the client since previous call to .progress()
    speed: 0        // Bytes per second calculated since previous call to .progress()
  }
}
```

## Acknowledgement

Thanks to [mafintosh](https://github.com/mafintosh) for coming up with
the initial concept and pointing me in the right direction.

## License

MIT

---
_Source: https://npm.io/package/lum_request-stats · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._