[systemd-devel] journald API documentation

[Lennart Poettering]

On Fri, 29.06.12 14:39, Zbigniew Jędrzejewski-Szmek (zbyszek at in.waw.pl) wrote:

> Hi,
> 
> I've been playing around with the python journald client, and I'm not
> entirely clear on a few API details. I think it would be nice if the new
> documentation cleared them up:
> 
> 1. If the iovect passed to sd_journal_sendv() doesn't contain MESSAGE=
> field, the whole request seems to be ignored. And no error is thrown. Is
> this expected?

It shouldn't be ignored, but journalctl currently just skips over it in
the normal output, since there is nothing to show. The data should
actually be stored on disk just fine, and the verbose mode of journalctl
should show it.

In the long run we actually want to make this a bit smarter, and if no
MESSAGE= field is set, try to look up MESSAGE_ID= in an "explanation"
database we want to integrated. If MESSAGE_ID= doesn't exist either it
might be a good idea to show some place holder text rather than not
showing anything...

> 2. The documentation mentions ASCII as the coding, but shouldn't the
> messages rather be standardized on UTF-8? And also, is there a way for
> the reader to know, which attributes are binary? Is there some convention?

The fields are typeless and can carry anything you like. We suggest
people format things as ASCII strings wherever possible, UTF-8 where
necessary, and binary where nothing else makes sense. This is what we
call "primarily ASCII". But yeah the bit that UTF-8 is the second best
thing if pure ASCII is not applicable is currently not mentioned anyway
and deserves.

The idea is that log viewers try to detect if something is valid UTF8
and show it as such if it is. If it isn't they should show something
like a hexdump or so instead. Currently journalctl isn't really doing
this yet, it just has a very simple logic that checks for a subset of
ASCII. This needs to be beefed up...

Lennart

-- 
Lennart Poettering - Red Hat, Inc.