From 676ea4b6c01b1bc5a3e45ca563099dac4acd448a Mon Sep 17 00:00:00 2001 From: Philip Gough Date: Wed, 9 Feb 2022 17:55:21 +0000 Subject: [PATCH] Document request logging configuration (#4934) * docs: Add instructions for configuring request logging Signed-off-by: Philip Gough * docs: Update link to logging config and make docs Signed-off-by: Philip Gough Signed-off-by: Nicholaswang --- docs/components/query-frontend.md | 4 +- docs/components/query.md | 4 +- docs/components/receive.md | 4 +- docs/components/rule.md | 4 +- docs/components/sidecar.md | 4 +- docs/components/store.md | 4 +- docs/logging.md | 134 ++++++++++++++++++++++++++++++ pkg/extkingpin/flags.go | 3 +- 8 files changed, 147 insertions(+), 14 deletions(-) create mode 100644 docs/logging.md diff --git a/docs/components/query-frontend.md b/docs/components/query-frontend.md index f11bc3c5c2..41959b558d 100644 --- 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= 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= 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 index 9c99939a7c..456a0359d0 100644 --- 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= 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=="" ... Query selector labels that will be exposed in info endpoint (repeated). diff --git a/docs/components/receive.md b/docs/components/receive.md index c0fe792284..26881703b7 100644 --- 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= 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= 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 index 9676d3a60a..5c2f81f8fe 100644 --- 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= 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 index 31120cc3f9..57b69311b4 100644 --- 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= 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 index e179139fbb..73fbee210a 100644 --- 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= 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= Alternative to 'selector.relabel-config-file' flag (mutually exclusive). Content of YAML file diff --git a/docs/logging.md b/docs/logging.md new file mode 100644 index 0000000000..af49a145d6 --- /dev/null +++ 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: + - --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 index 8f1f1c7608..59aaccf8b8 100644 --- 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(), ) }