strong-trace/transactionlog.md

StrongTrace Node.js Tracer

transactionlog
===

Logs transactions (by string id) and collects stats over time about them. This tool is part of the StrongTrace node.js instrumentation.

```js
var TransactionLog = require("./transactionlog")
var tlog = new TransactionLog({
  raw_subset: true,
  subset_stats: true,
  transactions_per_ms: true
})

tlog.update("/index.html", 13)
tlog.update("/index.html", 22)
tlog.update("/user/foo?blah=zap", 101)

var subset = tlog.reapSubset()
console.log(JSON.stringify(subset, null, 2))

/*
{
  "start": 1403045590568,
  "end": 1403045590569,
  "transactions": {
    "/index.html": {
      "stats": {
        "n": 2,
        "min": 13,
        "max": 22,
        "sum": 35,
        "mean": 17.5,
        "variance": 20.25,
        "standard_deviation": 4.5
      },
      "subset": [
        13,
        22
      ],
      "subset_stats": {
        "n": 2,
        "min": 13,
        "max": 22,
        "sum": 35,
        "mean": 17.5,
        "variance": 20.25,
        "standard_deviation": 4.5
      },
      "transactions_per_ms": {
        "n": 1,
        "min": 2,
        "max": 2,
        "sum": 2,
        "mean": 2,
        "variance": 0,
        "standard_deviation": 0
      }
    },
    "/user/foo?blah=zap": {
      "stats": {
        "n": 1,
        "min": 101,
        "max": 101,
        "sum": 101,
        "mean": 101,
        "variance": 0,
        "standard_deviation": 0
      },
      "subset": [
        101
      ],
      "subset_stats": {
        "n": 1,
        "min": 101,
        "max": 101,
        "sum": 101,
        "mean": 101,
        "variance": 0,
        "standard_deviation": 0
      },
      "transactions_per_ms": {
        "n": 1,
        "min": 1,
        "max": 1,
        "sum": 1,
        "mean": 1,
        "variance": 0,
        "standard_deviation": 0
      }
    }
  }
}
*/

setTimeout(function () {
  tlog.update("/index.html", 50)
  var subset = tlog.reapSubset()
  console.log(JSON.stringify(subset, null, 2))
}, 1000)

/*
{
  "start": 1403045590568,
  "end": 1403045591581,
  "transactions": {
    "/index.html": {
      "stats": {
        "n": 3,
        "min": 13,
        "max": 50,
        "sum": 85,
        "mean": 28.333333333333336,
        "variance": 248.2222222222222,
        "standard_deviation": 15.755069730795297
      },
      "subset": [
        50
      ],
      "subset_stats": {
        "n": 1,
        "min": 50,
        "max": 50,
        "sum": 50,
        "mean": 50,
        "variance": 0,
        "standard_deviation": 0
      },
      "transactions_per_ms": {
        "n": 2,
        "min": 0.0009871668311944718,
        "max": 2,
        "sum": 2.0009871668311945,
        "mean": 1.0004935834155972,
        "variance": 0.9990130767933937,
        "standard_deviation": 0.9995064165844028
      }
    }
  }
}
*/

```

API
===

`var transactionLog = require("concurix-transactionlog")(config)`
---

Create a new transaction log

config:
  * raw_subset [false]: show the raw values for each member of this subset
  * subset_stats: [true]: show stats for just this subset
  * transactions_per_ms: [true]: show transactions per millisecond stats

`transactionLog.update(transactionId, measurement)`
---

Log an instance of this transaction. `transactionId` should be a string and `measurement` should be a number.

`transactionLog.reapSubset()`
---

Extract the current subset of the transaction log and clear the subset buffer.

When reaped, statistics for each transaction id that was **active** in this subset is returned, with optional fields depending on the `config` provided.
  * stats: statistics for this tansaction id for all history
  * subset: raw values for this subset
  * subset_stats: statistics for just this subset
  * transactions_per_ms: Instances of this transaction id per millisecond, sampled at each `reapSubset()` call for all history.

Long-term stats are kept intact between `reapSubset` calls.

`transactionLog.clearAll()`
---

Completely empty the transaction log of all transactions and long-term stats.