diff options
| -rw-r--r-- | CONTRIBUTING.md | 10 | ||||
| -rw-r--r-- | README.md | 53 |
2 files changed, 46 insertions, 17 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae492ef2da..a001f97776 100644 --- a/CONTRIBUTING.md +++ b/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 -pollution" via the user's environment. If you have Nix installed and -are contributing to a project that has a `default.nix`, consider using +Most of my projects are built using [Nix][] to avoid "build pollution" +via the user's environment. If you have Nix installed and are +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 diff --git a/README.md b/README.md index 00db058e88..32efcf4288 100644 --- a/README.md +++ b/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 -languages with error-prone "cover every use-case" configuration. This -tool aims to fit a specific use-case very well, instead of covering -every possible logging setup. +Many existing log services are written in inefficient dynamic +languages with error-prone "cover every possible use-case" +configuration. `journaldrive` instead aims to fit a specific use-case +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 -`journaldriver`. The NixOS package repository [contains a module][] -for setting up `journaldriver`. +The NixOS package repository [contains a module][] for setting up +`journaldriver` on NixOS machines. NixOS by default uses `systemd` for +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 |