Demo
Demo

Knowledge base

PMTA knowledge base›File§ 4.1.2

The node's own log

logging file
The first place to look when something is wrong

The manual sets the priority unambiguously: the engine writes its own error messages here, not to the system log. The system log remains a fallback — for the case when the engine cannot write to its own file at all.

The contents are broad by design. One file holds lifecycle events — startup and shutdown — runtime errors, connection and command traces, which are enabled by logging directives for each source or receiver, and resolver warnings.

Rotation is automatic, and its parameters are part of the configuration: how many past files to keep is decided by directives. That is, the history depth is a setting, not a property of the file.

Do not confuse it with accounting. Accounting is data about messages, one record per recipient, and it exists for reports. The log is about the engine itself, and it exists for investigations. Their directives differ, their purposes differ, and one cannot stand in for the other (log-accounting-separation).

The main trap is enabling detailed traces and forgetting to turn them off. Command and connection logging is enabled per source or per receiver and produces a line for every step of the conversation with the server. During an investigation it is invaluable; in everyday operation it is a file growing faster than the spool and rotation eating the history in hours instead of days. Such traces are worth enabling selectively and with the intention of turning them off.
What the Hub does. It does not read the log — its whole picture is built on accounting, which the node delivers as a stream.

This is a deliberate division: accounting answers questions about messages, the log about the engine itself. But it has a cost: a failure that happened before a message got into accounting is invisible to the Hub. For example, configuration parsing during a settings reload — it gets into the log, while nothing gets into accounting.

So when investigating unclear node behavior, the log has to be viewed by hand by logging into the machine — and it is worth remembering that it is there and holds more than telemetry does.

Recommended values

What to look for in the log and when:

Event When to look
startup and shutdown the node did not come up or restarted by itself
configuration parse error a settings reload failed
resolver warnings delivery is not going to some of the domains
connection and command traces investigating a specific receiver — enable selectively

History depth is a setting. The number of kept files is set by logging directives; the default is reasonable for a quiet node and too small for one with detailed traces enabled.

An investigation starts here, not with the system log. Only what the engine could not write to its own file gets into the system log.

The “what to look for and when” table is ours. From the manual here come the priority of the engine’s own log over the system log, the set of what gets written, automatic rotation and the fact that its parameters live in the configuration.
Example configuration
# an investigation starts with two questions to the log
tail -n 200 /var/log/pmta/loggrep -i 'error\|warn' /var/log/pmta/log | tail -50
The highlighted line answers the question “what just happened” — the startup messages and a configuration parse failure, if there was one, will be there too. The second picks out errors and warnings for the whole lifetime of the file.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends3 mistakes▶

Looking for engine errors in the system log

§ 4.1.2

What it costsThe manual sets the opposite priority: the engine writes its own errors to its own file, and the system log is a fallback for when it cannot write to that file. An investigation based on the system log almost always comes up empty.
How to spot itThere is nothing about the engine in the system log, even though it is clearly misbehaving.
How to do it rightStart the investigation with the node’s own log. Look at the system log when the node’s own log is empty or unavailable.

Leaving detailed traces enabled

§ 4.1.2

What it costsCommand and connection logging writes a line for every step of the conversation. The file grows faster than the spool, and rotation eats the history in hours — and when the log is needed, the day you need will no longer be in it.
How to spot itThe log directory is noticeably larger than usual, and the history is shorter than a day.
How to do it rightEnable traces selectively — for one receiver or source — and turn them off right after the investigation.

Expecting message data from the log

§ 4

What it costsThe log is about the engine, not about messages. Questions like “how many went out” and “who did not get it” are answered by accounting, and one cannot stand in for the other: they have different directives and different contents.
How to spot itA search of the log finds no trace of a specific recipient.
How to do it rightAsk accounting. Keep the log for questions about the node itself.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Reference data
Syntax
Line-oriented text, each entry stamped with date and time.
Everything here comes from the manual, with the section.
Inheritance
The file has no inheritance. What is inherited are the directives that decide what gets into it: command and connection logging is set in a source or receiver block and merges by the usual rule — a narrow block overrides a broad one. So detailed traces can be enabled for one receiver without touching the others.
⇄

Related entries

3 relations

Works together with

The log and accounting — two files and two different questionsThe log is about the engine, accounting is about messages: different directives and different purposes. § 4.1.2Where the node writes why it did not startA separate file for startup failures — for the case when there is no one left to write to the main log. § 4.2.1

Where you can see it

Figure out why a queue to one receiver is growingA delivery investigation for a receiver reads exactly this file: both the trace and logging write here. § 4.2.2

Referenced from

The node needs a resolver that does all the work itselfRepeated referrals from one server produce a log warning — the only sign of this malfunction. § 4.2.3LogsThe file this output refers to. § 5.11Return a node fileThe file this output refers to. § 5.11Start a new log fileCloses the current file and starts a new one. § 6.3.10Delivery attempt with the session loggedThe file the command works with. § 6.3.23

How to check on the node
Check that the log is being written and has no accumulated errors:
ls -lh /var/log/pmta/
tail -n 100 /var/log/pmta/log
grep -c -i 'error' /var/log/pmta/log
The first will show the file sizes and the history depth — the number of files shows how rotation is configured. A file growing noticeably faster than the others usually means forgotten detailed traces.
◇

What else to read

3 articles

◇What the node tells about itself and through which channelsSeven observation surfaces: the web monitor, the console in four formats, the log, accounting, accounting search, metrics and export to external analytics.◇The log and accounting — two files and two different questionsThe engine keeps a separate log and a separate accounting file; the separation is made for the sake of format, performance and the ability to hand over the log without disclosing data.◇A file, a program or an endpoint — and a file under each of the threeThree ways to hand off accounting records; an endpoint still has a file underneath, which is deleted only after a successful send, and a non-2xx response triggers a retry.

In the Hub
Cost of a mistake
safe: a wrong value breaks nothing
Scenarios
Untangle a stuck queue · Collect telemetry