docs(README): Add notes about error reporting & minor improvements

CONTRIBUTING.md

@@ -74,7 +74,7 @@ different commit. Introducing a new feature and refactoring
 
 `git commit -a` is generally **taboo**.
 
-In our experience making "sane" commits becomes *significantly* easier
+In my experience making "sane" commits becomes *significantly* easier
 as developer tooling is improved. The interface to `git` that I
 recommend is [magit][]. Even if you are not yet an Emacs user, it
 makes sense to install Emacs just to be able to use magit - it is
@@ -91,16 +91,16 @@ very subjective, but as an example if you place code that throws away
 errors into a block in which errors are handled properly your change
 will be rejected.
 
-In our experience there is a strong correlation between the visual
+In my experience there is a strong correlation between the visual
 appearance of a code block and its quality. This is a simple way to
 sanity-check your work while squinting and keeping some distance from
 your screen ;-)
 
 ## Builds & tests
 
-Most of our projects are built using [Nix][] to avoid "build
+Most of my projects are built using [Nix][] to avoid "build pollution"
-pollution" via the user's environment. If you have Nix installed and
+via the user's environment. If you have Nix installed and are
-are contributing to a project that has a `default.nix`, consider using
+contributing to a project that has a `default.nix`, consider using
 `nix-build` to verify that builds work correctly.
 
 If the project has tests, check that they still work before submitting

README.md

@@ -4,16 +4,28 @@ journaldriver
 This is a small daemon used to forward logs from `journald` (systemd's
 logging service) to [Stackdriver Logging][].
 
-Most existing log services are written in inefficient dynamic
+Many existing log services are written in inefficient dynamic
-languages with error-prone "cover every use-case" configuration. This
+languages with error-prone "cover every possible use-case"
-tool aims to fit a specific use-case very well, instead of covering
+configuration. `journaldrive` instead aims to fit a specific use-case
-every possible logging setup.
+very well, instead of covering every possible logging setup.
 
 `journaldriver` can be run on GCP-instances with no additional
 configuration as authentication tokens are retrieved from the
 [metadata server][].
 
-## Features
+<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
+**Table of Contents**
+
+- [Features](#features)
+- [Usage on Google Cloud Platform](#usage-on-google-cloud-platform)
+- [Usage outside of Google Cloud Platform](#usage-outside-of-google-cloud-platform)
+- [Log levels / severities / priorities](#log-levels--severities--priorities)
+- [NixOS module](#nixos-module)
+- [Stackdriver Error Reporting](#stackdriver-error-reporting)
+
+<!-- markdown-toc end -->
+
+# Features
 
 * `journaldriver` persists the last forwarded position in the journal
   and will resume forwarding at the same position after a restart
@@ -25,7 +37,7 @@ configuration as authentication tokens are retrieved from the
 * `journaldriver` will recognise journald's log priority levels and
   convert them into equivalent Stackdriver log severity levels
 
-## Usage on Google Cloud Platform
+# Usage on Google Cloud Platform
 
 `journaldriver` does not require any configuration when running on GCP
 instances.
@@ -42,7 +54,7 @@ instances.
 
 3. Start `journaldriver`, for example via `systemd`.
 
-## Usage outside of Google Cloud Platform
+# Usage outside of Google Cloud Platform
 
 When running outside of GCP, the following extra steps need to be
 performed:
@@ -62,7 +74,7 @@ performed:
      `journaldriver` if unset, but it is recommended to - for
      example - set it to the machine hostname.
 
-## Log levels / severities / priorities
+# Log levels / severities / priorities
 
 `journaldriver` recognises [journald's priorities][] and converts them
 into [equivalent severities][] in Stackdriver. Both sets of values
@@ -80,11 +92,12 @@ $ echo '<4>{"fnord":true, "msg":"structured log (warning)"}' | systemd-cat
 $ echo '<4>unstructured log (warning)' | systemd-cat
 ```
 
-## NixOS module
+# NixOS module
 
-At Aprila we deploy all of our software using [NixOS][], including
+The NixOS package repository [contains a module][] for setting up
-`journaldriver`. The NixOS package repository [contains a module][]
+`journaldriver` on NixOS machines. NixOS by default uses `systemd` for
-for setting up `journaldriver`.
+service management and `journald` for logging, which means that log
+output from most services will be captured automatically.
 
 On a GCP instance the only required option is this:
 
@@ -107,6 +120,19 @@ services.journaldriver = {
 **Note**: The `journaldriver`-module is not yet included in a stable
 release of NixOS, but it is available on the `unstable`-channel.
 
+# Stackdriver Error Reporting
+
+The [Stackdriver Error Reporting][] service of Google's monitoring
+toolbox supports automatically detecting and correlating errors from
+log entries.
+
+To use this functionality log messages must be logged in the expected
+[log format][].
+
+*Note*: Currently errors logged from non-GCP instances are not
+ingested into Error Reporting. Please see [issue #4][] for more
+information about this.
+
 [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
@@ -115,3 +141,6 @@ release of NixOS, but it is available on the `unstable`-channel.
 [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
+[Stackdriver Error Reporting]: https://cloud.google.com/error-reporting/
+[log format]: https://cloud.google.com/error-reporting/docs/formatting-error-messages
+[issue #4]: https://github.com/tazjin/journaldriver/issues/4