Knowledge base

PMTA knowledge base›Mechanism§ 11.22

Node metrics in a standard format

Prometheus metrics exporter

The only surface that someone else’s monitoring understands by itself

The third way to observe a node — and the only one whose output a ready-made monitoring system understands without a translator. It appeared in PowerMTA 5.5.

What is exposed, by group:

Group	Metrics	What it reveals
traffic	recipients, messages, bytes, connections	demand and its seasonality
saturation	queue depth in recipients and bytes, current connections	approaching the limit
errors	4xx, 5xx, internal; queue ones separately	the failure rate
delays	conversation duration, time to the first attempt	early signs of trouble

Labels distinguish direction and submission method. Traffic has srcType: submission over SMTP, via the submission API, internal (for example, non-delivery notifications), via the Transmissions API and seeding. That is, you can see which path messages came by — something neither the monitor nor accounting shows.

These are summaries, not events. The vendor says so directly: the set is designed for overall system health, and it is not meant for investigating individual messages — accounting and the log exist for that.

Three metrics require separate enabling: both conversation delays (track-inbound-perf-stats, track-outbound-perf-stats) and the time to the first attempt (track-time-first-attempt). The rest work right away with the block.

The main trap is expecting an answer about a specific message here. The surface is aggregate by design. It answers “how many” and “how fast on average,” but not “what happened to this recipient” — accounting answers that.

What the Hub does. It does not use it: its own telemetry arrives via the accounting webhook, and the Hub collects the current state by polling the management interface.

🔎 The schema has a place reserved for this — the node_engines.metrics_port column — but nobody fills it in: the path was mapped out and never taken.

🔎 And this is the only node surface that does not need our secret. The management interface requires a key, the webhook a token, while metrics are exposed as they are. A client with its own monitoring can be given it with one line in the configuration, without opening anything else.

Recommended values

The mechanism has no values of its own — it is enabled by the block, and three metrics are opened by node-level lines:

What is needed	What enables it
the whole surface	the <prometheus-listener> block
receiving delay	track-inbound-perf-stats
sending delay	track-outbound-perf-stats
time to the first attempt	track-time-first-attempt
a per-receiver breakdown of the latter	time-first-attempt-domains-file

The metric set, the labels, the overhead estimate and the requirements for enabling individual values come from the manual (§ 11.22). The remark about the only surface without our secret is ours.

Example configuration

# the block exposes metrics; three lines add delays to them
<prometheus-listener 0/0:9090></prometheus-listener>

track-inbound-perf-stats true
track-outbound-perf-stats true
track-time-first-attempt true

The port must be closed with a firewall just like the management one: the metrics say enough about the node’s load to interest an outsider.

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▶

Expecting metrics to answer about an individual message

§ 11.22

What it costsThe surface is aggregate: counters, gauges and summaries. The fate of a specific recipient is not there and never will be.

How to spot itPeople search the metrics for whether a message reached a specific addressee.

How to do it rightLook at accounting — it is exactly about individual events.

Leaving the metrics port open to the outside

our experience

What it costsThe metrics tell about volumes, the error rate and queue depth — that is, about the state of affairs. They do not require a secret, which means they are not protected by anything.

How to spot itThe listener port responds from an arbitrary machine.

How to do it rightClose it with a firewall, leaving access for the monitoring system.

Configuring the block and expecting delay metrics

§ 11.22

What it costsThree values require separate enabling with node-level lines. Without them the corresponding metrics stay empty.

How to spot itTraffic and queue metrics are there, delays are not.

How to do it rightEnable track-inbound-perf-stats, track-outbound-perf-stats and track-time-first-attempt.

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.

Inheritance

The mechanism has no inheritance — the directives that enable it are inherited. There is one block on a node, and the metrics are exposed in full: a subset cannot be chosen.

⇄

Related entries

4 relations

Depends on

track-time-first-attemptGlobalOpens the time-to-first-attempt summary; without it this metric is empty. § 11.22

Can be replaced by

The whole node state in one documentThe same snapshot of the current state, only in its own format and without our key. § 11.22 Exposing metrics over SNMPA neighboring read surface with its own access model and its own format. inference

Where you can see it

Exposing metrics to a collectorHow exactly the exposure is built: the format, metric types and their semantics. § 14

How to check on the node

The check is direct — we fetch the metrics the same way monitoring does:

curl -s http://NODE:9090/metrics | head -30

The response has lines like pmta_traffic_recipients_total{direction=”out”,…}. Empty or a connection refusal means the block is not configured or the port is closed. Delay metrics appear only when the counting lines are enabled.

◇

What else to read

3 articles

◇Five ways for a queue to hand off a messageA queue does not have to use SMTP: it can write to a file, run a program, call over HTTP or discard.◇How a message gets into the engineSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.◇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.

In the Hub

Cost of a mistake: safe: a wrong value breaks nothing
Scenarios: Connect a sending platform · Collect telemetry