OpenTelemetry Hooks

The OpenTelemetry hooks for OpenFeature provide a spec compliant 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.

Installation

$ 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/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 for more information on setting up OpenTelemetry in your application. You need to set up the tracing SDK for SpanHook and SpanEventHook, the [metrics SDK][otel-metrics-js] for MetricsHook, and the [logs SDK][otel-logs-js] for EventHook.

Hooks

EventHook

This hook logs evaluation events to OpenTelemetry using an EventLogger. 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. Note: Log Events are the recommended approach for capturing feature flag evaluation data.

SpanEventHook

This hook adds evaluation 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 in favor of using log events via EventHook.

SpanHook

This hook creates a new span for each flag evaluation and sets the evaluation details as span attributes. This is useful for tracing flag evaluations as part of a larger trace.

MetricsHook

This hook performs metric collection by tapping into various hook stages. Below are the metrics are extracted by this hook:

• feature_flag.evaluation_requests_total
• feature_flag.evaluation_success_total
• feature_flag.evaluation_error_total
• feature_flag.evaluation_active_count

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

Register Globally

The hooks can be set on the OpenFeature singleton. This will ensure that every flag evaluation will always generate the applicable telemetry signals.

import { OpenFeature } from '@openfeature/core';
import { EventHook, MetricsHook } from '@openfeature/open-telemetry-hooks';

OpenFeature.addHooks(new EventHook(), new MetricsHook());

Register Per Client

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.

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 SpanEventHook(), new MetricsHook());

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

Hook Options

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:

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:

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:

import { SpanHook } from '@openfeature/open-telemetry-hooks';

const spanHook = new SpanHook({ excludeExceptions: true });

Event Mutation

Transform events before they are emitted:

import { EventHook } from '@openfeature/open-telemetry-hooks';

const eventMutator = (event) => ({
  ...event,
  attributes: {
    ...event.attributes,
    environment: 'production'
  }
});

const eventHook = new EventHook({ eventMutator });

Development

Building

Run nx package hooks-open-telemetry to build the library.

Running unit tests

Run nx test hooks-open-telemetry to execute the unit tests via Jest.