chore: import upstream snapshot with attribution

2026-07-13 13:32:57 +08:00
commit cd420f9332
4811 changed files with 884702 additions and 0 deletions
@@ -0,0 +1,113 @@
+---
+title: "Usage"
+description: "Get compute duration and cost from inside a run, or for a specific block of code."
+---
+
+## Getting the run cost and duration
+
+You can get the cost and duration of the current including retries of the same run.
+
+```ts
+import { task, usage, wait } from "@trigger.dev/sdk";
+
+export const heavyTask = task({
+  id: "heavy-task",
+  machine: {
+    preset: "medium-2x",
+  },
+  run: async (payload, { ctx }) => {
+    // Do some compute
+    const result = await convertVideo(payload.videoUrl);
+
+    // Get the current cost and duration up until this line of code
+    // This includes the compute time of the previous lines
+    let currentUsage = usage.getCurrent();
+    /* currentUsage = {
+        compute: {
+          attempt: {
+            costInCents: 0.01700,
+            durationMs: 1000,
+          },
+          total: {
+            costInCents: 0.0255,
+            durationMs: 1500,
+          },
+        },
+        baseCostInCents: 0.0025,
+        totalCostInCents: 0.028,
+      } 
+      */
+
+    // In the cloud product we do not count waits towards the compute cost or duration.
+    // We also don't include time between attempts or before the run starts executing your code.
+    // So this line does not affect the cost or duration.
+    await wait.for({ seconds: 5 });
+
+    // This will give the same result as before the wait.
+    currentUsage = usage.getCurrent();
+
+    // Do more compute
+    const result = await convertVideo(payload.videoUrl);
+
+    // This would give a different value
+    currentUsage = usage.getCurrent();
+  },
+});
+```
+
+<Note>
+  In Trigger.dev cloud we do not include time between attempts, before your code executes, or waits
+  towards the compute cost or duration.
+</Note>
+
+## Getting the run cost and duration from your backend
+
+You can use [runs.retrieve()](/management/runs/retrieve) to get a single run or [runs.list()](/management/runs/list) to get a list of runs. The response will include `costInCents` `baseCostInCents` and `durationMs` fields.
+
+```ts single run
+import { runs } from "@trigger.dev/sdk";
+
+const run = await runs.retrieve("run-id");
+console.log(run.costInCents, run.baseCostInCents, run.durationMs);
+const totalCost = run.costInCents + run.baseCostInCents;
+```
+
+```ts multiple runs
+import { runs } from "@trigger.dev/sdk";
+
+let totalCost = 0;
+for await (const run of runs.list({ tag: "user_123456" })) {
+  totalCost += run.costInCents + run.baseCostInCents;
+  console.log(run.costInCents, run.baseCostInCents, run.durationMs);
+}
+
+console.log("Total cost", totalCost);
+```
+
+## Getting the cost and duration of a block of code
+
+You can also wrap code with `usage.measure` to get the cost and duration of that block of code:
+
+```ts
+import { usage, logger } from "@trigger.dev/sdk";
+
+// Inside a task run function, or inside a function that's called from there.
+const { result, compute } = await usage.measure(async () => {
+  //...Do something for 1 second
+  return {
+    foo: "bar",
+  };
+});
+
+logger.info("Result", { result, compute });
+/* result = {
+    foo: "bar"
+  }
+  compute = {
+    costInCents: 0.01700,
+    durationMs: 1000,
+  }
+*/
+```
+
+This will work from inside the `run` function, our lifecycle hooks (like `onStart`, `onFailure`, `onSuccess`, etc.), or any function you're calling from the `run` function. It won't work for code that's not executed using Trigger.dev.