Joining a pair you have

One pair of indexes can serve several sites on several machines. Every record carries the virtual host it came from, so six machines reporting into one pair stay separable in the panel — two indexes and six hostnames, rather than twelve indexes.

Before offering to create anything, setup reads your account once and groups what comes back into Loghound pairs. Pairs are listed and chosen as pairs, never as halves:

aaaa1111   loghound_aaaa1111_hits + loghound_aaaa1111_sessions

Choosing one does four things, each with its own result:

1. Confirms the pair is still on the account — the list is an offer, never evidence.
2. Reads the connection details.
3. Checks the indexes have the shape this version writes, by fetching the live schema and comparing its declared field names against this release’s, field by field.
4. Queries both to prove Loghound can reach and authenticate to them.

Unattended, the same thing is LOGHOUND_OPENSOLR_REUSE=aaaa1111 — see unattended installs. It defaults to new, so an unattended re-run never adopts another site’s indexes merely because it found some.

This is the check that runs when you join a pair. The equivalent check for a pair you are already using, after a code upgrade, is bin/loghound-schema — the same comparison, run against the indexes this installation already writes to.

The shape check is a comparison rather than a version marker, because a marker has to be remembered and bumped by hand, and the day somebody forgets is the day the check says yes to an index it should have refused. Fields this version writes that the index lacks stop the run and are named. The configset is pushed only on an explicit agreement from you, and that is additive — it only ever adds fields, and it does not alter or remove a single document already in the index. Unattended, that agreement is LOGHOUND_OPENSOLR_UPGRADE_SCHEMA=yes.

A live schema that cannot be read, or that parses to no fields at all, is treated as unreadable and stops the run — never as a match.

A _hits with no _sessions, or the reverse, is what a setup run that died between the two creates leaves behind. It is reported as exactly that, with the name of the index and the name of the one it is missing.

It cannot be joined — half a pair is not somewhere Loghound can work — and it holds no usable data on its own, but it still counts against your plan’s index limit. Delete it in your Opensolr control panel, or leave it and create a new pair. Loghound will not touch it either way.

• Session ids cannot collide. A log-backed id is a SHA-1 over the client key, the first timestamp and sixteen random bytes; a beacon-minted one is a marker plus twenty random bytes.
• Hit ids cannot collide either, but only because the installation id is in them. Two machines both tailing /var/log/apache2/access.log produce identical source-and-offset pairs, and a Solr update with a duplicate key is a delete-and-add — so without the installation id each machine would have silently overwritten the other’s traffic, one request at a time, with no error anywhere.
• An installation field names the writer on both cores. It is not how the panel separates sites — that is the hostname, and a shared pair is meant to read as one dashboard. It exists so a destructive operation can be scoped: the retention job detects a shared pair from it and deletes only its own documents, and if it cannot name its own documents it refuses to run rather than guessing.
• The daily rollup converges rather than forking. Every installation recomputes a whole day from every session document and writes it at the same deterministic id, so they all compute the same numbers. An atomic increment would have each installation add its own sessions to a shared counter and inflate the day by the number of writers.