feat!: implement SemConv compatible OTEL hooks (#1372)

Release-As: 1.0.0

Signed-off-by: Lukas Reining <[email protected]>

Author: lukas-reining

libs/hooks/open-telemetry/README.md

@@ -1,6 +1,6 @@
 # OpenTelemetry Hooks
 
-The OpenTelemetry hooks for OpenFeature provide a [spec compliant][otel-spec] way to automatically add feature flag evaluation information to traces and metrics.
+The OpenTelemetry hooks for OpenFeature provide a [spec compliant][otel-semconv] way to automatically add feature flag evaluation information to traces, logs, and metrics.
 Since feature flags are dynamic and affect runtime behavior, it’s important to collect relevant feature flag telemetry signals.
 These can be used to determine the impact a feature has on application behavior, enabling enhanced observability use cases, such as A/B testing or progressive feature releases.
 
@@ -13,16 +13,43 @@ $ npm install @openfeature/open-telemetry-hooks
 ### Peer dependencies
 
 Confirm that the following peer dependencies are installed.
+If you use the `MetricsHook`, `SpanEventHook` or `SpanHook`, you need to install:
 
 ```
-$ npm install @openfeature/server-sdk @opentelemetry/api
+$ npm install @openfeature/core @opentelemetry/api
 ```
 
+For the `EventHook`, you also need to install the OpenTelemetry logs SDK:
+
+```
+$ npm install @opentelemetry/sdk-logs
+```
+
+> [!NOTE]
+> For the hooks to work, you must have the OpenTelemetry SDK configured in your application.
+> Please refer to the [OpenTelemetry documentation](https://opentelemetry.io/docs/instrumentation/js/) for more information on setting up OpenTelemetry in your application.
+> You need to set up the [tracing SDK][otel-tracing-js] for `SpanHook` and `SpanEventHook`, the [metrics SDK][[otel-metrics-js]] for `MetricsHook`, and the [logs SDK][[otel-logs-js]] for `EventHook`.
+
 ## Hooks
 
-### TracingHook
+### EventHook
+
+This hook logs evaluation events to OpenTelemetry using an [EventLogger][otel-logs].
+These are logged even if there is no active span.
+This is useful for exporting evaluation events to a backend that supports [OpenTelemetry log events][otel-logs].
+**Note:** Log Events are the recommended approach for capturing feature flag evaluation data.
 
-This hook adds a [span event](https://opentelemetry.io/docs/concepts/signals/traces/#span-events) for each feature flag evaluation.
+### SpanEventHook
+
+This hook adds evaluation [span events][otel-span-events] to the current active span.
+This is useful for associating evaluation events with a trace.
+If there is no active span, the event is not logged.
+**Note:** [Span events are being deprecated in OTEL][span-event-deprecation-otep] in favor of [using log events via `EventHook`](#eventhook).
+
+### SpanHook
+
+This hook creates a new [span][otel-span] for each flag evaluation and sets the evaluation details as [span attributes][otel-span-attributes].
+This is useful for tracing flag evaluations as part of a larger trace.
 
 ### MetricsHook
 
@@ -36,52 +63,105 @@ This hook performs metric collection by tapping into various hook stages. Below
 ## Usage
 
 OpenFeature provides various ways to register hooks. The location that a hook is registered affects when the hook is run.
-It's recommended to register both the `TracingHook` and `MetricsHook` globally in most situations, but it's possible to only enable the hook on specific clients.
-You should **never** register these hooks both globally and on a client.
+It's recommended to register the desired hooks globally in most situations, but it's possible to only enable specific hooks on individual clients.
+You should **never** register the same hook type both globally and on a client.
 
 More information on hooks can be found in the [OpenFeature documentation][hook-concept].
 
 ### Register Globally
 
-The `TracingHook` and `MetricsHook` can both be set on the OpenFeature singleton.
+The hooks can be set on the OpenFeature singleton.
 This will ensure that every flag evaluation will always generate the applicable telemetry signals.
 
 ```typescript
-import { OpenFeature } from '@openfeature/server-sdk';
-import { TracingHook } from '@openfeature/open-telemetry-hooks';
+import { OpenFeature } from '@openfeature/core';
+import { EventHook, MetricsHook } from '@openfeature/open-telemetry-hooks';
 
-OpenFeature.addHooks(new TracingHook());
+OpenFeature.addHooks(new EventHook(), new MetricsHook());
 ```
 
 ### Register Per Client
 
- The `TracingHook` and `MetricsHook` can both be set on an individual client. This should only be done if it wasn't set globally and other clients shouldn't use this hook.
- Setting the hook on the client will ensure that every flag evaluation performed by this client will always generate the applicable telemetry signals.
+The hooks can be set on an individual client. This should only be done if they weren't set globally and other clients shouldn't use these hooks.
+Setting the hooks on the client will ensure that every flag evaluation performed by this client will always generate the applicable telemetry signals.
 
 ```typescript
-import { OpenFeature } from '@openfeature/server-sdk';
-import { MetricsHook } from '@openfeature/open-telemetry-hooks';
+import { OpenFeature } from '@openfeature/core';
+import { SpanHook, MetricsHook } from '@openfeature/open-telemetry-hooks';
+import { SpanEventHook } from './tracing-hooks';
 
 const client = OpenFeature.getClient('my-app');
-client.addHooks(new MetricsHook());
+client.addHooks(new SpanEventHook(), new MetricsHook());
 ```
 
-### Custom Attributes
+### Hook Selection Guide
+
+Choose the appropriate hook(s) based on your observability needs:
+
+- **EventHook**: Recommended for future use cases. Logs evaluation events that can be backends supporting [OTEL Logs][otel-logs].
+- **SpanEventHook**: Span events are being deprecated. Use only if your backend supports span events and you cannot use `EventHook`.
+- **SpanHook**: Use when you want dedicated spans for each evaluation in your traces.
+- **MetricsHook**: Use alongside any of the above when you need metrics about evaluation performance.
 
-Custom attributes can be extracted from [flag metadata](https://openfeature.dev/specification/types#flag-metadata) by supplying a `attributeMapper` in the `MetricsHookOptions` or `TracingHookOptions`.
+### Hook Options
 
-In the case of the `MetricsHook`, these will be added to the `feature_flag.evaluation_success_total` metric.
-The `TracingHook` adds them as [span event attributes](https://opentelemetry.io/docs/instrumentation/js/manual/#span-events).
+All hooks support the following options via `OpenTelemetryHookOptions`:
+
+#### Custom Attributes
+
+Custom attributes can be extracted from hook metadata or evaluation details by supplying an `attributeMapper`:
 
 ```typescript
-// configure an attributeMapper function for a custom property
-const attributeMapper: AttributeMapper = (flagMetadata) => { 
-    return {
-        myCustomAttribute: flagMetadata.someFlagMetadataField,
-    };
-};
-const metricsHook = new MetricsHook({ attributeMapper });
-const tracingHook = new TracingHook({ attributeMapper });
+import { HookContext, EvaluationDetails, FlagValue } from '@openfeature/core';
+import { EventHook } from '@openfeature/open-telemetry-hooks';
+
+const attributeMapper = (hookContext: HookContext, evaluationDetails: EvaluationDetails<FlagValue>) => ({
+  myCustomAttributeFromContext: hookContext.context.targetingKey,
+  myCustomAttributeFromMetadata: evaluationDetails.flagMetadata.someFlagMetadataField,
+});
+
+const eventHook = new EventHook({ attributeMapper });
+```
+
+#### Exclude Attributes
+
+Exclude specific attributes from being added to telemetry events:
+
+```typescript
+import { EventHook } from '@openfeature/open-telemetry-hooks';
+import { TelemetryAttribute } from '@openfeature/core';
+
+const eventHook = new EventHook({
+  excludeAttributes: [TelemetryAttribute.VALUE, 'sensitive_value']
+});
+```
+
+#### Exclude Exceptions
+
+Prevent exceptions from being recorded:
+
+```typescript
+import { SpanHook } from '@openfeature/open-telemetry-hooks';
+
+const spanHook = new SpanHook({ excludeExceptions: true });
+```
+
+#### Event Mutation
+
+Transform events before they are emitted:
+
+```typescript
+import { EventHook } from '@openfeature/open-telemetry-hooks';
+
+const eventMutator = (event) => ({
+  ...event,
+  attributes: {
+    ...event.attributes,
+    environment: 'production'
+  }
+});
+
+const eventHook = new EventHook({ eventMutator });
 ```
 
 ## Development
@@ -94,5 +174,22 @@ Run `nx package hooks-open-telemetry` to build the library.
 
 Run `nx test hooks-open-telemetry` to execute the unit tests via [Jest](https://jestjs.io).
 
-[otel-spec]: https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/feature-flags/
+[otel-span]: https://opentelemetry.io/docs/concepts/signals/traces/#spans
+
+[otel-span-attributes]: https://opentelemetry.io/docs/concepts/signals/traces/#attributes
+
+[otel-span-events]: https://opentelemetry.io/docs/concepts/signals/traces/#span-events
+
+[otel-logs]: https://opentelemetry.io/docs/concepts/signals/logs
+
+[otel-semconv]: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/
+
 [hook-concept]: https://openfeature.dev/docs/reference/concepts/hooks
+
+[span-event-deprecation-otep]: https://github.com/open-telemetry/opentelemetry-specification/blob/fbcd7a3126a545debd9e6e5c69b7b67d4ef1c156/oteps/4430-span-event-api-deprecation-plan.md
+
+[otel-tracing-js]: https://opentelemetry.io/docs/languages/js/instrumentation/#initialize-tracing
+
+[otel-metrics-js]: https://opentelemetry.io/docs/languages/js/instrumentation/#initialize-metrics
+
+[otel-logs-js]: https://opentelemetry.io/docs/languages/js/instrumentation/#logsl