refactor: fold attribute docs into the telemetry constants, neverthrow cancel emission

Replaces the standalone DEPLOYMENT_TELEMETRY_ATTRIBUTES.md with short
comments on the DeploymentTelemetryAttributes keys, and chains the
canceled-lifecycle emission through the cancel ResultAsync pipeline
instead of a fire-and-forget promise.

Author: myftija

apps/webapp/app/v3/DEPLOYMENT_TELEMETRY_ATTRIBUTES.md

@@ -1,33 +1,57 @@
 import { BuildServerMetadata } from "@trigger.dev/core/v3";
 
-// Attribute names for the deployment telemetry events (see
-// DEPLOYMENT_TELEMETRY_ATTRIBUTES.md next to this file). This module is the single owner of these names — Axiom
-// queries, dashboards, and monitors reference them, so treat renames as
-// breaking changes.
+/**
+ * Attribute names for the `deployment.lifecycle` and `deployment.initialized`
+ * telemetry events (emitted by services/recordDeploymentLifecycle.server.ts).
+ * This module is the single owner of these names — external queries,
+ * dashboards, and monitors reference them, so treat renames as breaking.
+ *
+ * Query gotchas: dedup with `arg_max(_time, *) by deployment.id` (job retries
+ * can double-emit); the span's `_time` is the deployment's createdAt, so a
+ * TIMED_OUT event lands backdated by up to the full deploy timeout — monitor
+ * windows must exceed it; phase durations are omitted (not zero) when a
+ * boundary timestamp is missing, and `total_ms` excludes local-bundle's
+ * pre-init client work (esbuild + upload) until the CLI reports timings.
+ */
 export const DeploymentTelemetryAttributes = {
   ORG_ID: "$trigger.org.id",
   PROJECT_ID: "$trigger.project.id",
+  // Project external ref ("proj_…")
   PROJECT_REF: "$trigger.project.ref",
   ENV_ID: "$trigger.env.id",
+  // PRODUCTION / STAGING / PREVIEW / DEVELOPMENT
   ENV_TYPE: "$trigger.env.type",
+  // Deployment friendly id — the dedup key
   DEPLOYMENT_ID: "deployment.id",
   VERSION: "deployment.version",
+  // lifecycle: terminal status; initialized: initial status (PENDING/BUILDING)
   STATUS: "deployment.status",
+  // status === DEPLOYED; CANCELED is excluded from failure rates
   SUCCESS: "deployment.success",
+  // depot / native / local_bundle (see deriveBuildPath)
   BUILD_PATH: "deployment.build_path",
+  // V1 / MANAGED (run engine)
   WORKER_TYPE: "deployment.worker_type",
   RUNTIME: "deployment.runtime",
+  // Set at indexing; null for pre-index failures
   RUNTIME_VERSION: "deployment.runtime_version",
+  // From x-trigger-cli-version at init; null for pre-column history
   CLI_VERSION: "deployment.cli_version",
   TRIGGERED_VIA: "deployment.triggered_via",
   COMMIT_SHA: "deployment.commit_sha",
+  // error.* only on FAILED/TIMED_OUT; CANCELED uses canceled_reason
   ERROR_NAME: "deployment.error.name",
   ERROR_MESSAGE: "deployment.error.message",
   CANCELED_REASON: "deployment.canceled_reason",
+  // createdAt → terminal (also the span's own duration)
   DURATION_TOTAL_MS: "deployment.duration.total_ms",
+  // createdAt → startedAt; ≈0 when created directly in BUILDING (depot)
   DURATION_QUEUE_MS: "deployment.duration.queue_ms",
+  // startedAt → installedAt; build-server paths only (depot never sets it)
   DURATION_INSTALL_MS: "deployment.duration.install_ms",
+  // (installedAt ?? startedAt) → builtAt
   DURATION_BUILDING_MS: "deployment.duration.building_ms",
+  // builtAt → terminal; for depot dominated by the server-side registry push
   DURATION_DEPLOYING_MS: "deployment.duration.deploying_ms",
 } as const;
 

apps/webapp/app/v3/deploymentTelemetry.ts

@@ -239,8 +239,6 @@ export class DeploymentService extends BaseService {
         if (result.count === 0) {
           return errAsync({ type: "deployment_cannot_be_cancelled" as const });
         }
-        // Fire-and-forget: telemetry must never affect the cancel result.
-        void this.#recordCanceledLifecycle(deployment.id);
         return okAsync({ deployment });
       });
 
@@ -253,6 +251,14 @@ export class DeploymentService extends BaseService {
     return this.getDeployment(authenticatedEnv.id, friendlyId)
       .andThen(validateDeployment)
       .andThen(cancelDeployment)
+      .andThen(({ deployment }) =>
+        this.#recordCanceledLifecycle(deployment.id)
+          .orElse((error) => {
+            logger.error("Failed to record canceled deployment lifecycle", { error });
+            return okAsync(undefined);
+          })
+          .map(() => ({ deployment }))
+      )
       .andThen(({ deployment }) =>
         this.appendToEventLog(deployment.environment.project, deployment, [
           {
@@ -479,9 +485,9 @@ export class DeploymentService extends BaseService {
 
   // The cancel path only carries a narrow row selection, so re-fetch the full
   // row (post-update, status already CANCELED) for the lifecycle event.
-  async #recordCanceledLifecycle(deploymentId: string) {
-    try {
-      const canceled = await this._prisma.workerDeployment.findFirst({
+  #recordCanceledLifecycle(deploymentId: string) {
+    return fromPromise(
+      this._prisma.workerDeployment.findFirst({
         where: { id: deploymentId },
         include: {
           environment: {
@@ -492,8 +498,12 @@ export class DeploymentService extends BaseService {
             },
           },
         },
-      });
-
+      }),
+      (error) => ({
+        type: "other" as const,
+        cause: error,
+      })
+    ).map((canceled) => {
       if (!canceled || canceled.status !== "CANCELED") return;
 
       recordDeploymentLifecycle({
@@ -507,9 +517,7 @@ export class DeploymentService extends BaseService {
           environmentType: canceled.environment.type,
         },
       });
-    } catch (error) {
-      logger.error("Failed to record canceled deployment lifecycle", { deploymentId, error });
-    }
+    });
   }
 
   private getDeployment(environmentId: string, friendlyId: string) {

apps/webapp/app/v3/services/deployment.server.ts

@@ -49,8 +49,8 @@ type EnvironmentInfo = {
  * `deployment.lifecycle` span, backdated to span the deployment's real
  * lifetime (createdAt → terminal) and carrying per-phase durations as
  * attributes. This is THE per-deployment analytics event: build-path
- * comparison dashboards and monitors are built on it (see
- * ../deploymentTelemetry.ts and DEPLOYMENT_TELEMETRY_ATTRIBUTES.md for the attribute contract).
+ * comparison dashboards and monitors are built on it (the attribute contract
+ * lives in ../deploymentTelemetry.ts).
  *
  * Call exactly once per terminal transition, only after a guarded status
  * write confirmed this caller won the transition. Emitted on ROOT_CONTEXT