Document request logging configuration (#4934)

* docs: Add instructions for configuring request logging Signed-off-by: Philip Gough <[email protected]> * docs: Update link to logging config and make docs Signed-off-by: Philip Gough <[email protected]>
thanos-io · Feb 9, 2022 · c038534 · c038534
1 parent 02549ea
commit c038534
Show file tree

Hide file tree

Showing 8 changed files with 147 additions and 14 deletions.
diff --git a/docs/components/query-frontend.md b/docs/components/query-frontend.md
@@ -291,11 +291,11 @@ Flags:
                                  flag (mutually exclusive). Content of YAML file
                                  with request logging configuration. See format
                                  details:
-                                 https://gist.github.com/yashrsharma44/02f5765c5710dd09ce5d14e854f22825
+                                 https://thanos.io/tip/thanos/logging.md/#configuration
       --request.logging-config-file=<file-path>
                                  Path to YAML file with request logging
                                  configuration. See format details:
-                                 https://gist.github.com/yashrsharma44/02f5765c5710dd09ce5d14e854f22825
+                                 https://thanos.io/tip/thanos/logging.md/#configuration
       --tracing.config=<content>
                                  Alternative to 'tracing.config-file' flag
                                  (mutually exclusive). Content of YAML file with

diff --git a/docs/components/query.md b/docs/components/query.md
@@ -376,11 +376,11 @@ Flags:
                                  flag (mutually exclusive). Content of YAML file
                                  with request logging configuration. See format
                                  details:
-                                 https://gist.github.com/yashrsharma44/02f5765c5710dd09ce5d14e854f22825
+                                 https://thanos.io/tip/thanos/logging.md/#configuration
       --request.logging-config-file=<file-path>
                                  Path to YAML file with request logging
                                  configuration. See format details:
-                                 https://gist.github.com/yashrsharma44/02f5765c5710dd09ce5d14e854f22825
+                                 https://thanos.io/tip/thanos/logging.md/#configuration
       --selector-label=<name>="<value>" ...
                                  Query selector labels that will be exposed in
                                  info endpoint (repeated).

diff --git a/docs/components/receive.md b/docs/components/receive.md
@@ -178,11 +178,11 @@ Flags:
                                  flag (mutually exclusive). Content of YAML file
                                  with request logging configuration. See format
                                  details:
-                                 https://gist.github.com/yashrsharma44/02f5765c5710dd09ce5d14e854f22825
+                                 https://thanos.io/tip/thanos/logging.md/#configuration
       --request.logging-config-file=<file-path>
                                  Path to YAML file with request logging
                                  configuration. See format details:
-                                 https://gist.github.com/yashrsharma44/02f5765c5710dd09ce5d14e854f22825
+                                 https://thanos.io/tip/thanos/logging.md/#configuration
       --tracing.config=<content>
                                  Alternative to 'tracing.config-file' flag
                                  (mutually exclusive). Content of YAML file with

diff --git a/docs/components/rule.md b/docs/components/rule.md
@@ -422,11 +422,11 @@ Flags:
                                  flag (mutually exclusive). Content of YAML file
                                  with request logging configuration. See format
                                  details:
-                                 https://gist.github.com/yashrsharma44/02f5765c5710dd09ce5d14e854f22825
+                                 https://thanos.io/tip/thanos/logging.md/#configuration
       --request.logging-config-file=<file-path>
                                  Path to YAML file with request logging
                                  configuration. See format details:
-                                 https://gist.github.com/yashrsharma44/02f5765c5710dd09ce5d14e854f22825
+                                 https://thanos.io/tip/thanos/logging.md/#configuration
       --resend-delay=1m          Minimum amount of time to wait before resending
                                  an alert to Alertmanager.
       --rule-file=rules/ ...     Rule files that should be used by rule manager.

diff --git a/docs/components/sidecar.md b/docs/components/sidecar.md
@@ -156,11 +156,11 @@ Flags:
                                  flag (mutually exclusive). Content of YAML file
                                  with request logging configuration. See format
                                  details:
-                                 https://gist.github.com/yashrsharma44/02f5765c5710dd09ce5d14e854f22825
+                                 https://thanos.io/tip/thanos/logging.md/#configuration
       --request.logging-config-file=<file-path>
                                  Path to YAML file with request logging
                                  configuration. See format details:
-                                 https://gist.github.com/yashrsharma44/02f5765c5710dd09ce5d14e854f22825
+                                 https://thanos.io/tip/thanos/logging.md/#configuration
       --shipper.upload-compacted
                                  If true shipper will try to upload compacted
                                  blocks as well. Useful for migration purposes.

diff --git a/docs/components/store.md b/docs/components/store.md
@@ -138,11 +138,11 @@ Flags:
                                  flag (mutually exclusive). Content of YAML file
                                  with request logging configuration. See format
                                  details:
-                                 https://gist.github.com/yashrsharma44/02f5765c5710dd09ce5d14e854f22825
+                                 https://thanos.io/tip/thanos/logging.md/#configuration
       --request.logging-config-file=<file-path>
                                  Path to YAML file with request logging
                                  configuration. See format details:
-                                 https://gist.github.com/yashrsharma44/02f5765c5710dd09ce5d14e854f22825
+                                 https://thanos.io/tip/thanos/logging.md/#configuration
       --selector.relabel-config=<content>
                                  Alternative to 'selector.relabel-config-file'
                                  flag (mutually exclusive). Content of YAML file

diff --git a/docs/logging.md b/docs/logging.md
@@ -0,0 +1,134 @@
+# Logging
+
+Thanos supports request logging via flags.
+
+Components are either configured using `--request.logging-config-file` to reference to the configuration file or `--request.logging-config` to provide configuration as YAML directly.
+
+## Configuration
+
+Configuration can be supplied globally, which applies to both `grpc` and `http`. Alternatively `http` and/or `grpc` can be configured independently.
+
+### Options
+
+Valid `level` for `options` should be one of `INFO`, `WARNING`, `ERROR` or `DEBUG`.
+
+```yaml
+options:
+  level: ERROR
+```
+
+The request logging is configurable per phase via the `decision`.
+
+Valid decision combinations are as follows:
+
+* Log details only when the request completes - Log level is determined by the status code from the response.
+
+```yaml
+options:
+  decision:
+    log_start: false
+    log_end: true
+```
+
+* Log details prior to the request and when the request completes - Pre request log is made at `debug` level.
+
+```yaml
+options:
+  decision:
+    log_start: true
+    log_end: true
+```
+
+### HTTP
+
+Specifying an `http` block enables request logging for each endpoint.
+
+```yaml
+http:
+  options:
+    level: DEBUG
+    decision:
+      log_start: true
+      log_end: true
+```
+
+The log level of the "post request" log is determined by the status code in the response.
+
+The following mappings apply:
+* `200 <= status code < 500` = `debug`
+* `status code > 500` = `error`
+
+Optionally, additional configuration can be supplied via the `config` block to create an allowlist of endpoint and port combinations. Note that this feature requires an exact match if enabled.
+
+```yaml
+http:
+  config:
+    - path: /api/v1/query
+      port: 10904
+    - path: /api/v1/app_range/metrics
+      port: 3456
+```
+
+### gRPC
+
+Specifying a `grpc` block enables request logging for each service and method name combination.
+
+```yaml
+grpc:
+  options:
+    level: DEBUG
+    decision:
+      log_start: true
+      log_end: true
+```
+
+The log level of the "post request" log is determined by the [code](https://grpc.github.io/grpc/core/md_doc_statuscodes.html) in the response.
+
+The following mappings apply:
+* Codes `2, 12, 13 ,15` = `error`
+* All other codes = `debug`
+
+Optionally, additional configuration can be supplied via the `config` block to create an allowlist of service and method combinations. Note that this feature requires an exact match if enabled.
+
+```yaml
+grpc:
+  config:
+    - service: thanos.Store
+      method: Info
+```
+
+## How to use `config` flags?
+
+The following example shows how the logging config can be supplied to the `sidecar` component:
+
+```yaml
+      - args:
+        - sidecar
+        - |
+          --objstore.config=type: GCS
+          config:
+            bucket: <bucket>
+        - --prometheus.url=http://localhost:9090
+        - |
+          --request.logging-config=http:
+            config:
+              - path: /api/v1/query
+                port: 10904
+            options:
+              level: DEBUG
+              decision:
+                log_start: true
+                log_end: true
+          grpc:
+            config:
+              - service: thanos.Store
+                method: Info
+            options:
+              level: ERROR
+              decision:
+                log_start: false
+                log_end: true
+        - --tsdb.path=/prometheus-data
+```
+
+Note that in the above example, logs will be emitted at `debug` level. These logs will be filtered unless the flag `--log.level=debug` is set.
diff --git a/pkg/extkingpin/flags.go b/pkg/extkingpin/flags.go
@@ -136,8 +136,7 @@ func RegisterRequestLoggingFlags(app FlagClause) *extflag.PathOrContent {
 	return extflag.RegisterPathOrContent(
 		app,
 		"request.logging-config",
-		// TODO @yashrsharma44: Change the link with the documented link for yaml configuration.
-		"YAML file with request logging configuration. See format details: https://gist.github.com/yashrsharma44/02f5765c5710dd09ce5d14e854f22825",
+		"YAML file with request logging configuration. See format details: https://thanos.io/tip/thanos/logging.md/#configuration",
 		extflag.WithEnvSubstitution(),
 	)
 }