-
Notifications
You must be signed in to change notification settings - Fork 39
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat!: update the otel hook to be spec compliant (#179)
- Loading branch information
Showing
6 changed files
with
127 additions
and
158 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,21 +1,59 @@ | ||
| # OpenTelemetry Hook | ||
|
|
||
| The OpenTelemetry hook for OpenFeature provides a [spec compliant][otel-spec] way to automatically add a feature flag evaluation to a span as a span event. Since feature flags are dynamic and affect runtime behavior, it’s important to collect relevant feature flag telemetry signals. This can be used to determine the impact a feature has on a request, enabling enhanced observability use cases, such as A/B testing or progressive feature releases. | ||
|
|
||
| ## Installation | ||
|
|
||
| ``` | ||
| $ npm install @openfeature/open-telemetry-hook | ||
| ``` | ||
|
|
||
| Required peer dependencies | ||
| ### Peer dependencies | ||
|
|
||
| Confirm that the following peer dependencies are installed. | ||
|
|
||
| ``` | ||
| $ npm install @openfeature/js-sdk @opentelemetry/api | ||
| ``` | ||
|
|
||
| ## Building | ||
| ## 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 `OpenTelemetryHook` globally in most situations but it's possible to only enable the hook on specific clients. You should **never** register the `OpenTelemetryHook` globally and on a client. | ||
|
|
||
| More information on hooks can be found in the [OpenFeature documentation][hook-concept]. | ||
|
|
||
| ### Register Globally | ||
|
|
||
| The `OpenTelemetryHook` can be set on the OpenFeature singleton. This will ensure that every flag evaluation will always create a span event, if am active span is available. | ||
|
|
||
| ```typescript | ||
| import { OpenFeature } from '@openfeature/js-sdk'; | ||
| import { OpenTelemetryHook } from '@openfeature/open-telemetry-hook'; | ||
|
|
||
| OpenFeature.addHooks(new OpenTelemetryHook()); | ||
| ``` | ||
|
|
||
| ### Register Per Client | ||
|
|
||
| The `OpenTelemetryHook` can 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 create a span event, if am active span is available. | ||
|
|
||
| ```typescript | ||
| import { OpenFeature } from '@openfeature/js-sdk'; | ||
| import { OpenTelemetryHook } from '@openfeature/open-telemetry-hook'; | ||
|
|
||
| const client = OpenFeature.getClient('my-app'); | ||
| client.addHooks(new OpenTelemetryHook()); | ||
| ``` | ||
|
|
||
| ## Development | ||
|
|
||
| ### Building | ||
|
|
||
| Run `nx package hooks-open-telemetry` to build the library. | ||
|
|
||
| ## Running unit tests | ||
| ### Running unit tests | ||
|
|
||
| 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/ | ||
| [hook-concept]: https://docs.openfeature.dev/docs/reference/concepts/hooks |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,65 +1,36 @@ | ||
| import { | ||
| Hook, | ||
| HookContext, | ||
| EvaluationDetails, | ||
| FlagValue, | ||
| } from '@openfeature/js-sdk'; | ||
| import { Span, Tracer, trace } from '@opentelemetry/api'; | ||
| import { Hook, HookContext, EvaluationDetails, FlagValue } from '@openfeature/js-sdk'; | ||
| import { trace } from '@opentelemetry/api'; | ||
|
|
||
| const SpanProperties = Object.freeze({ | ||
| FLAG_KEY: 'feature_flag.flag_key', | ||
| const eventName = 'feature_flag'; | ||
| const spanEventProperties = Object.freeze({ | ||
| FLAG_KEY: 'feature_flag.key', | ||
| PROVIDER_NAME: 'feature_flag.provider_name', | ||
| VARIANT: 'feature_flag.evaluated_variant', | ||
| VALUE: 'feature_flag.evaluated_value', | ||
| VARIANT: 'feature_flag.variant', | ||
| }); | ||
|
|
||
| export class OpenTelemetryHook implements Hook { | ||
| private spanMap = new WeakMap<HookContext, Span>(); | ||
| private tracer: Tracer; | ||
|
|
||
| constructor() { | ||
| this.tracer = trace.getTracer( | ||
| '@openfeature/open-telemetry-hook', | ||
| '5.1.1' // x-release-please-version | ||
| ); | ||
| } | ||
|
|
||
| before(hookContext: HookContext) { | ||
| const span = this.tracer.startSpan( | ||
| `${hookContext.providerMetadata.name} ${hookContext.flagKey}`, | ||
| { | ||
| attributes: { | ||
| [SpanProperties.FLAG_KEY]: hookContext.flagKey, | ||
| [SpanProperties.PROVIDER_NAME]: hookContext.providerMetadata.name, | ||
| }, | ||
| after(hookContext: HookContext, evaluationDetails: EvaluationDetails<FlagValue>) { | ||
| const currentTrace = trace.getActiveSpan(); | ||
| if (currentTrace) { | ||
| let variant = evaluationDetails.variant; | ||
|
|
||
| if (!variant) { | ||
| if (typeof evaluationDetails.value === 'string') { | ||
| variant = evaluationDetails.value; | ||
| } else { | ||
| variant = JSON.stringify(evaluationDetails.value); | ||
| } | ||
| } | ||
| ); | ||
|
|
||
| this.spanMap.set(hookContext, span); | ||
| } | ||
|
|
||
| after( | ||
| hookContext: HookContext, | ||
| evaluationDetails: EvaluationDetails<FlagValue> | ||
| ) { | ||
| if (evaluationDetails.variant) { | ||
| this.spanMap | ||
| .get(hookContext) | ||
| ?.setAttribute(SpanProperties.VARIANT, evaluationDetails.variant); | ||
| } else { | ||
| const value = | ||
| typeof evaluationDetails.value === 'string' | ||
| ? evaluationDetails.value | ||
| : JSON.stringify(evaluationDetails.value); | ||
| this.spanMap.get(hookContext)?.setAttribute(SpanProperties.VALUE, value); | ||
| currentTrace.addEvent(eventName, { | ||
| [spanEventProperties.FLAG_KEY]: hookContext.flagKey, | ||
| [spanEventProperties.PROVIDER_NAME]: hookContext.providerMetadata.name, | ||
| [spanEventProperties.VARIANT]: variant, | ||
| }); | ||
| } | ||
| } | ||
|
|
||
| error(hookContext: HookContext, err: Error) { | ||
| this.spanMap.get(hookContext)?.recordException(err); | ||
| } | ||
|
|
||
| finally(hookContext: HookContext) { | ||
| this.spanMap.get(hookContext)?.end(); | ||
| error(_: HookContext, err: Error) { | ||
| trace.getActiveSpan()?.recordException(err); | ||
| } | ||
| } |
Oops, something went wrong.