replace specific timing fields with generic label/duration pairs & add feature flag

Author: adambenhassen

integration-tests/tests/api/app-deployments.spec.ts

@@ -93,10 +93,9 @@ const AddDocumentsToAppDeployment = graphql(`
           version
           status
         }
-        timing {
-          totalMs
-          s3Ms
-          clickhouseMs
+        timings {
+          label
+          duration
         }
       }
     }
@@ -306,7 +305,7 @@ test('create app deployment, add operations, publish, access via CDN (happy path
         version: '1.0.0',
         status: 'pending',
       },
-      timing: expect.any(Object),
+      timings: null,
     },
   });
 

packages/libraries/cli/src/commands/app/create.ts

@@ -223,6 +223,7 @@ export default class AppCreate extends Command<typeof AppCreate> {
               documents: buffer,
               format:
                 format === 'v1' ? AppDeploymentFormatType.V1 : AppDeploymentFormatType.V2,
+              showTimings: flags.showTiming || undefined,
             },
           },
         });
@@ -251,11 +252,11 @@ export default class AppCreate extends Command<typeof AppCreate> {
           throw new APIError(result.addDocumentsToAppDeployment.error.message);
         }
 
-        if (flags.showTiming && result.addDocumentsToAppDeployment.ok?.timing) {
-          const t = result.addDocumentsToAppDeployment.ok.timing;
-          this.log(
-            `  Batch timing: ${t.totalMs}ms total (${t.documentsProcessed} docs, parse: ${t.parsingMs}ms, validate: ${t.validationMs}ms, coords: ${t.coordinateExtractionMs}ms, ch: ${t.clickhouseMs}ms, s3: ${t.s3Ms}ms)`,
-          );
+        if (flags.showTiming && result.addDocumentsToAppDeployment.ok?.timings?.length) {
+          const parts = result.addDocumentsToAppDeployment.ok.timings
+            .map(t => `${t.label}: ${t.duration}ms`)
+            .join(', ');
+          this.log(`  Batch timing: ${parts}`);
         }
 
         buffer = [];
@@ -319,14 +320,9 @@ const AddDocumentsToAppDeploymentMutation = graphql(/* GraphQL */ `
           version
           status
         }
