add telemetry hook implementation guidelines

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**      | ✓           | 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. |
+
+> [!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 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.
+
+### 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.