Query the journal with explicit field and priority rules

Fri, 30 Jul 2027 00:00:00 +0000

A useful journal query selects the records that answer a specific incident question. Unit identity, invocation, time, priority, and application fields provide different dimensions. Combining them correctly matters more than finding a familiar word somewhere in the machine’s history. journald can attach process metadata, but it does not automatically collect every file an application writes or infer the business meaning of each message.

When it breaks

Field matches have a particular Boolean grammar. Different fields are combined with AND. Multiple matches for the same field are alternatives combined with OR. A separate + joins groups with OR. Consequently, adding another value for a field can broaden a result rather than narrow it. Treat the query as a predicate and check its result against known records before using it in an incident script.

-p err includes error and more severe priorities. It does not mean only priority three. Use an exact PRIORITY=3 field match when that is the intended condition. Application text saying “error” is not itself a priority assignment; stdout collection uses configured priority rules unless the application supplies a supported priority representation.

A successful command with no returned records is not proof that the service never ran. The selected boot, time window, namespace, reader permissions, retention, or output routing might explain the absence. Conversely, querying an entire unit history can find a previous successful startup and mistakenly attribute it to the current process. Separate unit identity from one specific invocation.

Check it quickly

Run this Python script as an administrator in a disposable Linux system whose PID 1 is systemd. The recorded environment was Debian 12 with systemd 252.39. It installs a uniquely named temporary service and activates it twice. Each worker submits four short structured datagrams to the native journal socket, with two application components and several explicit priorities:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,uuid

name='xbcatm-query-'+uuid.uuid4().hex[:8];unit=name+'.service'
path=Path('/run/systemd/system')/unit
assert not path.exists()
def run(*args):
 result=subprocess.run(args,text=True,capture_output=True,timeout=10)
 assert result.returncode==0,(args,result.stderr)
 return result.stdout.strip()
def query(*matches):
 output=run('journalctl','--no-pager','-o','json','-u',unit,*matches)
 return [json.loads(line) for line in output.splitlines() if line]
def labels(rows):return sorted(row['MESSAGE'] for row in rows)
with TemporaryDirectory(prefix=name+'-',dir='/run') as directory:
 root=Path(directory);worker=root/'worker.py'
 worker.write_text(r'''from pathlib import Path
import socket
phase=Path(__file__).with_name('phase').read_text()
with socket.socket(socket.AF_UNIX,socket.SOCK_DGRAM) as log:
 log.connect('/run/systemd/journal/socket')
 for component,priority in [('api',2),('api',3),('api',6),('db',3)]:
 fields=[f'MESSAGE={phase}-{component}-{priority}',f'PRIORITY={priority}',
 f'LAB_RUN={phase}',f'LAB_COMPONENT={component}',
 '_SYSTEMD_UNIT=forged.service']
 log.sendall(('\n'.join(fields)+'\n').encode())
''')
 path.write_text(f'[Service]\nType=oneshot\nExecStart=/usr/bin/python3 {worker}\n')
 try:
 run('systemd-analyze','verify',str(path));run('systemctl','daemon-reload')
 for phase in ('first','second'):
 (root/'phase').write_text(phase);run('systemctl','start',unit)
 run('journalctl','--sync')
 first=query('LAB_RUN=first')
 assert len(first)==4 and all(row['_SYSTEMD_UNIT']==unit for row in first)
 second=query('LAB_RUN=second');assert len(second)==4
 invocation=first[0]['_SYSTEMD_INVOCATION_ID']
 assert {row['_SYSTEMD_INVOCATION_ID'] for row in first}=={invocation}
 assert {row['_SYSTEMD_INVOCATION_ID'] for row in second}!={invocation}
 assert labels(query('LAB_RUN=first','LAB_COMPONENT=api','-p','err'))==['first-api-2','first-api-3']
 print('different fields AND; -p err includes critical priority 2 and error priority 3')
 assert labels(query('LAB_RUN=first','LAB_COMPONENT=api','PRIORITY=3'))==['first-api-3']
 assert labels(query('LAB_RUN=first','LAB_COMPONENT=api','LAB_COMPONENT=db','PRIORITY=3'))==['first-api-3','first-db-3']
 print('exact PRIORITY=3 differs from threshold; repeated component fields OR')
 union=query('LAB_RUN=first','LAB_COMPONENT=db','+','LAB_RUN=second','LAB_COMPONENT=db')
 assert labels(union)==['first-db-3','second-db-3']
 assert labels(query('_SYSTEMD_INVOCATION_ID='+invocation,'LAB_COMPONENT=db'))==['first-db-3']
 print('explicit + joins match groups; invocation filter separates repeated starts')
 assert query('LAB_RUN=absent')==[]
 print('empty query still succeeds; underscore unit field comes from journal metadata')
 finally:
 run('systemctl','stop',unit)
 if run('systemctl','show',unit,'-p','ActiveState','--value')=='failed':run('systemctl','reset-failed',unit)
 path.unlink();run('systemctl','daemon-reload')

The first activation produces an API critical message, an API error, an API informational message, and a database error. The second activation produces the same categories with a different application run label. Filtering by the first run, API component, and -p err returns two records: priorities two and three. Switching to exact priority three returns only the API error.

Repeating the component field with API and database values returns both components’ error records for the first run. It does not demand that one record simultaneously have both values. The explicit + example then selects the database record from either run. The assertions check complete expected message lists, so an accidentally broad filter cannot pass by merely containing one desired phrase.

The service’s two activations have different journal invocation identifiers. Filtering with the first identifier selects only that activation’s database message, even though the unit name is unchanged. This is useful during crash loops and repeated manual starts: the unit groups a service’s history, while an invocation identifies one execution lifecycle.

The worker also attempts to submit a forged underscore-prefixed unit field. Returned records carry the actual service unit instead. Those trusted fields are supplied by the journal from process context rather than accepted as ordinary application labels. In contrast, the custom component and run fields are application claims; the experiment controls them, but a production parser should not treat their names as an independent authentication mechanism.

Finally, a match for an absent run returns an empty list while the query command succeeds. The script explicitly checks this case. It removes the temporary service and worker files afterward; the eight harmless journal entries remain subject to the host’s normal retention policy, rather than deleting unrelated system history to erase a small fixture.

Preserve context when exporting results

Use structured output when another program consumes the query. The sample parses JSON and its deliberately small textual fields. General journal JSON can represent repeated values or binary data differently, so define the consumer’s accepted schema rather than assuming every arbitrary field is always one simple string. Keep timestamps and attribution fields when exporting evidence for later comparison.

Record the relevant boot or invocation and make time-zone assumptions explicit for time-window queries. Reader access and selected namespace are part of the observation, not incidental details. Before concluding that an application event is missing, verify that a known harmless event from the same route is visible. A bounded, reproducible query should make both its selection rule and its limits clear.

Sources

systemd 252 journalctl, field-match Boolean rules, priority filters, and JSON output, checked 2026-09-12.
systemd 252 systemd.journal-fields, trusted metadata, application fields, and invocation identifiers, checked 2026-09-12.
systemd 252 systemd-journald.service, native logging transport, namespace separation, and collection scope, checked 2026-09-12.

Journald · XB Field Notes

Query the journal with explicit field and priority rules

When it breaks

Check it quickly

Preserve context when exporting results

Further reading

Sources