refactor(telemetry): update telemetry attributes and remove unused evaluation data (#1189)

## This PR

- update the evaluation event to match the latest OTel semcon

### Related Issues

Fixes #1188

### Notes

Update the createEvaluationEvent to match the latest OpenTelemetry spec.
Unforutnately, this is a breaking change. I'll denote this in the
release notes but not in the library version. That's because we're
following the experimental OTel spec and the method itself is currently
undocumented except from the generated JS Doc.

It's also worth noting that OTel JS SDK event API doesn't currently
support object as attribute values. @dyladan will update the OTel SDK.

### Follow-up Tasks

Update the ToggleShop.

### How to test

`npm run test`

Signed-off-by: Michael Beemer <[email protected]>
Signed-off-by: Weyert de Boer <[email protected]>

Author: beeme1mr

packages/shared/src/evaluation/evaluation.ts

@@ -3,7 +3,7 @@ import type { JsonValue } from '../types/structure';
 export type FlagValueType = 'boolean' | 'string' | 'number' | 'object';
 
 /**
- * Represents a JSON node value, or Date.
+ * Represents a JSON node value.
  */
 export type FlagValue = boolean | string | number | JsonValue;
 

packages/shared/src/telemetry/attributes.ts

@@ -20,6 +20,14 @@ export const TelemetryAttribute = {
    * - example: `flag_not_found`
    */
   ERROR_CODE: 'error.type',
+  /**
+   * A message explaining the nature of an error occurring during flag evaluation.
+   *
+   * - type: `string`
+   * - requirement level: `recommended`
+   * - example: `Flag not found`
+   */
+  ERROR_MESSAGE: 'error.message',
   /**
    * A semantic identifier for an evaluated flag value.
    *
@@ -28,39 +36,40 @@ export const TelemetryAttribute = {
    * - condition: variant is defined on the evaluation details
    * - example: `blue`; `on`; `true`
    */
-  VARIANT: 'feature_flag.variant',
+  VARIANT: 'feature_flag.result.variant',
   /**
-   * The unique identifier for the flag evaluation context. For example, the targeting key.
+   * The evaluated value of the feature flag.
    *
-   * - type: `string`
-   * - requirement level: `recommended`
-   * - example: `5157782b-2203-4c80-a857-dbbd5e7761db`
+   * - type: `undefined`
+   * - requirement level: `conditionally required`
+   * - condition: variant is not defined on the evaluation details
+   * - example: `#ff0000`; `1`; `true`
    */
-  CONTEXT_ID: 'feature_flag.context.id',
+  VALUE: 'feature_flag.result.value',
   /**
-   * A message explaining the nature of an error occurring during flag evaluation.
+   * The unique identifier for the flag evaluation context. For example, the targeting key.
    *
    * - type: `string`
    * - requirement level: `recommended`
-   * - example: `Flag not found`
+   * - example: `5157782b-2203-4c80-a857-dbbd5e7761db`
    */
-  ERROR_MESSAGE: 'feature_flag.evaluation.error.message',
+  CONTEXT_ID: 'feature_flag.context.id',
   /**
    * 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',
+  REASON: 'feature_flag.result.reason',
   /**
    * Describes a class of error the operation ended with.
    *
    * - type: `string`
    * - requirement level: `recommended`
    * - example: `flag_not_found`
    */
-  PROVIDER: 'feature_flag.provider_name',
+  PROVIDER: 'feature_flag.provider.name',
   /**
    * The identifier of the flag set to which the feature flag belongs.
    *

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

@@ -1,14 +1,19 @@
 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 = {
+  /**
+   * The name of the feature flag evaluation event.
+   */
   name: string;
-  attributes: Record<string, string | number | boolean>;
-  body: Record<string, JsonValue>;
+  /**
+   * The attributes of an OpenTelemetry compliant event for flag evaluation.
+   * @experimental The attributes are subject to change.
+   * @see https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/
+   */
+  attributes: Record<string, string | number | boolean | FlagValue>;
 };
 
 const FLAG_EVALUATION_EVENT_NAME = 'feature_flag.evaluation';
@@ -28,12 +33,11 @@ export function createEvaluationEvent(
     [TelemetryAttribute.PROVIDER]: hookContext.providerMetadata.name,
     [TelemetryAttribute.REASON]: (evaluationDetails.reason ?? StandardResolutionReasons.UNKNOWN).toLowerCase(),
   };
-  const body: EvaluationEvent['body'] = {};
 
   if (evaluationDetails.variant) {
     attributes[TelemetryAttribute.VARIANT] = evaluationDetails.variant;
   } else {
-    body[TelemetryEvaluationData.VALUE] = evaluationDetails.value;
+    attributes[TelemetryAttribute.VALUE] = evaluationDetails.value;
   }
 
   const contextId =
@@ -62,6 +66,5 @@ export function createEvaluationEvent(
   return {
     name: FLAG_EVALUATION_EVENT_NAME,
     attributes,
-    body,
   };
 }

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

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

packages/shared/src/telemetry/index.ts

@@ -1,7 +1,7 @@
 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';
+import { TelemetryAttribute, TelemetryFlagMetadata } from '../src/telemetry';
 
 describe('evaluationEvent', () => {
   const flagKey = 'test-flag';
@@ -43,9 +43,7 @@ describe('evaluationEvent', () => {
       [TelemetryAttribute.PROVIDER]: 'test-provider',
       [TelemetryAttribute.REASON]: StandardResolutionReasons.STATIC.toLowerCase(),
       [TelemetryAttribute.CONTEXT_ID]: 'test-target',
-    });
-    expect(result.body).toEqual({
-      [TelemetryEvaluationData.VALUE]: true,
+      [TelemetryAttribute.VALUE]: true,
     });
   });
 
@@ -61,7 +59,7 @@ describe('evaluationEvent', () => {
     const result = createEvaluationEvent(mockHookContext, details);
 
     expect(result.attributes[TelemetryAttribute.VARIANT]).toBe('test-variant');
-    expect(result.attributes[TelemetryEvaluationData.VALUE]).toBeUndefined();
+    expect(result.attributes[TelemetryAttribute.VALUE]).toBeUndefined();
   });
 
   it('should include flag metadata when provided', () => {