feat: logging requirements and logging hook

Signed-off-by: Todd Baert <[email protected]>

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",

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).

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