Designing What to Record
In this pack:
sizing,
notation,
rule strictness.
Overview
Records outlive the moment that produced them, so they are part of the
design and not an afterthought. This skill decides each record from the
question it must answer and the person who asks it, keeps audit records
with the acts they describe, gives each request one correlation
identifier, and keeps patients' details out of logs, metrics and
traces.
When to use
- A feature needs log records, metrics or traces and nobody has said
what each one is for.
- An incident cannot be explained from the records the system kept.
- Staff actions on patients' files need an audit trail.
- An error is logged in several layers as it passes through them.
- A log line, metric or trace carries a patient's name or clinical
details.
- The clinic asks for a count of outcomes, such as refused bookings.
When not to use
- The question is which error a method raises, or which caller handles
it. That is designing failure behaviour.
- The question is the history of an object's own status changes.
Modeling lifecycles, rule 6, covers it.
- The record is a domain event that other parts react to. That is
publishing domain events.
- The code is a short script or a test whose output nobody reads after
it ends.
Core rules
Rule. Decide each record from the question it must answer and the
person who asks it. The person on call asks why one request failed
and reads a log record. A practice manager asks how many bookings
were refused today and reads a metric. An auditor asks who recorded
a patient's allergy and when, and reads an audit record. A record
that answers no one's question is noise that hides the ones that do.
Rule. Keep an audit record as domain data, written by the
use-case object in the same transaction as the act it records, and
kept for as long as the clinic must answer for the act; never a log
line, which may be sampled, rotated or dropped. Modeling
lifecycles, rule 6, keeps the history of an object's own
transitions; an audit record covers any other act the clinic must
answer for, such as an allergy recorded in a patient's file. It is
stored with the act as the outbox is stored with a change, in one
transaction, as publishing domain events, rule 4, does.
Rule. Give each request one correlation identifier where it enters
the system, and carry it on every log record, message and event the
request causes. One incident can then be followed from its records
across threads and processes.
Default. Record a failure once, where it is handled: the handler
at the program's edge that turns a fault into a general failure, as
designing failure behaviour, rule 2, places it, writes one log
record with the correlation identifier and the error, and no layer
logs an error and raises it again. A failure logged at every layer
it passes reads as several failures.
The exception is an adapter that translates an outside system's
error: it records the original error before it raises the port's
own, because the original is lost after that.
Rule. Keep patients' personal and clinical details out of logs,
metrics and traces: record identities, such as a PatientId, and
outcomes, never names, contact details, diagnoses or notes. Those
records reach more people and live in more places than the patient's
file, and nobody checks who reads them the way the file is checked.
Default. Count with metrics: each outcome the clinic watches, such
as bookings made or refused, is a counter or a measured duration,
and each metric takes a few label values, such as the site, never a
patient or appointment identity, which would make one series per
patient.
The exception is a count needed once, for one investigation: query
the logs or the store for it instead of adding a metric.
Rule. Keep logging out of domain objects: a domain object raises
its refusals and records its domain events, and the application
service, the handler at the edge and the adapters write log
records. Where a test must check that a record is written, write
it through a port the domain owns, as inverting dependencies,
rule 1, asks.
Pattern
Before, the use-case object RecordAllergy stores the allergy and
writes a log line. That line carries the patient's name and the allergy,
a clinical detail; it is the only trace of who recorded the allergy, and
a log may be rotated away.
Before:
class RecordAllergy
- patients: Patients
- log: Log
+ new(patients: Patients, log: Log)
+ run(id: PatientId, allergy: Allergy, by: ClinicianId): void
raises AllergyAlreadyRecorded
patient := patients.find(id)
patient.record(allergy)
patients.save(patient)
log.write(patient.fullName(), allergy, by)
return
After, RecordAllergy stores the same patient and appends an
AllergyAuditEntry to the AuditTrail it is given, instead of writing
a log line.
After:
value AllergyAuditEntry
- patient: PatientId
- allergy: Allergy
- by: ClinicianId
- at: DateTime
+ new(patient: PatientId, allergy: Allergy, by: ClinicianId,
at: DateTime)
interface AuditTrail
+ append(entry: AllergyAuditEntry): void
class RecordAllergy
- patients: Patients
- audit: AuditTrail
- clock: Clock
+ new(patients: Patients, audit: AuditTrail, clock: Clock)
+ run(id: PatientId, allergy: Allergy, by: ClinicianId): void
raises AllergyAlreadyRecorded
patient := patients.find(id)
patient.record(allergy)
patients.save(patient)
audit.append(new AllergyAuditEntry(id, allergy, by, clock.now()))
return
Patient, its record command and the AllergyAlreadyRecorded error
are the encapsulating state and behaviour skill's, in its
guarding-collections.md reference; patient.fullName() is taken to
answer the patient's name. Patients is taken to be the patients'
repository, whose find answers the stored patient and whose save
stores it. Log.write is taken to write one log line. Clock is the
inverting dependencies skill's port, whose now() answers the current
time. The audit entry is an audit record, not a domain event.
The Before's log line has no place in the After: a failure is logged
once at the edge, as rule 4 says, and the audit entry answers the
auditor.
run stores the patient with the new allergy under its PatientId, in
the clinic's database, in the one transaction run opens and ends. The
After also stores one AllergyAuditEntry there, in that same
transaction. patient.record raises before save or append runs, so
a refused allergy stores neither the patient nor an entry. Each version
stores the patient once, and the After appends one entry for each
allergy recorded.
Red flags
Places to look, not verdicts. A red flag becomes a finding only with
evidence: a measurement, a reproducible bug, or a failing test.
- A log line that holds a patient's name, contact details or clinical
notes.
- An error logged at every layer it passes.
- A log message with no identity of the request, appointment or
patient.
- An audit question answered from the logs.
- A metric labelled with a patient or appointment identity.
- A domain object that writes to a logger.
Common mistakes
- Logging every step in case it is needed.
- Counting outcomes by searching the logs.
- Writing the audit record after the transaction commits, where a
failure loses it.
- Starting a new correlation identifier at each process the request
reaches.
- Keeping logs as long as audit records, or audit records as briefly as
logs.
Related skills
Further reading
- Logs, metrics and traces
- Audit records
1---2name: oo-designing-what-to-record3description: Use when deciding what to log, measure or trace, when an incident cannot be explained from the records, or staff actions need an audit trail.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-designing-what-to-record7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Designing What to Record1213**In this pack:**14[sizing](../oo-design/SKILL.md#how-much-design-a-task-warrants),15[notation](../oo-design/references/notation.md),16[rule strictness](../oo-design/SKILL.md#how-strictly-a-rule-is-meant).1718## Overview1920Records outlive the moment that produced them, so they are part of the21design and not an afterthought. This skill decides each record from the22question it must answer and the person who asks it, keeps audit records23with the acts they describe, gives each request one correlation24identifier, and keeps patients' details out of logs, metrics and25traces.2627## When to use2829- A feature needs log records, metrics or traces and nobody has said30 what each one is for.31- An incident cannot be explained from the records the system kept.32- Staff actions on patients' files need an audit trail.33- An error is logged in several layers as it passes through them.34- A log line, metric or trace carries a patient's name or clinical35 details.36- The clinic asks for a count of outcomes, such as refused bookings.3738## When not to use3940- The question is which error a method raises, or which caller handles41 it. That is designing failure behaviour.42- The question is the history of an object's own status changes.43 Modeling lifecycles, rule 6, covers it.44- The record is a domain event that other parts react to. That is45 publishing domain events.46- The code is a short script or a test whose output nobody reads after47 it ends.4849## Core rules50511. Rule. **Decide each record from the question it must answer and the52 person who asks it.** The person on call asks why one request failed53 and reads a log record. A practice manager asks how many bookings54 were refused today and reads a metric. An auditor asks who recorded55 a patient's allergy and when, and reads an audit record. A record56 that answers no one's question is noise that hides the ones that do.57582. Rule. **Keep an audit record as domain data, written by the59 use-case object in the same transaction as the act it records, and60 kept for as long as the clinic must answer for the act; never a log61 line, which may be sampled, rotated or dropped.** Modeling62 lifecycles, rule 6, keeps the history of an object's own63 transitions; an audit record covers any other act the clinic must64 answer for, such as an allergy recorded in a patient's file. It is65 stored with the act as the outbox is stored with a change, in one66 transaction, as publishing domain events, rule 4, does.67683. Rule. **Give each request one correlation identifier where it enters69 the system, and carry it on every log record, message and event the70 request causes.** One incident can then be followed from its records71 across threads and processes.72734. Default. **Record a failure once, where it is handled: the handler74 at the program's edge that turns a fault into a general failure, as75 designing failure behaviour, rule 2, places it, writes one log76 record with the correlation identifier and the error, and no layer77 logs an error and raises it again.** A failure logged at every layer78 it passes reads as several failures.7980 The exception is an adapter that translates an outside system's81 error: it records the original error before it raises the port's82 own, because the original is lost after that.83845. Rule. **Keep patients' personal and clinical details out of logs,85 metrics and traces: record identities, such as a `PatientId`, and86 outcomes, never names, contact details, diagnoses or notes.** Those87 records reach more people and live in more places than the patient's88 file, and nobody checks who reads them the way the file is checked.89906. Default. **Count with metrics: each outcome the clinic watches, such91 as bookings made or refused, is a counter or a measured duration,92 and each metric takes a few label values, such as the site, never a93 patient or appointment identity, which would make one series per94 patient.**9596 The exception is a count needed once, for one investigation: query97 the logs or the store for it instead of adding a metric.98997. Rule. **Keep logging out of domain objects: a domain object raises100 its refusals and records its domain events, and the application101 service, the handler at the edge and the adapters write log102 records.** Where a test must check that a record is written, write103 it through a port the domain owns, as inverting dependencies,104 rule 1, asks.105106## Pattern107108Before, the use-case object `RecordAllergy` stores the allergy and109writes a log line. That line carries the patient's name and the allergy,110a clinical detail; it is the only trace of who recorded the allergy, and111a log may be rotated away.112113Before:114115```text116class RecordAllergy117 - patients: Patients118 - log: Log119 + new(patients: Patients, log: Log)120 + run(id: PatientId, allergy: Allergy, by: ClinicianId): void121 raises AllergyAlreadyRecorded122 patient := patients.find(id)123 patient.record(allergy)124 patients.save(patient)125 log.write(patient.fullName(), allergy, by)126 return127```128129After, `RecordAllergy` stores the same patient and appends an130`AllergyAuditEntry` to the `AuditTrail` it is given, instead of writing131a log line.132133After:134135```text136value AllergyAuditEntry137 - patient: PatientId138 - allergy: Allergy139 - by: ClinicianId140 - at: DateTime141 + new(patient: PatientId, allergy: Allergy, by: ClinicianId,142 at: DateTime)143144interface AuditTrail145 + append(entry: AllergyAuditEntry): void146147class RecordAllergy148 - patients: Patients149 - audit: AuditTrail150 - clock: Clock151 + new(patients: Patients, audit: AuditTrail, clock: Clock)152 + run(id: PatientId, allergy: Allergy, by: ClinicianId): void153 raises AllergyAlreadyRecorded154 patient := patients.find(id)155 patient.record(allergy)156 patients.save(patient)157 audit.append(new AllergyAuditEntry(id, allergy, by, clock.now()))158 return159```160161`Patient`, its `record` command and the `AllergyAlreadyRecorded` error162are the encapsulating state and behaviour skill's, in its163`guarding-collections.md` reference; `patient.fullName()` is taken to164answer the patient's name. `Patients` is taken to be the patients'165repository, whose `find` answers the stored patient and whose `save`166stores it. `Log.write` is taken to write one log line. `Clock` is the167inverting dependencies skill's port, whose `now()` answers the current168time. The audit entry is an audit record, not a domain event.169170The Before's log line has no place in the After: a failure is logged171once at the edge, as rule 4 says, and the audit entry answers the172auditor.173174`run` stores the patient with the new allergy under its `PatientId`, in175the clinic's database, in the one transaction `run` opens and ends. The176After also stores one `AllergyAuditEntry` there, in that same177transaction. `patient.record` raises before `save` or `append` runs, so178a refused allergy stores neither the patient nor an entry. Each version179stores the patient once, and the After appends one entry for each180allergy recorded.181182## Red flags183184Places to look, not verdicts. A red flag becomes a finding only with185evidence: a measurement, a reproducible bug, or a failing test.186187- A log line that holds a patient's name, contact details or clinical188 notes.189- An error logged at every layer it passes.190- A log message with no identity of the request, appointment or191 patient.192- An audit question answered from the logs.193- A metric labelled with a patient or appointment identity.194- A domain object that writes to a logger.195196## Common mistakes197198- Logging every step in case it is needed.199- Counting outcomes by searching the logs.200- Writing the audit record after the transaction commits, where a201 failure loses it.202- Starting a new correlation identifier at each process the request203 reaches.204- Keeping logs as long as audit records, or audit records as briefly as205 logs.206207## Related skills208209- [oo-design](../oo-design/SKILL.md) sizes a task and defines the rule210 labels.211- [oo-designing-failure-behaviour](../oo-designing-failure-behaviour/SKILL.md)212 places the one handler that records a fault.213- [oo-modeling-lifecycles](../oo-modeling-lifecycles/SKILL.md) keeps the214 history of an object's own transitions.215- [oo-publishing-domain-events](../oo-publishing-domain-events/SKILL.md)216 stores a domain event with the change that caused it.217- [oo-inverting-dependencies](../oo-inverting-dependencies/SKILL.md)218 puts a port beside the domain for a clock or a store.219- [oo-separating-reads-from-writes](../oo-separating-reads-from-writes/SKILL.md)220 keeps a read from changing what it reads.221222## Further reading223224- [Logs, metrics and traces](references/logs-metrics-and-traces.md)225- [Audit records](references/audit-records.md)