Tuning the Loghound Scoring Weights

Weights live in the configuration, keyed by rule code. An empty map means the built-in weights are used, which is the right place to start.

'scoring' => [
    // Ships as 1. Bump it yourself when you change a weight by hand.
    'rule_version' => 1,
    'weights' => [
        // A technical audience blocks the beacon far more often than average.
        'no_js_on_html' => 40,
        // We are behind a corporate VPN; everyone's timezone is wrong.
        'tz_mismatch'   => 0,
    ],
    'thresholds' => [
        'bot' => 80, 'likely_bot' => 60, 'unknown' => 40, 'likely_human' => 20,
    ],
    // The five-address floor for the proxy fleet rule. Raise it on a site with a
    // large NATed corporate audience; lower it only if you like false positives.
    'fp_fleet_min_ips' => 5,
],

The identifiers are the ones on the identifiers and labels page.

01 · What the rules are about the rules

An unknown rule code is a hard error. The scorer throws rather than start with a typo’d key that silently does nothing, so a misspelt override stops the scorer instead of quietly leaving a rule at its default.
A weight is clamped to 0–200, so a deliberate override can exceed a hundred when you want one signal decisive on its own.
Setting a weight to 0 disables the rule, and its reason code stops being emitted — which is the intended behaviour, because a rule contributing nothing should not appear in the explanation.
Thresholds must descend. The panel form refuses a save where they do not.
The fleet floor has a minimum of 2 and is not in the shipped example configuration; add the key yourself if you want it.

What the panel form can and cannot reach

The scoring card in Settings edits weights and thresholds through a form, but its number inputs cap at a hundred and it does not expose the fleet floor. Anything beyond that has to be set in the file.

02 · Bump the rule version whenever you change a weight

It ships as 1, it is written onto every session document, and it is what lets you tell which ruleset produced a verdict and re-score a window under the new one instead of comparing incomparable numbers. Saving weights through the panel bumps it for you; changing the file by hand does not.

Existing documents are not rescored by either route

A weight change applies to sessions scored after it. That is why the version number is on the document: without it, a chart spanning the change would be averaging two different rulesets and nothing would say so.

03 · How to tune, in order

Run for a week without changing anything.
Open Bot forensics and look at the signal facet. The reason codes are ranked by how often they fire.
Take the most frequent one and pull twenty sessions that fired it. Read them.
If they are humans, lower that weight. If they are bots, leave it alone.
Bump the rule version. Write down what you changed and why.

Do not tune towards a bot percentage you expected

There is no correct number. Sites in the same industry, of the same size, legitimately differ by an order of magnitude — and tuning until the number looks reasonable is how you end up with a detector that reports whatever you already believed.

Two overrides worth considering before anything else, because they are the two most common genuine mismatches between the defaults and a real audience: lower the no-JS rule if your audience is technical and blocks the beacon far more than average, and zero the timezone rule if everybody reaches you through a corporate VPN. False positives is the catalogue of who else the defaults get wrong.

Tuning the weights