feat: add telemetry helper utils (#1120)

## This PR

- adds a method to core that returns a semantically valid flag
evaluation event

### Related Issues

Fixes #1118

## Notes

I've omitted value type because it is likely to be declined in the OTel
spec and adds complexity. We should consider removing that section from
[appendix
d](https://openfeature.dev/specification/appendix-d#evaluation-details).

---------

Signed-off-by: Michael Beemer <[email protected]>
Signed-off-by: Todd Baert <[email protected]>
Co-authored-by: Todd Baert <[email protected]>

Author: beeme1mr

packages/shared/src/telemetry/attributes.ts

@@ -0,0 +1,80 @@
+/**
+ * The attributes of an OpenTelemetry compliant event for flag evaluation.
+ * @see https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/
+ */
+export const TelemetryAttribute = {
+  /**
+   * The lookup key of the feature flag.
+   *
+   * - type: `string`
+   * - requirement level: `required`
+   * - example: `logo-color`
+   */
+  KEY: 'feature_flag.key',
+  /**
+   * Describes a class of error the operation ended with.
+   *
+   * - type: `string`
+   * - requirement level: `conditionally required`
+   * - condition: `reason` is `error`
+   * - example: `flag_not_found`
+   */
+  ERROR_CODE: 'error.type',
+  /**
+   * A semantic identifier for an evaluated flag value.
+   *
+   * - type: `string`
+   * - requirement level: `conditionally required`
+   * - condition: variant is defined on the evaluation details
+   * - example: `blue`; `on`; `true`
+   */
+  VARIANT: 'feature_flag.variant',
+  /**
+   * The unique identifier for the flag evaluation context. For example, the targeting key.
+   *
+   * - type: `string`
+   * - requirement level: `recommended`
+   * - example: `5157782b-2203-4c80-a857-dbbd5e7761db`
+   */
+  CONTEXT_ID: 'feature_flag.context.id',
+  /**
+   * A message explaining the nature of an error occurring during flag evaluation.
+   *
+   * - type: `string`
+   * - requirement level: `recommended`
+   * - example: `Flag not found`
+   */
+  ERROR_MESSAGE: 'feature_flag.evaluation.error.message',
+  /**
+   * The reason code which shows how a feature flag value was determined.
+   *
+   * - type: `string`
+   * - requirement level: `recommended`
+   * - example: `targeting_match`
+   */
+  REASON: 'feature_flag.evaluation.reason',
+  /**
+   * Describes a class of error the operation ended with.
+   *
+   * - type: `string`
+   * - requirement level: `recommended`
+   * - example: `flag_not_found`
+   */
+  PROVIDER: 'feature_flag.provider_name',
+  /**
+   * The identifier of the flag set to which the feature flag belongs.
+   *
+   * - type: `string`
+   * - requirement level: `recommended`
+   * - example: `proj-1`; `ab98sgs`; `service1/dev`
+   */
+  FLAG_SET_ID: 'feature_flag.set.id',
+  /**
+   * The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset.
+   *
+   * - type: `string`
+   * - requirement level: `recommended`
+   * - example: `1.0.0`; `2021-01-01`
+   */
+  VERSION: 'feature_flag.version',
+} as const;

packages/shared/src/telemetry/evaluation-data.ts

@@ -0,0 +1,17 @@
+/**
+ * Event data, sometimes referred as "body", is specific to a specific event.
+ * In this case, the event is `feature_flag.evaluation`. That's why the prefix
+ * is omitted from the values.
+ * @see https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/
+ */
+export const TelemetryEvaluationData = {
+  /**
+   * The evaluated value of the feature flag.
+   *
+   * - type: `undefined`
+   * - requirement level: `conditionally required`
+   * - condition: variant is not defined on the evaluation details
+   * - example: `#ff0000`; `1`; `true`
+   */
+  VALUE: 'value',
+} as const;

packages/shared/src/telemetry/evaluation-event.ts

@@ -0,0 +1,67 @@
+import { ErrorCode, StandardResolutionReasons, type EvaluationDetails, type FlagValue } from '../evaluation/evaluation';
+import type { HookContext } from '../hooks/hooks';
+import type { JsonValue } from '../types';
+import { TelemetryAttribute } from './attributes';
+import { TelemetryEvaluationData } from './evaluation-data';
+import { TelemetryFlagMetadata } from './flag-metadata';
+
+type EvaluationEvent = {
+  name: string;
+  attributes: Record<string, string | number | boolean>;
+  data: Record<string, JsonValue>;
+};
+
+const FLAG_EVALUATION_EVENT_NAME = 'feature_flag.evaluation';
+
+/**
+ * Returns an OpenTelemetry compliant event for flag evaluation.
+ * @param {HookContext} hookContext Contextual information about the flag evaluation
+ * @param {EvaluationDetails} evaluationDetails The details of the flag evaluation
+ * @returns {EvaluationEvent} An evaluation event object containing the event name and attributes
+ */
+export function createEvaluationEvent(
+  hookContext: Readonly<HookContext<FlagValue>>,
+  evaluationDetails: EvaluationDetails<FlagValue>,
+): EvaluationEvent {
+  const attributes: EvaluationEvent['attributes'] = {
+    [TelemetryAttribute.KEY]: hookContext.flagKey,
+    [TelemetryAttribute.PROVIDER]: hookContext.providerMetadata.name,
+    [TelemetryAttribute.REASON]: (evaluationDetails.reason ?? StandardResolutionReasons.UNKNOWN).toLowerCase(),
+  };
+  const data: EvaluationEvent['data'] = {};
+
+  if (evaluationDetails.variant) {
+    attributes[TelemetryAttribute.VARIANT] = evaluationDetails.variant;
+  } else {
+    data[TelemetryEvaluationData.VALUE] = evaluationDetails.value;
+  }
+
+  const contextId =
+    evaluationDetails.flagMetadata[TelemetryFlagMetadata.CONTEXT_ID] || hookContext.context.targetingKey;
+  if (contextId) {
+    attributes[TelemetryAttribute.CONTEXT_ID] = contextId;
+  }
+
+  const setId = evaluationDetails.flagMetadata[TelemetryFlagMetadata.FLAG_SET_ID];
+  if (setId) {
+    attributes[TelemetryAttribute.FLAG_SET_ID] = setId;
+  }
+
+  const version = evaluationDetails.flagMetadata[TelemetryFlagMetadata.VERSION];
+  if (version) {
+    attributes[TelemetryAttribute.VERSION] = version;
+  }
+
+  if (evaluationDetails.reason === StandardResolutionReasons.ERROR) {
+    attributes[TelemetryAttribute.ERROR_CODE] = (evaluationDetails.errorCode ?? ErrorCode.GENERAL).toLowerCase();
+    if (evaluationDetails.errorMessage) {
+      attributes[TelemetryAttribute.ERROR_MESSAGE] = evaluationDetails.errorMessage;
+    }
+  }
+
+  return {
+    name: FLAG_EVALUATION_EVENT_NAME,
+    attributes,
+    data,
+  };
+}

packages/shared/src/telemetry/flag-metadata.ts

@@ -0,0 +1,20 @@
+/**
+ * Well-known flag metadata attributes for telemetry events.
+ * @see https://openfeature.dev/specification/appendix-d#flag-metadata
+ */
+export const TelemetryFlagMetadata = {
+  /**
+   * The context identifier returned in the flag metadata uniquely identifies
+   * the subject of the flag evaluation. If not available, the targeting key
+   * should be used.
+   */
+  CONTEXT_ID: 'contextId',
+  /**
+   * 	A logical identifier for the flag set.
+   */
+  FLAG_SET_ID: 'flagSetId',
+  /**
+   * 	A version string (format unspecified) for the flag or flag set.
+   */
+  VERSION: 'version',
+} as const;

packages/shared/src/telemetry/index.ts

@@ -0,0 +1,4 @@
+export * from './attributes';
+export * from './evaluation-data';
+export * from './flag-metadata';
+export * from './evaluation-event';

packages/shared/test/telemetry.spec.ts

@@ -0,0 +1,113 @@
+import { createEvaluationEvent } from '../src/telemetry/evaluation-event';
+import { ErrorCode, StandardResolutionReasons, type EvaluationDetails } from '../src/evaluation/evaluation';
+import type { HookContext } from '../src/hooks/hooks';
+import { TelemetryAttribute, TelemetryFlagMetadata, TelemetryEvaluationData } from '../src/telemetry';
+
+describe('evaluationEvent', () => {
+  const flagKey = 'test-flag';
+  const providerMetadata = {
+    name: 'test-provider',
+  };
+  const mockHookContext: HookContext<boolean> = {
+    flagKey,
+    providerMetadata: providerMetadata,
+    context: {
+      targetingKey: 'test-target',
+    },
+    clientMetadata: {
+      providerMetadata,
+    },
+    defaultValue: false,
+    flagValueType: 'boolean',
+    logger: {
+      debug: jest.fn(),
+      info: jest.fn(),
+      error: jest.fn(),
+      warn: jest.fn(),
+    },
+  };
+
+  it('should return basic event body with mandatory fields', () => {
+    const details: EvaluationDetails<boolean> = {
+      value: true,
+      reason: StandardResolutionReasons.STATIC,
+      flagMetadata: {},
+      flagKey,
+    };
+
+    const result = createEvaluationEvent(mockHookContext, details);
+
+    expect(result.name).toBe('feature_flag.evaluation');
+    expect(result.attributes).toEqual({
+      [TelemetryAttribute.KEY]: 'test-flag',
+      [TelemetryAttribute.PROVIDER]: 'test-provider',
+      [TelemetryAttribute.REASON]: StandardResolutionReasons.STATIC.toLowerCase(),
+      [TelemetryAttribute.CONTEXT_ID]: 'test-target',
+    });
+    expect(result.data).toEqual({
+      [TelemetryEvaluationData.VALUE]: true,
+    });
+  });
+
+  it('should include variant when provided', () => {
+    const details: EvaluationDetails<boolean> = {
+      flagKey,
+      value: true,
+      variant: 'test-variant',
+      reason: StandardResolutionReasons.STATIC,
+      flagMetadata: {},
+    };
+
+    const result = createEvaluationEvent(mockHookContext, details);
+
+    expect(result.attributes[TelemetryAttribute.VARIANT]).toBe('test-variant');
+    expect(result.attributes[TelemetryEvaluationData.VALUE]).toBeUndefined();
+  });
+
+  it('should include flag metadata when provided', () => {
+    const details: EvaluationDetails<boolean> = {
+      flagKey,
+      value: true,
+      reason: StandardResolutionReasons.STATIC,
+      flagMetadata: {
+        [TelemetryFlagMetadata.FLAG_SET_ID]: 'test-set',
+        [TelemetryFlagMetadata.VERSION]: 'v1.0',
+        [TelemetryFlagMetadata.CONTEXT_ID]: 'metadata-context',
+      },
+    };
+
+    const result = createEvaluationEvent(mockHookContext, details);
+
+    expect(result.attributes[TelemetryAttribute.FLAG_SET_ID]).toBe('test-set');
+    expect(result.attributes[TelemetryAttribute.VERSION]).toBe('v1.0');
+    expect(result.attributes[TelemetryAttribute.CONTEXT_ID]).toBe('metadata-context');
+  });
+
+  it('should handle error cases', () => {
+    const details: EvaluationDetails<boolean> = {
+      flagKey,
+      value: false,
+      reason: StandardResolutionReasons.ERROR,
+      errorCode: ErrorCode.GENERAL,
+      errorMessage: 'test error',
+      flagMetadata: {},
+    };
+
+    const result = createEvaluationEvent(mockHookContext, details);
+
+    expect(result.attributes[TelemetryAttribute.ERROR_CODE]).toBe(ErrorCode.GENERAL.toLowerCase());
+    expect(result.attributes[TelemetryAttribute.ERROR_MESSAGE]).toBe('test error');
+  });
+
+  it('should use unknown reason when reason is not provided', () => {
+    const details: EvaluationDetails<boolean> = {
+      flagKey,
+      value: true,
+      flagMetadata: {},
+    };
+
+    const result = createEvaluationEvent(mockHookContext, details);
+
+    expect(result.attributes[TelemetryAttribute.REASON]).toBe(StandardResolutionReasons.UNKNOWN.toLowerCase());
+  });
+});