From 02d641da67967b7e3e0f210fe11adec077d82f3b Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Fri, 24 Oct 2025 17:59:42 +0000 Subject: [PATCH 01/12] add telemetry hook implementation guidelines Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 68 +++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index d2f77644..50a1b5a1 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -51,6 +51,74 @@ The following describes how keys in [flag metadata](types.md#flag-metadata) are | ---------------------------- | ----------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------ | | `feature_flag.provider.name` | `name` | `Recommended` | `string` | The name of the provider as defined in the `provider metadata`, available in the `hook context`. | +## Telemetry Hook Implementation Guide + +This section provides guidance for implementing observability hooks that emit OpenTelemetry signals during feature flag evaluations. The recommendations ensure consistency across SDK implementations while allowing for language-specific idioms. + +### Signal Emission Patterns + +Telemetry hooks can emit OpenTelemetry signals in three distinct ways: + +| Pattern | Recommended | Advantages | Disadvantages | +| -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Span Events** | ✓ | Associates flag evaluations with existing traces. Minimal overhead - no additional spans created. Maintains trace context relationships. Low cardinality impact. | Requires an active span to function. Must gracefully handle absence of active span. Limited to span lifetime and context. | +| **Event Logging** | | Works independently without active spans. Aligns with OpenTelemetry's emerging direction. Suitable for environments without tracing. Simpler implementation model. | No automatic trace correlation. May require separate correlation mechanisms. Event logging standards still evolving. | +| **Standalone Spans** | | Complete distributed tracing per evaluation. Detailed timing information. Full span lifecycle control. Rich performance metrics. | High cardinality - one span per evaluation. Increased overhead and resource usage. Potential performance impact at scale. More complex implementation. | + +> [!NOTE] +> While span events are recommended for their low overhead and ease of use, OpenTelemetry is trending toward using log-based events instead of span events. SDK implementations may choose to prioritize event logging as standards evolve. + +### Hook Lifecycle Implementation + +#### Before Stage + +The `before` hook stage is primarily used by standalone span hooks to create and store spans. When creating spans, it's recommended to store them in hook data using a consistent, documented key for easy retrieval in later stages. + +#### Finally Stage + +The `finally` hook stage is where telemetry signals are emitted with complete evaluation details. This stage should include all required and conditionally required attributes as defined in the evaluation details mapping table. It's also responsible for proper resource cleanup (like ending spans or closing connections) while ensuring it doesn't throw exceptions that could affect flag evaluation. + +#### Error Stage + +The `error` hook stage records exception information unless explicitly configured to exclude it. Implementations typically use OpenTelemetry's standard exception recording semantics (`recordException` for spans, exception log events for event logging). Configuration options like `excludeExceptions` allow users to control this behavior based on their needs. + +### Attribute Transformations + +When building telemetry attributes, implementations should extract and map well-known fields from flag metadata to their corresponding event record attributes as defined in the Flag Metadata table above. Remember to transform enumeration values (like error codes and reasons) from OpenFeature's uppercase format to OpenTelemetry's lowercase snake_case convention. + +### Value Handling and Privacy + +Flag values can contain sensitive data, so implementations should provide configuration to control whether values are included in telemetry signals. A safe default that protects potentially sensitive data is recommended. When values are included, they need to be serialized appropriately for the telemetry backend. + +Consider providing mechanisms to redact or obfuscate sensitive flag values, along with size limits to prevent telemetry bloat. This helps balance observability needs with privacy and performance concerns. + +### Configuration Options + +For consistency across implementations, consider supporting a common set of configuration options: + +- `excludeExceptions` (boolean): Whether to exclude exception recording in telemetry +- `includeValue` (boolean): Whether to include flag values in telemetry signals +- `maxValueLength` (integer): Maximum size for flag values before redaction +- `shouldRedact` (function): Custom function to determine value redaction + +### Error Handling + +Hooks should be designed to never throw exceptions that interrupt flag evaluation. Any internal errors can be logged at appropriate levels (debug/trace) without affecting application execution. While the OpenFeature SDK has error handling to capture hook exceptions, it's best practice to handle errors gracefully within the hook itself. + +### Implementation Patterns + +#### Common Base Class + +In object-oriented languages, you might find it helpful to create a base hook class containing common functionality shared across all telemetry hook types. This typically includes: + +- Shared configuration options +- Attribute building and transformation methods +- Enumeration format conversion +- Metadata extraction logic +- Logger instances for internal debugging + +This pattern can reduce code duplication and ensure consistency across different hook implementations, though it's not required. + ## History Feature flags in the OpenTelemetry semantic conventions are currently in development and are marked as experimental. From 49f870157d2196889ea4aeef0a01efc14b9a32cd Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Fri, 24 Oct 2025 18:21:25 +0000 Subject: [PATCH 02/12] improve the pros/cons section Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index 50a1b5a1..2c4970d6 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -61,9 +61,9 @@ Telemetry hooks can emit OpenTelemetry signals in three distinct ways: | Pattern | Recommended | Advantages | Disadvantages | | -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Span Events** | ✓ | Associates flag evaluations with existing traces. Minimal overhead - no additional spans created. Maintains trace context relationships. Low cardinality impact. | Requires an active span to function. Must gracefully handle absence of active span. Limited to span lifetime and context. | +| **Span Events** | ✓ | Leverages existing trace configuration and tooling. Minimal overhead - no additional spans created. Maintains trace context relationships. Simpler than creating spans. | Requires an active span to function. Must gracefully handle absence of active span. Limited to span lifetime and context. | | **Event Logging** | | Works independently without active spans. Aligns with OpenTelemetry's emerging direction. Suitable for environments without tracing. Simpler implementation model. | No automatic trace correlation. May require separate correlation mechanisms. Event logging standards still evolving. | -| **Standalone Spans** | | Complete distributed tracing per evaluation. Detailed timing information. Full span lifecycle control. Rich performance metrics. | High cardinality - one span per evaluation. Increased overhead and resource usage. Potential performance impact at scale. More complex implementation. | +| **Standalone Spans** | | Complete distributed tracing per evaluation. Detailed timing information. Full span lifecycle control. Rich performance metrics. | Creates one span per evaluation. May clutter trace visualizations. Increased overhead and resource usage. Potential performance impact at scale. More complex implementation. | > [!NOTE] > While span events are recommended for their low overhead and ease of use, OpenTelemetry is trending toward using log-based events instead of span events. SDK implementations may choose to prioritize event logging as standards evolve. From 963d850ac7e578a514669f62a3a80065ea358f64 Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Fri, 24 Oct 2025 14:39:05 -0400 Subject: [PATCH 03/12] Apply suggestion from @gemini-code-assist[bot] Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index 2c4970d6..b41b4810 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -76,7 +76,7 @@ The `before` hook stage is primarily used by standalone span hooks to create and #### Finally Stage -The `finally` hook stage is where telemetry signals are emitted with complete evaluation details. This stage should include all required and conditionally required attributes as defined in the evaluation details mapping table. It's also responsible for proper resource cleanup (like ending spans or closing connections) while ensuring it doesn't throw exceptions that could affect flag evaluation. +The `finally` hook stage is where telemetry signals are emitted with complete evaluation details. This stage should include all required and conditionally required attributes as defined in the attribute mapping tables above. It's also responsible for proper resource cleanup (like ending spans or closing connections) while ensuring it doesn't throw exceptions that could affect flag evaluation. #### Error Stage From a143f0d486163ed4ba8575157d2fa1fb5af305e8 Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Fri, 24 Oct 2025 19:13:15 +0000 Subject: [PATCH 04/12] improve table layout and content Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index b41b4810..11ff64ab 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -59,14 +59,14 @@ This section provides guidance for implementing observability hooks that emit Op Telemetry hooks can emit OpenTelemetry signals in three distinct ways: -| Pattern | Recommended | Advantages | Disadvantages | -| -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Span Events** | ✓ | Leverages existing trace configuration and tooling. Minimal overhead - no additional spans created. Maintains trace context relationships. Simpler than creating spans. | Requires an active span to function. Must gracefully handle absence of active span. Limited to span lifetime and context. | -| **Event Logging** | | Works independently without active spans. Aligns with OpenTelemetry's emerging direction. Suitable for environments without tracing. Simpler implementation model. | No automatic trace correlation. May require separate correlation mechanisms. Event logging standards still evolving. | -| **Standalone Spans** | | Complete distributed tracing per evaluation. Detailed timing information. Full span lifecycle control. Rich performance metrics. | Creates one span per evaluation. May clutter trace visualizations. Increased overhead and resource usage. Potential performance impact at scale. More complex implementation. | +| Pattern | Advantages | Disadvantages | +| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Span Events**
![recommended](https://img.shields.io/badge/recommended-green) | - Leverages existing trace configuration and tooling
- Minimal overhead, no additional spans created
- Maintains trace context relationships
- Simpler than creating spans | - Requires an active span to function
- Must gracefully handle absence of active span
- Limited to span lifetime and context. | +| **Event Logging** | - Works independently without active spans
- Aligns with OpenTelemetry's emerging direction
- Suitable for environments without tracing
- Simpler implementation model | - Requires an event exporter to be configured
- May require separate correlation mechanisms
- Event logging standards still evolving | +| **Standalone Spans** | - Distributed traces contain every evaluation
- Detailed timing information
- Full span lifecycle control | - Creates one span per evaluation
- May clutter trace visualizations
- Increased overhead and resource usage
- Potential performance impact at scale
- More complex implementation | > [!NOTE] -> While span events are recommended for their low overhead and ease of use, OpenTelemetry is trending toward using log-based events instead of span events. SDK implementations may choose to prioritize event logging as standards evolve. +> While span events are recommended for their low overhead and ease of use, OpenTelemetry is trending toward using log-based events instead of span events. SDK implementations may choose to prioritize event logging as standards evolve. Please refer to the [OpenTelemetry Span Event Deprecation Plan][otel-span-event-deprecation-plan] for more details. ### Hook Lifecycle Implementation @@ -139,3 +139,4 @@ The following table describes the history of changes to the OpenTelemetry featur [^3]: Include `error.type` and `error.message`, if and only if an error occurred during a flag evaluation. [otel-ff-events]: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/ +[otel-span-event-deprecation-plan]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/4430-span-event-api-deprecation-plan.md From 299112c2a17127fab8e84e22a5473fcb5bbd237a Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Fri, 24 Oct 2025 19:32:34 +0000 Subject: [PATCH 05/12] improve table content, reorder hooks Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index 11ff64ab..f1104036 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -62,7 +62,7 @@ Telemetry hooks can emit OpenTelemetry signals in three distinct ways: | Pattern | Advantages | Disadvantages | | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Span Events**
![recommended](https://img.shields.io/badge/recommended-green) | - Leverages existing trace configuration and tooling
- Minimal overhead, no additional spans created
- Maintains trace context relationships
- Simpler than creating spans | - Requires an active span to function
- Must gracefully handle absence of active span
- Limited to span lifetime and context. | -| **Event Logging** | - Works independently without active spans
- Aligns with OpenTelemetry's emerging direction
- Suitable for environments without tracing
- Simpler implementation model | - Requires an event exporter to be configured
- May require separate correlation mechanisms
- Event logging standards still evolving | +| **Event Logging** | - Works independently without active spans
- Aligns with OpenTelemetry's emerging direction
- Suitable for environments without tracing
- Simpler implementation model | - Requires an event exporter to be configured
- Processed and stored separately from spans
- Event logging standards still evolving | | **Standalone Spans** | - Distributed traces contain every evaluation
- Detailed timing information
- Full span lifecycle control | - Creates one span per evaluation
- May clutter trace visualizations
- Increased overhead and resource usage
- Potential performance impact at scale
- More complex implementation | > [!NOTE] @@ -74,14 +74,14 @@ Telemetry hooks can emit OpenTelemetry signals in three distinct ways: The `before` hook stage is primarily used by standalone span hooks to create and store spans. When creating spans, it's recommended to store them in hook data using a consistent, documented key for easy retrieval in later stages. -#### Finally Stage - -The `finally` hook stage is where telemetry signals are emitted with complete evaluation details. This stage should include all required and conditionally required attributes as defined in the attribute mapping tables above. It's also responsible for proper resource cleanup (like ending spans or closing connections) while ensuring it doesn't throw exceptions that could affect flag evaluation. - #### Error Stage The `error` hook stage records exception information unless explicitly configured to exclude it. Implementations typically use OpenTelemetry's standard exception recording semantics (`recordException` for spans, exception log events for event logging). Configuration options like `excludeExceptions` allow users to control this behavior based on their needs. +#### Finally Stage + +The `finally` hook stage is where telemetry signals are emitted with complete evaluation details. This stage should include all required and conditionally required attributes as defined in the attribute mapping tables above. It's also responsible for proper resource cleanup (like ending spans or closing connections) while ensuring it doesn't throw exceptions that could affect flag evaluation. + ### Attribute Transformations When building telemetry attributes, implementations should extract and map well-known fields from flag metadata to their corresponding event record attributes as defined in the Flag Metadata table above. Remember to transform enumeration values (like error codes and reasons) from OpenFeature's uppercase format to OpenTelemetry's lowercase snake_case convention. From 4da27848dbc2aa53a64599a95bcd275ad99e794f Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Mon, 27 Oct 2025 18:52:10 +0000 Subject: [PATCH 06/12] address pr feedback Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index f1104036..2bc56bb7 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -66,7 +66,7 @@ Telemetry hooks can emit OpenTelemetry signals in three distinct ways: | **Standalone Spans** | - Distributed traces contain every evaluation
- Detailed timing information
- Full span lifecycle control | - Creates one span per evaluation
- May clutter trace visualizations
- Increased overhead and resource usage
- Potential performance impact at scale
- More complex implementation | > [!NOTE] -> While span events are recommended for their low overhead and ease of use, OpenTelemetry is trending toward using log-based events instead of span events. SDK implementations may choose to prioritize event logging as standards evolve. Please refer to the [OpenTelemetry Span Event Deprecation Plan][otel-span-event-deprecation-plan] for more details. +> While span events are recommended for their low overhead and ease of use, OpenTelemetry is trending toward using log-based events instead of span events. Please refer to the [OpenTelemetry Span Event Deprecation Plan][otel-span-event-deprecation-plan] for more details. ### Hook Lifecycle Implementation @@ -76,7 +76,7 @@ The `before` hook stage is primarily used by standalone span hooks to create and #### Error Stage -The `error` hook stage records exception information unless explicitly configured to exclude it. Implementations typically use OpenTelemetry's standard exception recording semantics (`recordException` for spans, exception log events for event logging). Configuration options like `excludeExceptions` allow users to control this behavior based on their needs. +The `error` hook stage records exception information unless explicitly configured to exclude it. Implementations typically use [OpenTelemetry's standard exception][otle-record-error] recording semantics (`recordException` for spans, exception log events for event logging). Configuration options like `excludeExceptions` allow users to control this behavior based on their needs. #### Finally Stage @@ -100,6 +100,7 @@ For consistency across implementations, consider supporting a common set of conf - `includeValue` (boolean): Whether to include flag values in telemetry signals - `maxValueLength` (integer): Maximum size for flag values before redaction - `shouldRedact` (function): Custom function to determine value redaction +- `attributeMapper` (function): Custom function to add additional attributes to the signal ### Error Handling @@ -121,7 +122,7 @@ This pattern can reduce code duplication and ensure consistency across different ## History -Feature flags in the OpenTelemetry semantic conventions are currently in development and are marked as experimental. +Feature flags in the OpenTelemetry semantic conventions are currently in development and are marked as a release candidate. The following table describes the history of changes to the OpenTelemetry feature flag event records as it progresses towards a stable release. | Original Field Name | New Field Name | Semantic Convention Release | @@ -140,3 +141,4 @@ The following table describes the history of changes to the OpenTelemetry featur [otel-ff-events]: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/ [otel-span-event-deprecation-plan]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/4430-span-event-api-deprecation-plan.md +[otle-record-error]: https://opentelemetry.io/docs/specs/semconv/general/recording-errors/ From ae9d64c530265417e992222d049e58c4385b7924 Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Mon, 27 Oct 2025 19:03:48 +0000 Subject: [PATCH 07/12] add span name, update value section Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index 2bc56bb7..eb909803 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -72,7 +72,7 @@ Telemetry hooks can emit OpenTelemetry signals in three distinct ways: #### Before Stage -The `before` hook stage is primarily used by standalone span hooks to create and store spans. When creating spans, it's recommended to store them in hook data using a consistent, documented key for easy retrieval in later stages. +The `before` hook stage is primarily used by standalone span hooks to create and store spans. When creating spans, it's recommended to use the name `feature_flag.evaluation` and store them in hook data using a consistent, documented key for easy retrieval in later stages. #### Error Stage @@ -88,7 +88,7 @@ When building telemetry attributes, implementations should extract and map well- ### Value Handling and Privacy -Flag values can contain sensitive data, so implementations should provide configuration to control whether values are included in telemetry signals. A safe default that protects potentially sensitive data is recommended. When values are included, they need to be serialized appropriately for the telemetry backend. +Flag values can contain large or sensitive data, so implementations should provide configuration to control whether values are included in telemetry signals. It's the users' responsibility to manage this configuration. When values are included, they need to be serialized appropriately for OpenTelemetry. Consider providing mechanisms to redact or obfuscate sensitive flag values, along with size limits to prevent telemetry bloat. This helps balance observability needs with privacy and performance concerns. From 3bf249b2923359b6562f07a9d5a929b7c396cec2 Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Thu, 30 Oct 2025 12:34:12 -0400 Subject: [PATCH 08/12] Apply suggestion from @askpt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: André Silva <2493377+askpt@users.noreply.github.com> Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index eb909803..e259bc3f 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -76,7 +76,7 @@ The `before` hook stage is primarily used by standalone span hooks to create and #### Error Stage -The `error` hook stage records exception information unless explicitly configured to exclude it. Implementations typically use [OpenTelemetry's standard exception][otle-record-error] recording semantics (`recordException` for spans, exception log events for event logging). Configuration options like `excludeExceptions` allow users to control this behavior based on their needs. +The `error` hook stage records exception information unless explicitly configured to exclude it. Implementations typically use [OpenTelemetry's standard exception][otel-record-error] recording semantics (`recordException` for spans, exception log events for event logging). Configuration options like `excludeExceptions` allow users to control this behavior based on their needs. #### Finally Stage From 2cf5ced2835a9e2378ff5cc3340862a6784d1126 Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Thu, 30 Oct 2025 12:34:21 -0400 Subject: [PATCH 09/12] Apply suggestion from @askpt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: André Silva <2493377+askpt@users.noreply.github.com> Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index e259bc3f..ffe44314 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -141,4 +141,4 @@ The following table describes the history of changes to the OpenTelemetry featur [otel-ff-events]: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/ [otel-span-event-deprecation-plan]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/4430-span-event-api-deprecation-plan.md -[otle-record-error]: https://opentelemetry.io/docs/specs/semconv/general/recording-errors/ +[otel-record-error]: https://opentelemetry.io/docs/specs/semconv/general/recording-errors/ From 1fff0115d099bac438b0a12b370acee6696106cd Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Thu, 30 Oct 2025 12:55:13 -0400 Subject: [PATCH 10/12] apply pr feedback Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index ffe44314..b1fba82c 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -80,7 +80,7 @@ The `error` hook stage records exception information unless explicitly configure #### Finally Stage -The `finally` hook stage is where telemetry signals are emitted with complete evaluation details. This stage should include all required and conditionally required attributes as defined in the attribute mapping tables above. It's also responsible for proper resource cleanup (like ending spans or closing connections) while ensuring it doesn't throw exceptions that could affect flag evaluation. +The `finally` hook stage is where telemetry signals are emitted with complete evaluation details. This stage should include all required and conditionally required attributes as defined in the attribute mapping tables above. It's also responsible for proper resource cleanup (like ending spans or closing connections). ### Attribute Transformations @@ -96,15 +96,14 @@ Consider providing mechanisms to redact or obfuscate sensitive flag values, alon For consistency across implementations, consider supporting a common set of configuration options: -- `excludeExceptions` (boolean): Whether to exclude exception recording in telemetry -- `includeValue` (boolean): Whether to include flag values in telemetry signals -- `maxValueLength` (integer): Maximum size for flag values before redaction -- `shouldRedact` (function): Custom function to determine value redaction - `attributeMapper` (function): Custom function to add additional attributes to the signal +- `excludeAttributes` (list): List of attribute keys to exclude from the signal +- `excludeExceptions` (boolean): Whether to omit exception details from error signals +- `eventMutator` (function): Custom function to modify event attributes before sending ### Error Handling -Hooks should be designed to never throw exceptions that interrupt flag evaluation. Any internal errors can be logged at appropriate levels (debug/trace) without affecting application execution. While the OpenFeature SDK has error handling to capture hook exceptions, it's best practice to handle errors gracefully within the hook itself. +Hooks should be designed to never throw exceptions that interrupt flag evaluation. Any internal errors can be logged at appropriate levels (debug/trace) without affecting application execution. ### Implementation Patterns From c2b8dafde4041579fe377e5b4275ced63ef708a4 Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Mon, 3 Nov 2025 12:56:25 -0500 Subject: [PATCH 11/12] add link to otel exception semcon Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index b1fba82c..1e2c63da 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -98,7 +98,7 @@ For consistency across implementations, consider supporting a common set of conf - `attributeMapper` (function): Custom function to add additional attributes to the signal - `excludeAttributes` (list): List of attribute keys to exclude from the signal -- `excludeExceptions` (boolean): Whether to omit exception details from error signals +- `excludeExceptions` (boolean): Whether to omit [exception details][otel-exception-details] from error signals using - `eventMutator` (function): Custom function to modify event attributes before sending ### Error Handling @@ -141,3 +141,4 @@ The following table describes the history of changes to the OpenTelemetry featur [otel-ff-events]: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/ [otel-span-event-deprecation-plan]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/4430-span-event-api-deprecation-plan.md [otel-record-error]: https://opentelemetry.io/docs/specs/semconv/general/recording-errors/ +[otel-exception-details]: https://opentelemetry.io/docs/specs/semconv/exceptions/ From d3769a6523d4f5014d4497f728bd35fd7ed0f9a0 Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Tue, 4 Nov 2025 08:11:29 -0500 Subject: [PATCH 12/12] typed typo in config options Signed-off-by: Michael Beemer --- specification/appendix-d-observability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index 1e2c63da..0a35385d 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -98,7 +98,7 @@ For consistency across implementations, consider supporting a common set of conf - `attributeMapper` (function): Custom function to add additional attributes to the signal - `excludeAttributes` (list): List of attribute keys to exclude from the signal -- `excludeExceptions` (boolean): Whether to omit [exception details][otel-exception-details] from error signals using +- `excludeExceptions` (boolean): Whether to omit [exception details][otel-exception-details] from error signals - `eventMutator` (function): Custom function to modify event attributes before sending ### Error Handling