about summary refs log tree commit diff
path: root/README.md
diff options
context:
space:
mode:
authorVincent Ambo <mail@tazj.in>2018-09-24T13·45+0200
committerVincent Ambo <github@tazj.in>2018-09-24T14·03+0200
commita4084bf1e0ffc1f6f417974de8c6f93d461a5135 (patch)
tree5425d42aa7a7235500ac3bcc584cdbba5d2d99ef /README.md
parent3b20abe0f891d2379a6d815fea49aface8e95f95 (diff)
docs(README): Add note about log levels / priorities / severities
(kjære barn har mange navn :P)

Adds a small piece of documentation about the conversion between
journald priorities and Stackdriver severities to the README, as well
as information about how to easily emit messages at different
priorities from applications logging to journald.
Diffstat (limited to 'README.md')
-rw-r--r--README.md28
1 files changed, 23 insertions, 5 deletions
diff --git a/README.md b/README.md
index 63ac2655687a..00db058e8850 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,8 @@ configuration as authentication tokens are retrieved from the
   in Stackdriver
 * `journaldriver` can be used outside of GCP by configuring static
   credentials
+* `journaldriver` will recognise journald's log priority levels and
+  convert them into equivalent Stackdriver log severity levels
 
 ## Usage on Google Cloud Platform
 
@@ -60,6 +62,24 @@ performed:
      `journaldriver` if unset, but it is recommended to - for
      example - set it to the machine hostname.
 
+## Log levels / severities / priorities
+
+`journaldriver` recognises [journald's priorities][] and converts them
+into [equivalent severities][] in Stackdriver. Both sets of values
+correspond to standard `syslog` priorities.
+
+The easiest way to emit log messages with priorites from an
+application is to use [priority prefixes][], which are compatible with
+structured log messages.
+
+For example, to emit a simple warning message (structured and
+unstructured):
+
+```
+$ echo '<4>{"fnord":true, "msg":"structured log (warning)"}' | systemd-cat
+$ echo '<4>unstructured log (warning)' | systemd-cat
+```
+
 ## NixOS module
 
 At Aprila we deploy all of our software using [NixOS][], including
@@ -87,13 +107,11 @@ services.journaldriver = {
 **Note**: The `journaldriver`-module is not yet included in a stable
 release of NixOS, but it is available on the `unstable`-channel.
 
-## Upcoming features:
-
-* `journaldriver` will be added to [nixpkgs][] with a complementary
-  [NixOS][] module for easy configuration.
-
 [Stackdriver Logging]: https://cloud.google.com/logging/
 [metadata server]: https://cloud.google.com/compute/docs/storing-retrieving-metadata
 [Google's documentation]: https://cloud.google.com/logging/docs/access-control
 [NixOS]: https://nixos.org/
 [contains a module]: https://github.com/NixOS/nixpkgs/pull/42134
+[journald's priorities]: http://0pointer.de/public/systemd-man/sd-daemon.html
+[equivalent severities]: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
+[priority prefixes]: http://0pointer.de/public/systemd-man/sd-daemon.html