[9.1] [Discover][APM] Create accessKnownApmEventFields for validating unified traces API (#241976) (#242448)

Bluefinger · kibanamachine · web-flow · commit 28e490e1b2eb · 2025-11-10T19:55:36.000+01:00
# Backport This will backport the following commits from `main` to `9.1`: - [[Discover][APM] Create `accessKnownApmEventFields` for validating unified traces API (#241976)](#241976)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport)  --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
diff --git a/x-pack/solutions/observability/plugins/apm/server/routes/services/get_service_instance_metadata_details.ts b/x-pack/solutions/observability/plugins/apm/server/routes/services/get_service_instance_metadata_details.ts
@@ -8,7 +8,7 @@ import { merge } from 'lodash';
 import { rangeQuery } from '@kbn/observability-plugin/server';
 import { ProcessorEvent } from '@kbn/observability-plugin/common';
 import { unflattenKnownApmEventFields } from '@kbn/apm-data-access-plugin/server/utils';
-import type { FlattenedApmEvent } from '@kbn/apm-data-access-plugin/server/utils/unflatten_known_fields';
+import type { FlattenedApmEvent } from '@kbn/apm-data-access-plugin/server/utils/utility_types';
 import {
   AGENT_NAME,
   AT_TIMESTAMP,
diff --git a/x-pack/solutions/observability/plugins/apm/server/routes/services/get_service_metadata_details.ts b/x-pack/solutions/observability/plugins/apm/server/routes/services/get_service_metadata_details.ts
@@ -8,7 +8,7 @@
 import { rangeQuery } from '@kbn/observability-plugin/server';
 import { ProcessorEvent } from '@kbn/observability-plugin/common';
 import { unflattenKnownApmEventFields } from '@kbn/apm-data-access-plugin/server/utils';
-import type { FlattenedApmEvent } from '@kbn/apm-data-access-plugin/server/utils/unflatten_known_fields';
+import type { FlattenedApmEvent } from '@kbn/apm-data-access-plugin/server/utils/utility_types';
 import { getAgentName } from '@kbn/elastic-agent-utils';
 import type { SortOptions } from '@elastic/elasticsearch/lib/api/types';
 import { environmentQuery } from '../../../common/utils/environment_query';
diff --git a/x-pack/solutions/observability/plugins/apm/server/routes/services/get_service_metadata_icons.ts b/x-pack/solutions/observability/plugins/apm/server/routes/services/get_service_metadata_icons.ts
@@ -8,7 +8,7 @@
 import { rangeQuery } from '@kbn/observability-plugin/server';
 import { ProcessorEvent } from '@kbn/observability-plugin/common';
 import { unflattenKnownApmEventFields } from '@kbn/apm-data-access-plugin/server/utils';
-import type { FlattenedApmEvent } from '@kbn/apm-data-access-plugin/server/utils/unflatten_known_fields';
+import type { FlattenedApmEvent } from '@kbn/apm-data-access-plugin/server/utils/utility_types';
 import { getAgentName } from '@kbn/elastic-agent-utils';
 import { maybe } from '../../../common/utils/maybe';
 import { asMutableArray } from '../../../common/utils/as_mutable_array';
diff --git a/x-pack/solutions/observability/plugins/apm/server/routes/traces/get_unified_trace_items.ts b/x-pack/solutions/observability/plugins/apm/server/routes/traces/get_unified_trace_items.ts
@@ -7,7 +7,7 @@
 
 import type { Sort } from '@elastic/elasticsearch/lib/api/types';
 import type { APMEventClient } from '@kbn/apm-data-access-plugin/server';
-import { unflattenKnownApmEventFields } from '@kbn/apm-data-access-plugin/server/utils';
+import { accessKnownApmEventFields } from '@kbn/apm-data-access-plugin/server/utils';
 import { ProcessorEvent } from '@kbn/observability-plugin/common';
 import { rangeQuery, termQuery } from '@kbn/observability-plugin/server';
 import type { APMConfig } from '../..';
@@ -154,28 +154,27 @@ export async function getUnifiedTraceItems({
   return {
     traceItems: unifiedTraceItems.hits.hits
       .map((hit) => {
-        const event = unflattenKnownApmEventFields(hit.fields, fields);
-        const apmDuration = event.span?.duration?.us || event.transaction?.duration?.us;
-        const id = event.span?.id || event.transaction?.id;
-        if (!id) {
+        const event = accessKnownApmEventFields(hit.fields, fields);
+        const apmDuration = event[SPAN_DURATION] ?? event[TRANSACTION_DURATION];
+        const id = event[SPAN_ID] ?? event[TRANSACTION_ID];
+        const name = event[SPAN_NAME] ?? event[TRANSACTION_NAME];
+
+        if (!id || !name) {
           return undefined;
         }
 
         const docErrorCount = errorCountByDocId[id] || 0;
+        const statusCode = event[STATUS_CODE];
         return {
-          id: event.span?.id ?? event.transaction?.id,
-          timestampUs: event.timestamp?.us ?? toMicroseconds(event[AT_TIMESTAMP]),
-          name: event.span?.name ?? event.transaction?.name,
-          traceId: event.trace.id,
-          duration: resolveDuration(apmDuration, event.duration),
-          hasError:
-            docErrorCount > 0 ||
-            (event.status?.code && Array.isArray(event.status.code)
-              ? event.status.code[0] === 'Error'
-              : false),
-          parentId: event.parent?.id,
-          serviceName: event.service.name,
-        } as TraceItem;
+          id,
+          name,
+          timestampUs: event[TIMESTAMP_US] ?? toMicroseconds(event[AT_TIMESTAMP]),
+          traceId: event[TRACE_ID],
+          duration: resolveDuration(apmDuration, event[DURATION]),
+          hasError: docErrorCount > 0 || statusCode === 'Error',
+          parentId: event[PARENT_ID],
+          serviceName: event['service.name'],
+        } satisfies TraceItem;
       })
       .filter((_) => _) as TraceItem[],
     unifiedTraceErrors,
diff --git a/x-pack/solutions/observability/plugins/apm/server/routes/transactions/get_span/index.ts b/x-pack/solutions/observability/plugins/apm/server/routes/transactions/get_span/index.ts
@@ -8,7 +8,7 @@
 import { rangeQuery, termQuery } from '@kbn/observability-plugin/server';
 import { ProcessorEvent } from '@kbn/observability-plugin/common';
 import { unflattenKnownApmEventFields } from '@kbn/apm-data-access-plugin/server/utils';
-import type { FlattenedApmEvent } from '@kbn/apm-data-access-plugin/server/utils/unflatten_known_fields';
+import type { FlattenedApmEvent } from '@kbn/apm-data-access-plugin/server/utils/utility_types';
 import { merge, omit } from 'lodash';
 import { maybe } from '../../../../common/utils/maybe';
 import { SPAN_ID, SPAN_STACKTRACE, TRACE_ID } from '../../../../common/es_fields/apm';
diff --git a/x-pack/solutions/observability/plugins/apm_data_access/server/utils.ts b/x-pack/solutions/observability/plugins/apm_data_access/server/utils.ts
@@ -16,3 +16,4 @@ export {
 
 export { withApmSpan } from './utils/with_apm_span';
 export { unflattenKnownApmEventFields } from './utils/unflatten_known_fields';
+export { accessKnownApmEventFields } from './utils/access_known_fields';
diff --git a/x-pack/solutions/observability/plugins/apm_data_access/server/utils/access_known_fields.test.ts b/x-pack/solutions/observability/plugins/apm_data_access/server/utils/access_known_fields.test.ts
@@ -0,0 +1,84 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { accessKnownApmEventFields } from './access_known_fields';
+import type { FlattenedApmEvent } from './utility_types';
+
+describe('accessKnownApmEventFields', () => {
+  const input = {
+    '@timestamp': ['2024-10-10T10:10:10.000Z'],
+    'service.name': ['node-svc'],
+    'service.version': ['1.0.0'],
+    'service.environment': ['production'],
+    'agent.name': ['nodejs'],
+    'links.span_id': ['link1', 'link2'],
+  };
+
+  it('should return either single or array values for the various known field types', () => {
+    const event = accessKnownApmEventFields(input as Partial<FlattenedApmEvent>, [
+      '@timestamp',
+      'service.name',
+    ]);
+
+    expect(event['service.name']).not.toBeUndefined();
+    expect(event['agent.name']).toBe('nodejs');
+    expect(event['agent.version']).toBeUndefined();
+    expect(event['links.span_id']).toEqual(['link1', 'link2']);
+    expect(event['links.trace_id']).toBeUndefined();
+  });
+
+  it('should validate all required fields are present in the input document', () => {
+    expect(() => accessKnownApmEventFields(input, ['@timestamp', 'service.name'])).not.toThrow();
+
+    expect(() => accessKnownApmEventFields({}, ['@timestamp', 'service.name'])).toThrowError(
+      'Missing required fields (@timestamp, service.name) in event'
+    );
+
+    expect(() =>
+      accessKnownApmEventFields({ ...input, 'service.name': [] }, ['@timestamp', 'service.name'])
+    ).toThrowError('Missing required fields (service.name) in event');
+  });
+
+  it('exposes an `unflatten` method', () => {
+    const smallInput = {
+      '@timestamp': ['2024-10-10T10:10:10.000Z'],
+      'service.name': ['node-svc'],
+      'links.span_id': ['link1', 'link2'],
+    };
+
+    const event = accessKnownApmEventFields(smallInput, ['@timestamp', 'service.name']);
+
+    expect(typeof event.unflatten).toBe('function');
+
+    const unflattened = event.unflatten();
+
+    expect(unflattened).toEqual({
+      '@timestamp': '2024-10-10T10:10:10.000Z',
+      service: { name: 'node-svc' },
+      links: { span_id: ['link1', 'link2'] },
+    });
+  });
+
+  it('prevents mutations on the original object', () => {
+    const smallInput = {
+      '@timestamp': ['2024-10-10T10:10:10.000Z'],
+      'service.name': ['node-svc'],
+      'links.span_id': ['link1', 'link2'],
+    };
+
+    const event = accessKnownApmEventFields(smallInput as Partial<FlattenedApmEvent>);
+
+    // The proxied object is immutable. It will prevent mutations and will throw a TypeError
+    expect(() => {
+      // Disabling type checking here to ensure we also have runtime protection of immutability,
+      // so people can't just cast their way out of this. Normally, doing the setter op will
+      // error at compile time.
+      // @ts-ignore
+      event['agent.name'] = 'nodejs';
+    }).toThrowError("'set' on proxy: trap returned falsish for property 'agent.name'");
+  });
+});
diff --git a/x-pack/solutions/observability/plugins/apm_data_access/server/utils/access_known_fields.ts b/x-pack/solutions/observability/plugins/apm_data_access/server/utils/access_known_fields.ts
@@ -0,0 +1,117 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { unflattenKnownApmEventFields } from './unflatten_known_fields';
+import {
+  type UnflattenedKnownFields,
+  type FlattenedApmEvent,
+  type MapToSingleOrMultiValue,
+  KNOWN_SINGLE_VALUED_FIELDS_SET,
+} from './utility_types';
+
+type RequiredApmFields<
+  T extends Partial<FlattenedApmEvent>,
+  R extends keyof FlattenedApmEvent = never
+> = Partial<T> & Required<Pick<T, R>>;
+
+/**
+ * A Proxied APM document that is strongly typed and runtime checked to be correct.
+ * Accessing fields from the document will correctly return single or multi values
+ * according to known field types.
+ */
+type ProxiedApmEvent<
+  T extends Partial<FlattenedApmEvent>,
+  R extends keyof FlattenedApmEvent = never
+> = Readonly<MapToSingleOrMultiValue<RequiredApmFields<T, R>>>;
+
+/**
+ * Interface for exposing an `unflatten()` method on proxied APM documents.
+ */
+interface UnflattenApmDocument<
+  T extends Partial<FlattenedApmEvent>,
+  R extends keyof FlattenedApmEvent = never
+> {
+  /**
+   * Unflattens the APM Event, so fields can be accessed via `event.service?.name`.
+   *
+   * ```ts
+   * const unflattened = accessKnownApmEventFields(hit, ['service.name']).unflatten();
+   *
+   * console.log(unflattened.service.name); // outputs "node-svc" for example
+   * ```
+   */
+  unflatten(): UnflattenedKnownFields<RequiredApmFields<T, R>>;
+}
+
+/**
+ * An APM document that is strongly typed and runtime checked to be correct.
+ * Accessing fields from the document will correctly return single or multi values
+ * according to known field types.
+ *
+ * An `unflatten()` method is also exposed by this document to return an unflattened
+ * version of the document.
+ */
+type ApmDocument<
+  T extends Partial<FlattenedApmEvent>,
+  R extends keyof FlattenedApmEvent = never
+> = ProxiedApmEvent<T, R> & UnflattenApmDocument<T, R>;
+
+/**
+ * Validates an APM Event document, checking if it has all the required fields if provided,
+ * returning a proxied version of the document to allow strongly typed access to known single
+ * or multi-value fields. The proxy also exposes an `unflatten()` method to return an unflattened
+ * version of the document.
+ *
+ * ## Example
+ *
+ * ```ts
+ * const event = accessKnownApmEventFields(hit, ['service.name']);
+ *
+ * // The key is strongly typed to be `keyof FlattenedApmEvent`.
+ * console.log(event['service.name']) // => outputs `"node-svc"`, not `["node-svc"]` as in the original doc
+ *
+ * const unflattened = event.unflatten();
+ *
+ * console.log(unflattened.service.name); // => outputs "node-svc" like above
+ */
+export function accessKnownApmEventFields<
+  T extends Partial<FlattenedApmEvent>,
+  R extends keyof FlattenedApmEvent = never
+>(fields: T, required?: R[]): ApmDocument<T, R>;
+
+export function accessKnownApmEventFields(fields: Record<string, any>, required?: string[]) {
+  if (required) {
+    const missingRequiredFields = required.filter((key) => {
+      const value = fields[key];
+
+      return value == null || (Array.isArray(value) && value.length === 0);
+    });
+
+    if (missingRequiredFields.length) {
+      throw new Error(`Missing required fields (${missingRequiredFields.join(', ')}) in event`);
+    }
+  }
+
+  return new Proxy(fields, accessHandler);
+}
+
+const accessHandler = {
+  get(fields: Record<string, any>, key: string) {
+    if (key === 'unflatten') {
+      return () => unflattenKnownApmEventFields(fields);
+    }
+
+    const value = fields[key];
+
+    return KNOWN_SINGLE_VALUED_FIELDS_SET.has(key) && Array.isArray(value) ? value[0] : value;
+  },
+
+  // Trap any setters to make the proxied object immutable.
+  set() {
+    return false;
+  },
+};
diff --git a/x-pack/solutions/observability/plugins/apm_data_access/server/utils/unflatten_known_fields.ts b/x-pack/solutions/observability/plugins/apm_data_access/server/utils/unflatten_known_fields.ts
diff --git a/x-pack/solutions/observability/plugins/apm_data_access/server/utils/utility_types.ts b/x-pack/solutions/observability/plugins/apm_data_access/server/utils/utility_types.ts

Original file line number	Diff line number	Diff line change
`@@ -16,3 +16,4 @@ export {`
`16`	`16`
`17`	`17`	`export { withApmSpan } from './utils/with_apm_span';`
`18`	`18`	`export { unflattenKnownApmEventFields } from './utils/unflatten_known_fields';`
	`19`	`+export { accessKnownApmEventFields } from './utils/access_known_fields';`