-        timing {
-          totalMs
-          parsingMs
-          validationMs
-          coordinateExtractionMs
-          clickhouseMs
-          s3Ms
-          documentsProcessed
+        timings {
+          label
+          duration
         }
       }
       error {

packages/services/api/src/create.ts

@@ -4,7 +4,10 @@ import { TaskScheduler } from '@hive/workflows/kit';
 import { adminModule } from './modules/admin';
 import { alertsModule } from './modules/alerts';
 import { appDeploymentsModule } from './modules/app-deployments';
-import { APP_DEPLOYMENTS_ENABLED } from './modules/app-deployments/providers/app-deployments-enabled-token';
+import {
+  APP_DEPLOYMENT_TIMINGS_ENABLED,
+  APP_DEPLOYMENTS_ENABLED,
+} from './modules/app-deployments/providers/app-deployments-enabled-token';
 import { auditLogsModule } from './modules/audit-logs';
 import { AuditLogRecorder } from './modules/audit-logs/providers/audit-log-recorder';
 import { AuditLogS3Config } from './modules/audit-logs/providers/audit-logs-manager';
@@ -115,6 +118,7 @@ export function createRegistry({
   organizationOIDC,
   pubSub,
   appDeploymentsEnabled,
+  appDeploymentTimingsEnabled,
   schemaProposalsEnabled,
   otelTracingEnabled,
   prometheus,
@@ -160,6 +164,7 @@ export function createRegistry({
   organizationOIDC: boolean;
   pubSub: HivePubSub;
   appDeploymentsEnabled: boolean;
+  appDeploymentTimingsEnabled: boolean;
   schemaProposalsEnabled: boolean;
   otelTracingEnabled: boolean;
   prometheus: null | Record<string, unknown>;
@@ -283,6 +288,11 @@ export function createRegistry({
       useValue: appDeploymentsEnabled,
       scope: Scope.Singleton,
     },
+    {
+      provide: APP_DEPLOYMENT_TIMINGS_ENABLED,
+      useValue: appDeploymentTimingsEnabled,
+      scope: Scope.Singleton,
+    },
     {
       provide: SCHEMA_PROPOSALS_ENABLED,
       useValue: schemaProposalsEnabled,

packages/services/api/src/modules/app-deployments/module.graphql.ts

@@ -290,6 +290,11 @@ export default gql`
     V2 enables cross-version deduplication and delta uploads (requires SHA256 hashes).
     """
     format: AppDeploymentFormatType
+    """
+    When true, the response will include timing measurements for document processing.
+    Intended for benchmarking; requires server-side timing to be enabled.
+    """
+    showTimings: Boolean
   }
 
   type AddDocumentsToAppDeploymentErrorDetails {
@@ -312,42 +317,22 @@ export default gql`
   }
 
   """
-  Timing breakdown for document upload operations. All time values are in milliseconds.
+  A labeled timing measurement from document upload processing.
   """
   type DocumentUploadTiming {
     """
-    Total elapsed time for the entire batch processing.
-    """
-    totalMs: Int!
-    """
-    Time spent parsing GraphQL documents.
-    """
-    parsingMs: Int!
-    """
-    Time spent validating documents against the schema.
-    """
-    validationMs: Int!
-    """
-    Time spent extracting schema coordinates from documents.
-    """
-    coordinateExtractionMs: Int!
-    """
-    Time spent inserting records into ClickHouse.
-    """
-    clickhouseMs: Int!
-    """
-    Time spent uploading documents to S3.
+    Identifies the processing phase (e.g., "total", "parsing", "validation", "s3", "clickhouse").
     """
-    s3Ms: Int!
+    label: String!
     """
-    Number of documents successfully processed.
+    Duration in milliseconds.
     """
-    documentsProcessed: Int!
+    duration: Int!
   }
 
   type AddDocumentsToAppDeploymentOk {
     appDeployment: AppDeployment!
-    timing: DocumentUploadTiming
+    timings: [DocumentUploadTiming!]
   }
 
   type AddDocumentsToAppDeploymentResult {

packages/services/api/src/modules/app-deployments/providers/app-deployments-enabled-token.ts

@@ -1,3 +1,6 @@
 import { InjectionToken } from 'graphql-modules';
 
 export const APP_DEPLOYMENTS_ENABLED = new InjectionToken<boolean>('APP_DEPLOYMENTS_ENABLED');
+export const APP_DEPLOYMENT_TIMINGS_ENABLED = new InjectionToken<boolean>(
+  'APP_DEPLOYMENT_TIMINGS_ENABLED',
+);

packages/services/api/src/modules/app-deployments/providers/persisted-document-ingester.ts

@@ -24,15 +24,7 @@ type DocumentRecord = {
   schemaCoordinates: Array<string>;
 };
 
-export type ProcessingTiming = {
-  totalMs: number;
-  parsingMs: number;
-  validationMs: number;
-  coordinateExtractionMs: number;
-  clickhouseMs: number;
-  s3Ms: number;
-  documentsProcessed: number;
-};
+export type ProcessingTiming = Array<{ label: string; duration: number }>;
 
 const AppDeploymentOperationHashModel = z
   .string()
@@ -328,15 +320,14 @@ export class PersistedDocumentIngester {
 
     return {
       type: 'success' as const,
-      timing: {
-        totalMs: Math.round(totalMs),
-        parsingMs: Math.round(parsingMs),
-        validationMs: Math.round(validationMs),
-        coordinateExtractionMs: Math.round(coordinateExtractionMs),
-        clickhouseMs: Math.round(clickhouseMs),
-        s3Ms: Math.round(s3Ms),
-        documentsProcessed: documents.length,
-      },
+      timing: [
+        { label: 'total', duration: Math.round(totalMs) },
+        { label: 'parsing', duration: Math.round(parsingMs) },
+        { label: 'validation', duration: Math.round(validationMs) },
+        { label: 'coordinate-extraction', duration: Math.round(coordinateExtractionMs) },
+        { label: 'clickhouse', duration: Math.round(clickhouseMs) },
+        { label: 's3', duration: Math.round(s3Ms) },
+      ],
     };
   }
 
@@ -521,7 +512,7 @@ export class PersistedDocumentIngester {
       })(),
       (async () => {
         const start = performance.now();
-        await this.insertS3Documents({ ...args, isV1Format: args.isV1Format });
+        await this.insertS3Documents(args);
         return performance.now() - start;
       })(),
     ]);

packages/services/api/src/modules/app-deployments/resolvers/Mutation/addDocumentsToAppDeployment.ts

@@ -1,3 +1,4 @@
+import { APP_DEPLOYMENT_TIMINGS_ENABLED } from '../../providers/app-deployments-enabled-token';
 import { AppDeploymentsManager } from '../../providers/app-deployments-manager';
 import type { MutationResolvers } from './../../../../__generated__/types';
 
@@ -24,11 +25,13 @@ export const addDocumentsToAppDeployment: NonNullable<
     };
   }
 
+  const timingsEnabled = injector.get<boolean>(APP_DEPLOYMENT_TIMINGS_ENABLED);
+
   return {
     error: null,
     ok: {
       appDeployment: result.appDeployment,
-      timing: result.timing,
+      timings: timingsEnabled && input.showTimings ? result.timing : null,
     },
   };
 };

packages/services/server/.env.template

@@ -23,6 +23,7 @@ INTEGRATION_GITHUB="<sync>"
 INTEGRATION_GITHUB_APP_ID="<sync>"
 INTEGRATION_GITHUB_APP_PRIVATE_KEY="<sync>"
 FEATURE_FLAGS_APP_DEPLOYMENTS_ENABLED="0"
+FEATURE_FLAGS_APP_DEPLOYMENT_TIMINGS_ENABLED="0"
 FEATURE_FLAGS_SCHEMA_PROPOSALS_ENABLED="0"
 FEATURE_FLAGS_OTEL_TRACING_ENABLED="0"
 

packages/services/server/src/environment.ts

@@ -40,6 +40,9 @@ const EnvironmentModel = zod.object({
   FEATURE_FLAGS_APP_DEPLOYMENTS_ENABLED: emptyString(
     zod.union([zod.literal('1'), zod.literal('0')]).optional(),
   ),
+  FEATURE_FLAGS_APP_DEPLOYMENT_TIMINGS_ENABLED: emptyString(
+    zod.union([zod.literal('1'), zod.literal('0')]).optional(),
+  ),
   FEATURE_FLAGS_SCHEMA_PROPOSALS_ENABLED: emptyString(
     zod.union([zod.literal('1'), zod.literal('0')]).optional(),
   ),
@@ -555,6 +558,8 @@ export const env = {
   featureFlags: {
     /** Whether app deployments should be enabled by default for everyone. */
     appDeploymentsEnabled: base.FEATURE_FLAGS_APP_DEPLOYMENTS_ENABLED === '1',
+    /** Whether app deployment upload timings should be exposed via the GraphQL API. */
+    appDeploymentTimingsEnabled: base.FEATURE_FLAGS_APP_DEPLOYMENT_TIMINGS_ENABLED === '1',
     /** Whether schema proposals should be enabled for all organizations. */
     schemaProposalsEnabled: base.FEATURE_FLAGS_SCHEMA_PROPOSALS_ENABLED === '1',
     /** Whether OTEL tracing should be enabled for all organizations. */

packages/services/server/src/index.ts

@@ -373,6 +373,7 @@ export async function main() {
       supportConfig: env.zendeskSupport,
       pubSub,
       appDeploymentsEnabled: env.featureFlags.appDeploymentsEnabled,
+      appDeploymentTimingsEnabled: env.featureFlags.appDeploymentTimingsEnabled,
       schemaProposalsEnabled: env.featureFlags.schemaProposalsEnabled,
       otelTracingEnabled: env.featureFlags.otelTracingEnabled,
       prometheus: env.prometheus,