Behaviour norms

norms lets your app learn what normal looks like for itself, by hour of week. When a metric leaves that range and stays out, it emits one anomaly.detected signal.

norms:
  season: hour-of-week
  tz: Asia/Kolkata
  learn: 7d
  min-samples: 20                      # observations a bucket needs before it speaks
  persist: 5m                          # how often the model is stored, 1s to 24h

import { norms } from "mainsdk";

const n = await norms.get("requests");
console.log(n.bucket, n.p50, n.p99, n.learning);

norms:
  driver: builtin

Quick start

norms:
  season: hour-of-week
  tz: Asia/Kolkata
  learn: 7d

import { norms } from "mainsdk";

const n = await norms.get("requests");
console.log(n.bucket, n.p50, n.p99, n.learning);   // "mon-10" 118 240 true

Adding a norms section turns learning on. Without it nothing runs and norms.get throws MAIN-CONFIG-0003.

Configuration

norms:
  every: 1m                  # one value per metric per window; 1m to 15m
  season: hour-of-week       # hour-of-week (168 buckets) | hour-of-day (24) | none (1)
  tz: Asia/Kolkata           # time zone for buckets; default UTC
  learn: 7d                  # anomalies are info and learning: true until the model is this old; 0 to 28d
  min-samples: 30            # values a bucket needs before it is used; else hour-of-day, else global
  half-life: 14d             # how fast old behaviour fades, counted in visits to a bucket
  metrics: [cpu, loop, memory, requests, errors, latency]
  sensitivity: { z: 4, quantile: p99, margin: 20%, hold: 3 }   # hold: consecutive windows out of range
  persist: 5m

Calls

Signals

• anomaly.detected (subject metric:<name>): value, expected (mean, sd, p50, p99), bucket, score, direction (high or low), learning. Severity is high from a score of 8, medium from 6, else low, and info while learning. It is sent again each minute while the anomaly holds.
• anomaly.cleared after hold windows back in range.
• pressure.contention when loop delay is high while your own CPU is at or under its median: the instance is waiting on something else on the machine.

Helpers for wiring and tests

What you get

• A learner that is plain arithmetic: a decayed mean and variance and a decayed 48-bin histogram per hour of the week.
• A value out of range raises one signal with the value, the expected range and a score, and a playbook, a person or the advisor can then act.
• It is free.
• The same input gives the same model and the same signals.
• No dependency, no model and no service.
• Holds numbers only, never a person, a tenant or an address.
• Reads counters the SDK already keeps once a window, off the request path. A store that does not answer leaves the model in memory.

Errors and checks

• MAIN-NORMS-0001: a norms value is invalid (mainsdk check).
• MAIN-NORMS-0002: a metric's source is not available; it is skipped, logged once.
• MAIN-NORMS-0003: the stored model was another version or corrupt; it was discarded and learning restarted.
• MAIN-NORMS-0004: norms.delete refused, the caller lacks norms.manage (403).

Each code's cause and fix is in check codes.

Swapping drivers

norms has no drivers: the learner is built in, and persist sets how often the model is written to the runtime store.

Testing

createSim in @mainsdk/testing plays hours of traffic and CPU curves against an app in a second, on a fake clock, so you can assert what norms noticed. See testing.

npx mainsdk norms          # each metric's bucket, count, p50, p99 and learning state
npx mainsdk info --json    # the same under "norms"

Next

• Signals: where anomaly.detected goes.
• Playbooks: act on an anomaly.
• Testing kit: createSim and the fake clock.
• Check codes: each code's cause and fix.