An internal tool has been running for a few months. Then the questions begin: "Why does this order show the wrong status?", "Who changed the delivery term?", "The export did not run last night, what happened?" If the answer needs the developer, a database query and half an afternoon, the tool is costing more than it should.
This article is for a developer or technology lead who looks after a small internal application used by a few dozen people. It is about ordinary business software, not about monitoring AI agents, which has its own concerns covered in observing AI agents in production. The goal is modest: write down the right things, in a readable form, so that most support questions answer themselves.
Start from the questions, not the technology
Before choosing what to record, list the ten questions your users and managers actually ask. Look at the last few weeks of messages. They usually fall into a few groups:
- Who did this, and when?
- What did it look like before the change?
- Why did the automatic job not run, or run twice?
- Why can a person not see or do something?
- Why did a number change?
Each group points to one kind of record. If a record does not help answer a real question, it is noise, and noise makes the useful lines harder to find.
The five kinds of records
1. Business changes
Every time a person creates, changes or deletes something that matters to the business, write one line: who, when, what object, what changed. For a price change that means the user, the time, the order number, the old value and the new value. This single record answers most "who changed it" disputes and costs very little.
2. Sign-ins and permission changes
Record successful and failed sign-ins and every change to a person's role. When someone says "I could see this yesterday," you can check whether their role changed or whether they simply signed in with a different account.
3. Scheduled jobs and imports
Every automatic job writes a line when it starts and a line when it finishes, with the number of items processed and the result. A job that did not write a finishing line is the first thing to check when something looks stale. Include the job name and the date it was meant to cover, so that a missed night is visible.
4. Errors
When something fails, record what the user was doing, which object was involved and a short error code or message. Add a reference number that the user sees on screen. Then a user can write "error 4F7A" in a message, and you find the exact line in a minute.
5. Exports, sharing and sensitive views
If the tool lets people download data, send it onwards or open records that are normally restricted, note who did it and what was included, for example "customer list, 214 rows." You do not need the content, only the fact. It protects honest users as much as it helps in a real incident.
Write for a colleague, not for a machine
A log that only a developer can read will only be read by a developer. Prefer one short sentence per record with a fixed order of information:
2026-03-14 09:12 · Petra N. · changed delivery term on order 1042 · from 14 days to 10 days
Use real names or user identifiers the team recognises, and local time with the time zone stated once. Add a simple screen in the tool, visible to the tool owner, that lists the latest records with a filter by person, object and date. If that is too much work for now, a daily text file or a spreadsheet export is a fair start. The test is whether a team lead can find an answer without asking for help.
How long to keep records
Different records have different lifetimes.
| Kind | Typical retention | Reason |
|---|---|---|
| Business changes | As long as the business record itself, or as long as your rules for disputes and audits require | They explain history |
| Sign-ins and permission changes | Several months to a year | Enough to cover a typical investigation |
| Job runs | A few weeks | Only recent runs help |
| Errors | A few weeks, with notable cases copied into the ticket | Old errors rarely matter |
| Exports and sensitive views | Same as sign-ins | Needed after an incident is noticed |
These are starting points, not rules. If your company or sector has specific retention requirements, follow those and ask whoever is responsible for compliance. Whatever you choose, write it down and delete old technical records on a schedule, so that the log does not grow without limit.
What never to write
Logs are copied, backed up and shared with whoever helps with support, so treat them as less protected than the main database.
- Passwords, tokens and keys. Not even in error messages. Check what your error handler prints.
- Full personal data. Use an object number, not a full name, address and phone number. A customer number is enough to find the record.
- Free text from users. Notes, emails and comments can contain anything. Record that a note was changed, not what it says.
- Whole requests and responses. They are convenient during development and risky in operation.
A quick check: read twenty random log lines and ask whether you would be comfortable if they were forwarded to an outside supplier. If not, change what is written.
A short example
A small company uses an internal tool for service orders. A manager asks why a technician's visit shows as cancelled when the customer says it was confirmed. With the five records in place, the team lead filters the business changes by order number and sees: the status was changed to cancelled by a dispatcher at 16:40 the day before, from confirmed. The dispatcher remembers merging two duplicate orders. The team lead restores the status and adds a note. It takes five minutes and no developer.
Without the records, the same question becomes a request to the developer, a look at the database, and a guess about what happened.
What to avoid
- Logging everything "just in case." Volume hides the lines you need.
- Different formats in every part of the tool. Agree on one order of information and use it everywhere.
- No reference number for errors. Users then describe the problem in their own words and you search blindly.
- Logs nobody reads. If nobody has opened the log in three months, either it records the wrong things or nobody knows it exists.
What to do this week
Collect the ten most recent support questions about your tool. For each, write down where the answer would be found today. Add the missing records starting with business changes, because they answer the most questions. Then pick one real question, ask a colleague who is not a developer to answer it from the log, and note how long it takes. If you are still planning the wider rollout, our first 30 days after launching a new internal tool shows when such questions usually start, and who owns an internal tool after its author leaves explains who should read the log.
Sources
- Our related articles linked above.
- The five kinds of records, retention periods and the example are a general working approach, not a standard; adapt them to your tool, your team and any legal retention requirements that apply to you.