Merge pull request #207 from gabriel-samfira/update-readme

Update readme

README.md

@@ -28,11 +28,34 @@ Check out the [quickstart](/doc/quickstart.md) document for instructions on how
 
 Thanks to the efforts of the amazing folks at @mercedes-benz, GARM can now be integrated into k8s via their operator. Check out the [GARM operator](https://github.com/mercedes-benz/garm-operator/) for more details.
 
+## Configuration
+
+The ```GARM``` configuration is a simple ```toml```. The sample config file in [the testdata folder](/testdata/config.toml) is fairly well commented and should be enough to get you started. The configuration file is split into several sections, each of which is documented in its own page. The sections are:
+
+* [The default section](/doc/config_default.md)
+* [Logging](/doc/config_logging.md)
+* [Database](/doc/database.md)
+* [Github credentials](/doc/github_credentials.md)
+* [Providers](/doc/providers.md)
+* [Metrics](/doc/config_metrics.md)
+* [JWT authentication](/doc/config_jwt_auth.md)
+* [API server](/doc/config_api_server.md)
+
+## Using GARM
+
+GARM is designed with simplicity in mind. At least we try to keep it as simple as possible. We're aware that adding a new tool in your workflow can be painful, especially when you already have to deal with so many. The cognitive load for OPS has reached a level where it feels overwhelming at times to even wrap your head around a new tool. As such, we believe that tools should be simple, should take no more than a few hours to understand and set up and if you absolutely need to interact with the tool, it should be as intuitive as possible.
+
+We've written a short introduction into some of the commands that GARM has and some of the concepts involved in setting up GARM, managing runners and how GitHub does some of the things it does.
+
+[You can find it here](/doc/using_garm.md).
+
+Please, feel free to [open an issue](https://github.com/cloudbase/garm/issues/new) if you find the documentation lacking and would like more info. Sometimes we forget the challanges that new users face as we're so close to the code and how it works. Any feedback is welcome and we're always looking to improve the documentation. 
+
 ## Supported providers
 
 GARM uses providers to create runners in a particular IaaS. The providers are external executables that GARM calls into to create runners. Before you can create runners, you'll need to install at least one provider.
 
-## Installing external providers
+### Installing external providers
 
 External providers are binaries that GARM calls into to create runners in a particular IaaS. There are several external providers available:
 
@@ -41,21 +64,11 @@ External providers are binaries that GARM calls into to create runners in a part
 * [Kubernetes](https://github.com/mercedes-benz/garm-provider-k8s) - Thanks to the amazing folks at @mercedes-benz for sharing their awesome provider!
 * [LXD](https://github.com/cloudbase/garm-provider-lxd)
 * [Incus](https://github.com/cloudbase/garm-provider-incus)
+* [Equinix Metal](https://github.com/cloudbase/garm-provider-equinix)
+* [Amazon EC2](https://github.com/cloudbase/garm-provider-aws)
 
 Follow the instructions in the README of each provider to install them. 
 
-## Configuration
-
-The ```GARM``` configuration is a simple ```toml```. The sample config file in [the testdata folder](/testdata/config.toml) is fairly well commented and should be enough to get you started. The configuration file is split into several sections, each of which is documented in its own page. The sections are:
-
-* [The default section](/doc/config_default.md)
-* [Database](/doc/database.md)
-* [Github credentials](/doc/github_credentials.md)
-* [Providers](/doc/providers.md)
-* [Metrics](/doc/config_metrics.md)
-* [JWT authentication](/doc/config_jwt_auth.md)
-* [API server](/doc/config_api_server.md)
-
 ## Optimizing your runners
 
 If you would like to optimize the startup time of new instance, take a look at the [performance considerations](/doc/performance_considerations.md) page.

doc/config_logging.md

@@ -0,0 +1,35 @@
+# The logging section
+
+GARM has switched to the `slog` package for logging, adding structured logging. As such, we added a dedicated `logging` section to the config to tweak the logging settings. We moved the `enable_log_streamer` and the `log_file` options from the `default` section to the `logging` section. They are still available in the `default` section for backwards compatibility, but they are deprecated and will be removed in a future release.
+
+An example of the new `logging` section:
+
+```toml
+[logging]
+# Uncomment this line if you'd like to log to a file instead of standard output.
+# log_file = "/tmp/runner-manager.log"
+
+# enable_log_streamer enables streaming the logs over websockets
+enable_log_streamer = true
+# log_format is the output format of the logs. GARM uses structured logging and can
+# output as "text" or "json"
+log_format = "text"
+# log_level is the logging level GARM will output. Available log levels are:
+#  * debug
+#  * info
+#  * warn
+#  * error
+log_level = "debug"
+# log_source will output information about the function that generated the log line.
+log_source = false
+```
+
+By default GARM logs everything to standard output. You can optionally log to file by adding the `log_file` option to the `logging` section. The `enable_log_streamer` option allows you to stream GARM logs directly to your terminal. Set this option to `true`, then you can use the following command to stream logs:
+
+```bash
+garm-cli debug-log
+```
+
+The `log_format`, `log_level` and `log_source` options allow you to tweak the logging output. The `log_format` option can be set to `text` or `json`. The `log_level` option can be set to `debug`, `info`, `warn` or `error`. The `log_source` option will output information about the function that generated the log line. All these options influence how the structured logging is output.
+
+This will allow you to ingest GARM logs in a central location such as an ELK stack or similar.

doc/providers.md

@@ -50,6 +50,8 @@ For non testing purposes, there are two external providers currently available:
 * [Kubernetes](https://github.com/mercedes-benz/garm-provider-k8s) - Thanks to the amazing folks at @mercedes-benz for sharing their awesome provider!
 * [LXD](https://github.com/cloudbase/garm-provider-lxd)
 * [Incus](https://github.com/cloudbase/garm-provider-incus)
+* [Equinix Metal](https://github.com/cloudbase/garm-provider-equinix)
+* [Amazon EC2](https://github.com/cloudbase/garm-provider-aws)
 
 Details on how to install and configure them are available in their respective repositories.
 

doc/quickstart.md

@@ -101,6 +101,8 @@ This is where you have a decision to make. GARM has a number of providers you ca
 * [Kubernetes](https://github.com/mercedes-benz/garm-provider-k8s) - Thanks to the amazing folks at @mercedes-benz for sharing their awesome provider!
 * [LXD](https://github.com/cloudbase/garm-provider-lxd)
 * [Incus](https://github.com/cloudbase/garm-provider-incus)
+* [Equinix Metal](https://github.com/cloudbase/garm-provider-equinix)
+* [Amazon EC2](https://github.com/cloudbase/garm-provider-aws)
 
 All currently available providers are `external`.