[systemd-devel] journald API documentation

[Zbigniew Jędrzejewski-Szmek]

On 06/29/2012 02:49 PM, Lennart Poettering wrote:
> 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.
Oh, that explains it. journalctl -o verbose and -o export indeed show that
it is logged.

Invalid messages like "=goo" error out. That's good.

"MESSAGE=" is logged, and even displayed as an empty line with '-o
short'. That might be good, I'm not sure.

But "message=" is neither logged, nor causes an error. What's going on here?

> 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.

OK, that's fine, as long as 'ASCII' here means a script subset of UTF-8.
Then applications can just "show UTF-8".

> 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...

Let's just hope that this doesn't deteriorate into web-style 90%-successful
encoding-guessing-game.

Zbyszek