From 523c09b34ee72c5966c7acd80faef2ebf5d31ca6 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Thu, 29 Aug 2024 14:31:23 -0400 Subject: [PATCH] feat: logging requirements and logging hook Signed-off-by: Todd Baert --- specification.json | 7 +++++++ .../appendix-a-included-utilities.md | 21 ++++++++++++++++++- specification/sections/01-flag-evaluation.md | 12 +++++++++++ 3 files changed, 39 insertions(+), 1 deletion(-) diff --git a/specification.json b/specification.json index 1a3b3d31..1de71f07 100644 --- a/specification.json +++ b/specification.json @@ -273,6 +273,13 @@ } ] }, + { + "id": "Requirement 1.4.16", + "machine_id": "requirement_1_4_16", + "content": "Methods, functions, or operations on the client SHOULD NOT write log messages.", + "RFC 2119 keyword": "SHOULD NOT", + "children": [] + }, { "id": "Requirement 1.5.1", "machine_id": "requirement_1_5_1", diff --git a/specification/appendix-a-included-utilities.md b/specification/appendix-a-included-utilities.md index e972d01c..dfd9786a 100644 --- a/specification/appendix-a-included-utilities.md +++ b/specification/appendix-a-included-utilities.md @@ -11,7 +11,7 @@ This document contains requirements for auxiliary utilities provided by the SDK, ## In-memory provider -> Language-specific OpenFeature SDK implementations **SHOULD** expose an in-memory provider built into the SDK. +> OpenFeature SDK implementations **SHOULD** provide an `in-memory provider`. The in-memory provider is intended to be used for testing; SDK consumers may use it for their use cases. Hence, the packaging, naming, and access modifiers must be set appropriately. @@ -360,3 +360,22 @@ Providers can contain metadata. The Multi-Provider will make that metadata avail }, } ``` + +## Logging Hook + +> OpenFeature SDK implementations **SHOULD** provide a `logging hook`. + +The logging hook is a hook which logs messages during the flag evaluation life-cycle as described below: + +| Stage | Logged data | +| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| before | `stage`, `domain`, `provider name`, `flag key`, `default value` and `evaluation context` (serialized, opt-in) | +| after | `stage`, `domain`, `provider name`, `flag key`, `default value`, `evaluation context` (serialized, opt-in), `reason`, and `variant` (or stringified `value` if not available) | +| error | `stage`, `domain`, `provider name`, `flag key`, `default value`, `evaluation context` (serialized, opt-in), `reason`, `error code`, and `error message` | +| finally | N/A | + +> The evaluation context **SHOULD** only be logged if an associated option indicates so. + +> If logging the evaluation context is enabled, it **MUST** be printed in such a way that it's human readable. + +> If the logger abstraction in the SDK supports a log level concept, the appropriate log level **SHOULD** be used for each stage (before/after: info, error: error). diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md index 43b72000..496443ba 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -381,6 +381,18 @@ This `flag metadata` field is intended as a mechanism for providers to surface a > Condition: `Flag metadata` **MUST** be immutable. +#### Requirement 1.4.16 + +> Methods, functions, or operations on the client **SHOULD NOT** write log messages. + +The client methods (particularly the evaluation methods) run in hot code paths. +Logging (even at error level) can cause a huge volume of log entries. +For example, in a circumstance in which an application expecting a particular flag to exist is deployed in advance of that flag's being defined in the management system, logs can become inundated with `FLAG_NOT_FOUND` messages and related stack traces. +Logging in these code paths is highly discouraged. +Application authors can attach a [logging hook](../appendix-a-included-utilities.md#logging-hook) or author their own custom logging hook(s) to help with debugging or satisfy their particular logging needs. + +Logging is encouraged in functions to do with configuration, initialization, shutdown, etc. + ### Evaluation Options #### Requirement 1.5.1