From f68e29d4584e3c5dbae170c1d76e939911cff25b Mon Sep 17 00:00:00 2001 From: Bernard Grymonpon Date: Fri, 8 Dec 2023 15:17:56 +0100 Subject: [PATCH 1/8] add guidelines on metrics and log messages Signed-off-by: Bernard Grymonpon --- CONTRIBUTING.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cc8ee1175db..475c438a5d2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,6 +56,34 @@ check the [test documentation](./tests/README.md). Those tests are run nightly o Another easy way to contribute is improving the validations to avoid misconfigurations. New rules can be added in the proper type's webhooks file (`apis/keda/v1alpha1/*_webhook.go`). + +## Metrics and Logging + +### Metrics + +Incorporating Prometheus and OpenTelemetry metrics is essential in our project. When creating metrics, please consider the following guidelines: + +- Always specify the unit in the metric name using standard units (e.g., use seconds instead of milliseconds, bytes instead of megabytes, etc.). +- Choose descriptive metric names. Instead of vague names like `message_number` or `triggers`, opt for more specific ones like `queued_messages` and `trigger_registered`. +- Ensure consistency in metric naming. Review existing metrics for their naming patterns and try to align new metrics accordingly. +- Utilize labels for differentiating metric states. Instead of creating separate metrics like `messages_sent_successfully` and `messages_sent_failed`, create a single metric `messages_sent` and differentiate using a label `state` with values `success` or `failed`. +- Avoid overly detailed metrics. Refrain from using labels with high cardinality (such as _email_, _message-id_, or _time_), as this can burden the system. +- Favor metrics that are cumulative counters. Users can then apply functions like `rate()` to calculate changes over time. Append `total` for Prometheus and `count` for OpenTelemetry metrics. +- Provide clear descriptions. + +For further guidance on metric naming and labeling, refer to the recommendations in the [Prometheus](https://prometheus.io/docs/practices/naming/) and [OpenTelemetry](https://opentelemetry.io/docs/specs/semconv/general/metrics/) documentation. + +### Logging and Log Messages + +When adding log messages to the project, it's crucial to set the appropriate log level and tailor the message for its intended audience: +- Use `debug` level for Keda project developers, who possess deep knowledge of the system's inner workings. Messages should be data-rich and detailed. +- Set to `info` level for engineers familiar with Keda's components but not its intricate details. These messages should serve as updates or milestones regarding the system's sub-components, essentially acting as a status report. +- `Warning` level and above is aimed at operational teams. Messages should be clear, concise, and either indicate consequences or be actionable, with suggestions for next steps. Include links to further documentation where possible. A `warning` should indicate a problem which should be adressed in the near future, if it persists. An `error` indicates a failure, and a part of the system is not capable of fulfilling it's intended purpose. A warning should contain at least the consequence, an error should contain what part failed, why, and possible solutions. + +### Legacy + +Some of the metrics and log messages in the project don't follow the above practices, but are there for historical reasons. When refactoring pieces of code, please try to apply the best practices to any log message or metric which is impacted. + ## Changelog Every change should be added to our changelog under `Unreleased` which is located in `CHANGELOG.md`. This helps us keep track of all changes in a given release. From 5a045a90164dbc3e2f9d5eb26e9e014aac80874c Mon Sep 17 00:00:00 2001 From: Bernard Grymonpon Date: Mon, 11 Dec 2023 08:19:21 +0100 Subject: [PATCH 2/8] Apply suggestions from code review Co-authored-by: Tom Kerkhove Signed-off-by: Bernard Grymonpon --- CONTRIBUTING.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 475c438a5d2..38cc6e4aacc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,20 +56,19 @@ check the [test documentation](./tests/README.md). Those tests are run nightly o Another easy way to contribute is improving the validations to avoid misconfigurations. New rules can be added in the proper type's webhooks file (`apis/keda/v1alpha1/*_webhook.go`). - ## Metrics and Logging ### Metrics Incorporating Prometheus and OpenTelemetry metrics is essential in our project. When creating metrics, please consider the following guidelines: -- Always specify the unit in the metric name using standard units (e.g., use seconds instead of milliseconds, bytes instead of megabytes, etc.). -- Choose descriptive metric names. Instead of vague names like `message_number` or `triggers`, opt for more specific ones like `queued_messages` and `trigger_registered`. -- Ensure consistency in metric naming. Review existing metrics for their naming patterns and try to align new metrics accordingly. -- Utilize labels for differentiating metric states. Instead of creating separate metrics like `messages_sent_successfully` and `messages_sent_failed`, create a single metric `messages_sent` and differentiate using a label `state` with values `success` or `failed`. -- Avoid overly detailed metrics. Refrain from using labels with high cardinality (such as _email_, _message-id_, or _time_), as this can burden the system. -- Favor metrics that are cumulative counters. Users can then apply functions like `rate()` to calculate changes over time. Append `total` for Prometheus and `count` for OpenTelemetry metrics. -- Provide clear descriptions. +- **Always specify the unit in the metric name using standard units** (e.g., use seconds instead of milliseconds, bytes instead of megabytes, etc.). +- **Choose descriptive metric names**. Instead of vague names like `message_number` or `triggers`, opt for more specific ones like `queued_messages` and `trigger_registered`. +- **Ensure consistency in metric naming**. Review existing metrics for their naming patterns and try to align new metrics accordingly. +- **Utilize labels for differentiating metric states**. Instead of creating separate metrics like `messages_sent_successfully` and `messages_sent_failed`, create a single metric `messages_sent` and differentiate using a label `state` with values `success` or `failed`. +- **Avoid overly detailed metrics**. Refrain from using labels with high cardinality (such as _email_, _message-id_, or _time_), as this can burden the system. +- **Favor metrics that are cumulative counters**. Users can then apply functions like `rate()` to calculate changes over time. Append `total` for Prometheus and `count` for OpenTelemetry metrics. +- **Provide clear descriptions**. This should tell end-users what the metrics represent, without being a KEDA expert nor technical person. For further guidance on metric naming and labeling, refer to the recommendations in the [Prometheus](https://prometheus.io/docs/practices/naming/) and [OpenTelemetry](https://opentelemetry.io/docs/specs/semconv/general/metrics/) documentation. From 0eb3821480b2fae4c1fb6b3f56b8e1617326abb4 Mon Sep 17 00:00:00 2001 From: Bernard Grymonpon Date: Mon, 11 Dec 2023 12:15:42 +0100 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Zbynek Roubalik Signed-off-by: Bernard Grymonpon --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 38cc6e4aacc..40682fce846 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -76,8 +76,9 @@ For further guidance on metric naming and labeling, refer to the recommendations When adding log messages to the project, it's crucial to set the appropriate log level and tailor the message for its intended audience: - Use `debug` level for Keda project developers, who possess deep knowledge of the system's inner workings. Messages should be data-rich and detailed. -- Set to `info` level for engineers familiar with Keda's components but not its intricate details. These messages should serve as updates or milestones regarding the system's sub-components, essentially acting as a status report. -- `Warning` level and above is aimed at operational teams. Messages should be clear, concise, and either indicate consequences or be actionable, with suggestions for next steps. Include links to further documentation where possible. A `warning` should indicate a problem which should be adressed in the near future, if it persists. An `error` indicates a failure, and a part of the system is not capable of fulfilling it's intended purpose. A warning should contain at least the consequence, an error should contain what part failed, why, and possible solutions. +- Set to `info` level for engineers familiar with KEDA's components but not its intricate details. These messages should serve as updates or milestones regarding the system's sub-components, essentially acting as a status report. In the code an info message is written via `Info()` method on the logger, eg. `logger.Info(msg)`. +- `Warning` level and above is aimed at operational teams. Messages should be clear, concise, and either indicate consequences or be actionable, with suggestions for next steps. Include links to further documentation where possible. A `warning` should indicate a problem which should be adressed in the near future, if it persists. In the code a warning is written via `Info()` method on the logger with a `"Warning:"` prefix in the message, eg. `logger.Info("Warning: ...msg")`. +- An `error` indicates a failure, and a part of the system is not capable of fulfilling it's intended purpose. A warning should contain at least the consequence, an error should contain what part failed, why, and possible solutions. In the code an error is usually written via `Error()` method on the logger, eg. `logger.Error(err, msg)`. ### Legacy From 8875b15a077a6b59407ad080d9f5dd9a14a5c656 Mon Sep 17 00:00:00 2001 From: Bernard Grymonpon Date: Mon, 11 Dec 2023 12:15:54 +0100 Subject: [PATCH 4/8] Apply suggestions from code review Co-authored-by: Zbynek Roubalik Signed-off-by: Bernard Grymonpon --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 40682fce846..65290006d00 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -75,7 +75,7 @@ For further guidance on metric naming and labeling, refer to the recommendations ### Logging and Log Messages When adding log messages to the project, it's crucial to set the appropriate log level and tailor the message for its intended audience: -- Use `debug` level for Keda project developers, who possess deep knowledge of the system's inner workings. Messages should be data-rich and detailed. +- Use `debug` level for KEDA project developers, who possess deep knowledge of the system's inner workings. Messages should be data-rich and detailed. In the code a debug message is written via verbosity level 1 on the `Info()` method on the logger, eg. `logger.V(1).Info(msg)`. - Set to `info` level for engineers familiar with KEDA's components but not its intricate details. These messages should serve as updates or milestones regarding the system's sub-components, essentially acting as a status report. In the code an info message is written via `Info()` method on the logger, eg. `logger.Info(msg)`. - `Warning` level and above is aimed at operational teams. Messages should be clear, concise, and either indicate consequences or be actionable, with suggestions for next steps. Include links to further documentation where possible. A `warning` should indicate a problem which should be adressed in the near future, if it persists. In the code a warning is written via `Info()` method on the logger with a `"Warning:"` prefix in the message, eg. `logger.Info("Warning: ...msg")`. - An `error` indicates a failure, and a part of the system is not capable of fulfilling it's intended purpose. A warning should contain at least the consequence, an error should contain what part failed, why, and possible solutions. In the code an error is usually written via `Error()` method on the logger, eg. `logger.Error(err, msg)`. From db75bfba1d8f01249c59ff572e48fff6984aed00 Mon Sep 17 00:00:00 2001 From: Zbynek Roubalik Date: Mon, 11 Dec 2023 13:05:26 +0100 Subject: [PATCH 5/8] Update CONTRIBUTING.md Co-authored-by: Bernard Grymonpon Signed-off-by: Zbynek Roubalik --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 65290006d00..94888187951 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -78,7 +78,7 @@ When adding log messages to the project, it's crucial to set the appropriate log - Use `debug` level for KEDA project developers, who possess deep knowledge of the system's inner workings. Messages should be data-rich and detailed. In the code a debug message is written via verbosity level 1 on the `Info()` method on the logger, eg. `logger.V(1).Info(msg)`. - Set to `info` level for engineers familiar with KEDA's components but not its intricate details. These messages should serve as updates or milestones regarding the system's sub-components, essentially acting as a status report. In the code an info message is written via `Info()` method on the logger, eg. `logger.Info(msg)`. - `Warning` level and above is aimed at operational teams. Messages should be clear, concise, and either indicate consequences or be actionable, with suggestions for next steps. Include links to further documentation where possible. A `warning` should indicate a problem which should be adressed in the near future, if it persists. In the code a warning is written via `Info()` method on the logger with a `"Warning:"` prefix in the message, eg. `logger.Info("Warning: ...msg")`. -- An `error` indicates a failure, and a part of the system is not capable of fulfilling it's intended purpose. A warning should contain at least the consequence, an error should contain what part failed, why, and possible solutions. In the code an error is usually written via `Error()` method on the logger, eg. `logger.Error(err, msg)`. +- An `error` indicates a failure, and a part of the system is not capable of fulfilling its intended purpose. An error should contain what part failed, why, and possible solutions. In the code an error is usually written via the `Error()` method on the logger, eg. `logger.Error(err, msg)`. ### Legacy From 20a61674dc8cddfd3cbde6ee854580b9d1573bb9 Mon Sep 17 00:00:00 2001 From: Zbynek Roubalik Date: Mon, 11 Dec 2023 13:05:31 +0100 Subject: [PATCH 6/8] Update CONTRIBUTING.md Co-authored-by: Bernard Grymonpon Signed-off-by: Zbynek Roubalik --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94888187951..aa7d4a30e1a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -77,7 +77,7 @@ For further guidance on metric naming and labeling, refer to the recommendations When adding log messages to the project, it's crucial to set the appropriate log level and tailor the message for its intended audience: - Use `debug` level for KEDA project developers, who possess deep knowledge of the system's inner workings. Messages should be data-rich and detailed. In the code a debug message is written via verbosity level 1 on the `Info()` method on the logger, eg. `logger.V(1).Info(msg)`. - Set to `info` level for engineers familiar with KEDA's components but not its intricate details. These messages should serve as updates or milestones regarding the system's sub-components, essentially acting as a status report. In the code an info message is written via `Info()` method on the logger, eg. `logger.Info(msg)`. -- `Warning` level and above is aimed at operational teams. Messages should be clear, concise, and either indicate consequences or be actionable, with suggestions for next steps. Include links to further documentation where possible. A `warning` should indicate a problem which should be adressed in the near future, if it persists. In the code a warning is written via `Info()` method on the logger with a `"Warning:"` prefix in the message, eg. `logger.Info("Warning: ...msg")`. +- `Warning` level and above is aimed at operational teams. Messages should be clear, concise, and either indicate consequences or be actionable, with suggestions for next steps. It indicates a problem which should be addressed in the near future if it persists. The message should contain at least the consequence. Include links to further documentation where possible. In the code a warning is written via the `Info()` method on the logger with a `"Warning:"` prefix in the message, eg. `logger.Info("Warning: ...msg")`. - An `error` indicates a failure, and a part of the system is not capable of fulfilling its intended purpose. An error should contain what part failed, why, and possible solutions. In the code an error is usually written via the `Error()` method on the logger, eg. `logger.Error(err, msg)`. ### Legacy From 8495afec4880ac0556fe913ee940e5dd619a8c7b Mon Sep 17 00:00:00 2001 From: Zbynek Roubalik Date: Mon, 11 Dec 2023 13:26:21 +0100 Subject: [PATCH 7/8] Update CONTRIBUTING.md Signed-off-by: Zbynek Roubalik --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aa7d4a30e1a..e586063ffd4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,7 +82,7 @@ When adding log messages to the project, it's crucial to set the appropriate log ### Legacy -Some of the metrics and log messages in the project don't follow the above practices, but are there for historical reasons. When refactoring pieces of code, please try to apply the best practices to any log message or metric which is impacted. +Some of the metrics and log messages in the project don't follow the above practices, but are there for historical reasons. When refactoring pieces of code, please try to apply the best practices to any log message or metric which is impacted. ## Changelog From b5f9834a95579141150c92553ddbabea6f7c039a Mon Sep 17 00:00:00 2001 From: Bernard Grymonpon Date: Mon, 11 Dec 2023 16:02:47 +0100 Subject: [PATCH 8/8] TOC updated Signed-off-by: Bernard Grymonpon --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e586063ffd4..761e0e0afb5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,6 +14,10 @@ There are many areas we can use contributions - ranging from code, documentation - [Contributing Scalers](#contributing-scalers) - [Testing](#testing) - [Contributing webhooks](#contributing-webhooks) +- [Metrics and Logging](#metrics-and-logging) + - [Metrics](#metrics) + - [Logging and Log Messages](#logging-and-log-messages) + - [Legacy](#legacy) - [Changelog](#changelog) - [Including Documentation Changes](#including-documentation-changes) - [Creating and building a local environment](#creating-and-building-a-local-environment)