@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/migrating-from-v3.mdx

@@ -0,0 +1,332 @@
+---
+title: "Migrating from v3"
+description: "What's new in v4, how to migrate, and breaking changes."
+---
+
+import NodeVersions from "/snippets/node-versions.mdx";
+import MigrateV4UsingAi from "/snippets/migrate-v4-using-ai.mdx";
+
+<Warning>
+  **Trigger.dev v3 has been retired**
+
+Trigger.dev v3 is end of life. v4 is stable, fully supported, and recommended for all users.
+
+- On Trigger.dev Cloud, v3 has been shut down: v3 triggers and deploys no longer run.
+- If you self-host, 4.5.0 is the last version we officially support for running v3. Stay on 4.5.0 or upgrade to v4; 4.5.1 and later reject v3 triggers, batch triggers, and deploys with an upgrade message.
+
+**What you need to do:** Migrate to v4. The migration takes about 2 minutes; follow the steps below. If you have questions or need help, [contact us](https://trigger.dev/contact) or reach out in our [Discord](https://trigger.dev/discord).
+
+</Warning>
+
+## What's new in v4?
+
+| Feature                                                              | Description                                                                                                                                                                                                |
+| :------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Wait for token](/wait-for-token)                                    | Create and wait for tokens to be completed, enabling approval workflows and waiting for arbitrary external conditions.                                                                                     |
+| Wait idempotency                                                     | Skip waits if the same idempotency key is used again when using [wait for](/wait-for#wait-idempotency), [wait until](/wait-until#wait-idempotency), or [wait for token](/wait-for-token#wait-idempotency). |
+| [Priority](/runs/priority)                                           | Specify a priority when triggering a task.                                                                                                                                                                 |
+| [Global lifecycle hooks](/tasks/overview#global-lifecycle-hooks)     | Register global lifecycle hooks that are executed for all runs, regardless of the task.                                                                                                                    |
+| [onWait and onResume](/tasks/overview#onwait-and-onresume-functions) | Run code when a run is paused or resumed because of a wait.                                                                                                                                                |
+| [onComplete](/tasks/overview#oncomplete-function)                    | Run code when a run completes, regardless of whether it succeeded or failed.                                                                                                                               |
+| [onCancel](/tasks/overview#oncancel-function)                        | Run code when a run is cancelled.                                                                                                                                                                          |
+| [Hidden tasks](/hidden-tasks)                                        | Create tasks that are not exported from your trigger files but can still be executed.                                                                                                                      |
+| [Middleware & locals](#middleware-and-locals)                        | The middleware system runs at the top level, executing before and after all lifecycle hooks. The locals API allows sharing data between middleware and hooks.                                              |
+| [useWaitToken](/realtime/react-hooks/use-wait-token)                 | Use the useWaitToken hook to complete a wait token from a React component.                                                                                                                                 |
+| [Task-backed AI tools](/tasks/schemaTask#task-backed-ai-tools)       | Use `schemaTask` with AI SDK `tool()` and `ai.toolExecute()` (legacy `ai.tool` is deprecated).                                                                                                              |
+
+## Node.js support
+
+<NodeVersions />
+
+## How to migrate to v4
+
+First read the deprecations and breaking changes sections below.
+
+We recommend the following steps to migrate to v4:
+
+1. Install the v4 package.
+2. Run the `trigger dev` CLI command and test your tasks locally, fixing any breaking changes.
+3. Deploy to the staging environment and test your tasks in staging, fixing any breaking changes. (this step is optional, but highly recommended)
+4. Once you've verified that v4 is working as expected, you should deploy your application backend with the updated v4 package.
+5. Once you've deployed your application backend, you should deploy your tasks to the production environment.
+
+Note that between steps 4 and 5, runs triggered with the v4 package will continue using v3, and only new runs triggered after step 5 is complete will use v4.
+
+<Warning>
+  Once v4 is activated in your environment, there will be a period of time where old runs will
+  continue to execute using v3, while new runs will use v4. Because these engines use completely
+  different underlying queues and concurrency models, it's possible you may have up to double the
+  amount of concurrently executing runs. Once the runs drain from the old run engine, the
+  concurrency will return to normal.
+</Warning>
+
+<Note>
+  When migrating from v3 to v4, our infrastructure IPs may change. If you use IP allowlisting (e.g. for databases or APIs), [update your allowlists](https://trigger.dev/changelog/static-ips) with the current static IPs before or immediately after switching to v4 to avoid connectivity issues or downtime.
+</Note>
+
+## Migrate using AI
+
+Use the prompt in the accordion below to help you migrate your v3 tasks to v4. The prompt gives good results when using Claude 4 Sonnet. You’ll need a relatively large token limit.
+
+<MigrateV4UsingAi />
+
+## Installation
+
+To opt-in to using v4, you will need to update your dependencies to the latest version:
+
+<CodeGroup>
+
+```bash npx
+npx trigger.dev@latest update
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest update
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest update
+```
+
+</CodeGroup>
+
+This command should update all of your `@trigger.dev/*` packages to a `4.x` version.
+
+## Deprecations
+
+We've deprecated the following APIs:
+
+### @trigger.dev/sdk/v3
+
+We've deprecated the `@trigger.dev/sdk/v3` import path and moved to a new path:
+
+```ts
+// This still works, but will be removed in a future version
+import { task } from "@trigger.dev/sdk/v3";
+
+// This is the new path
+import { task } from "@trigger.dev/sdk";
+```
+
+### `handleError` and `init`
+
+We've renamed the `handleError` hook to `catchError` to better reflect that it can catch and react to errors. `handleError` will be removed in a future version.
+
+`init` was previously used to initialize data used in the run function:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+const myTask = task({
+  init: async () => {
+    return {
+      myClient: new MyClient(),
+    };
+  },
+  run: async (payload: any, { ctx, init }) => {
+    const client = init.myClient;
+    await client.doSomething();
+  },
+});
+```
+
+This has now been deprecated in favor of the `locals` API and middleware. See the [Improved middleware and locals](/tasks/overview#middleware-and-locals-functions) section for more details.
+
+### toolTask
+
+We've deprecated the `toolTask` function, which created both a Trigger.dev task and a tool compatible with the Vercel [AI SDK](https://vercel.com/docs/ai-sdk):
+
+```ts
+import { toolTask, schemaTask } from "@trigger.dev/sdk";
+import { z } from "zod";
+import { generateText } from "ai";
+
+const myToolTask = toolTask({
+  id: "my-tool-task",
+  run: async (payload: any, { ctx }) => {},
+});
+
+export const myAiTask = schemaTask({
+  id: "my-ai-task",
+  schema: z.object({
+    text: z.string(),
+  }),
+  run: async (payload, { ctx }) => {
+    const { text } = await generateText({
+      prompt: payload.text,
+      model: openai("gpt-4o"),
+      tools: {
+        myToolTask,
+      },
+    });
+  },
+});
+```
+
+We've replaced the `toolTask` function with `schemaTask` plus AI SDK `tool()` and `ai.toolExecute()` (the older `ai.tool()` wrapper is deprecated). See [Task-backed AI tools](/tasks/schemaTask#task-backed-ai-tools).
+
+## Breaking changes
+
+### Queue changes
+
+Previously, it was possible to specify a queue name of a queue that did not exist, along with a concurrency limit. The queue would then be created "on-demand" with the specified concurrency limit. If the queue did exist, the concurrency limit of the queue would be updated to the specified value:
+
+```ts
+await myTask.trigger({ foo: "bar" }, { queue: { name: "my-queue", concurrencyLimit: 10 } });
+```
+
+This is no longer possible, and queues must now be defined ahead of time using the `queue` function:
+
+```ts
+import { queue } from "@trigger.dev/sdk";
+
+const myQueue = queue({
+  name: "my-queue",
+  concurrencyLimit: 10,
+});
+```
+
+Now when you trigger a task, you can only specify the queue by name:
+
+```ts
+await myTask.trigger({ foo: "bar" }, { queue: "my-queue" });
+```
+
+Or you can set the queue on the task:
+
+```ts
+import { queue, task } from "@trigger.dev/sdk";
+
+const myQueue = queue({
+  name: "my-queue",
+  concurrencyLimit: 10,
+});
+
+export const myTask = task({
+  id: "my-task",
+  queue: myQueue,
+  run: async (payload: any, { ctx }) => {},
+});
+
+// You can optionally specify the queue directly on the task
+export const myTask2 = task({
+  id: "my-task-2",
+  queue: {
+    name: "my-queue-2",
+    concurrencyLimit: 50,
+  },
+  run: async (payload: any, { ctx }) => {},
+});
+```
+
+Now you can trigger these tasks without having to specify the queue name in the trigger options:
+
+```ts
+await myTask.trigger({ foo: "bar" }); // Will use the queue defined on the task
+await myTask2.trigger({ foo: "bar" }); // Will use the queue defined on the task
+```
+
+If you're using `concurrencyKey` you can specify the `queue` and `concurrencyKey` like this:
+
+```ts
+const handle = await generatePullRequest.trigger(data, {
+  queue: "paid-users",
+  concurrencyKey: data.userId,
+});
+```
+
+For each unique value of `concurrencyKey`, a new queue will be created using the `concurrencyLimit` from the queue. This allows you to have a queue per user.
+
+### Lifecycle hooks
+
+We've changed the function signatures of the lifecycle hooks to be more consistent and easier to use, by unifying all the parameters into a single object that can be destructured.
+
+Previously, hooks received a payload as the first argument and then an additional object as the second argument:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  onStart: (payload, { ctx }) => {},
+  run: async (payload, { ctx }) => {},
+});
+```
+
+Now, all the parameters are passed in a single object:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  onStart: ({ payload, ctx }) => {},
+  // The run function still uses separate parameters
+  run: async (payload, { ctx }) => {},
+});
+```
+
+This is true for all the lifecycle hooks:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  onStart: ({ payload, ctx, task }) => {},
+  onSuccess: ({ payload, ctx, task, output }) => {},
+  onFailure: ({ payload, ctx, task, error }) => {},
+  onWait: ({ payload, ctx, task, wait }) => {},
+  onResume: ({ payload, ctx, task, wait }) => {},
+  onComplete: ({ payload, ctx, task, result }) => {},
+  catchError: ({ payload, ctx, task, error, retry, retryAt, retryDelayInMs }) => {},
+  run: async (payload, { ctx }) => {},
+});
+```
+
+### Context changes
+
+We've made a few small changes to the `ctx` object:
+
+- `ctx.attempt.id` and `ctx.attempt.status` have been removed. `ctx.attempt.number` is still available.
+- `ctx.task.exportName` has been removed (since we no longer require tasks to be exported to be triggered).
+
+### BatchTrigger changes
+
+The `batchTrigger` function no longer returns a `runs` list directly. In v3, you could access the runs directly from the batch handle:
+
+```ts
+// In v3
+const batchHandle = await tasks.batchTrigger([
+  [myTask, { foo: "bar" }],
+  [myOtherTask, { baz: "qux" }],
+]);
+
+// You could access runs directly
+console.log(batchHandle.runs);
+```
+
+In v4, you now need to use the `batch.retrieve()` method to get the batch with its runs:
+
+```ts
+// In v4
+const batchHandle = await tasks.batchTrigger([
+  [myTask, { foo: "bar" }],
+  [myOtherTask, { baz: "qux" }],
+]);
+
+// Now you need to retrieve the batch to get the runs
+const batch = await batch.retrieve(batchHandle.batchId);
+console.log(batch.runs);
+```
+
+### OpenTelemetry
+
+We are now using newer versions of the OpenTelemetry packages. This means that if you're using custom exporters you may need to update the packages:
+
+| Package                                   | Previous Version | New Version | Change Type  |
+| ----------------------------------------- | ---------------- | ----------- | ------------ |
+| `@opentelemetry/api-logs`                 | 0.52.1           | 0.203.0     | Major update |
+| `@opentelemetry/exporter-logs-otlp-http`  | 0.52.1           | 0.203.0     | Major update |
+| `@opentelemetry/exporter-trace-otlp-http` | 0.52.1           | 0.203.0     | Major update |
+| `@opentelemetry/instrumentation`          | 0.52.1           | 0.203.0     | Major update |

package/docs/observability/dashboards.mdx

@@ -0,0 +1,166 @@
+---
+title: "Dashboards"
+description: "Create custom dashboards with real-time metrics powered by TRQL queries."
+---
+
+## Overview
+
+In the Trigger.dev dashboard we have built-in dashboards and you can create your own.
+
+Dashboards are powered by [TRQL queries](/observability/query) with widgets that can be displayed as charts, tables, or single values. They automatically refresh to show the latest data.
+
+### Available metrics data
+
+Trigger.dev automatically collects process metrics (CPU, memory) and Node.js runtime metrics (event loop, heap) for all deployed tasks -- no configuration needed. Requires SDK version **4.4.1 or later**. You can also create custom metrics using the `otel.metrics` API from the SDK.
+
+All of this data is available in the `metrics` table for use in dashboard widgets. See [Logging, tracing & metrics](/logging#metrics) for the full list of automatic metrics and how to create custom ones, or the [Query page](/observability/query#metrics-table-columns) for the `metrics` table schema.
+
+![The built-in Metrics dashboard](/images/metrics-built-in.png)
+
+### Visualization types
+
+- **Line chart** - Show trends over time
+- **Bar chart** - Compare values across categories
+- **Area chart** - Display cumulative trends
+- **Table** - Show detailed data in rows
+- **Single value** - Display a single metric (count, sum, average, etc.)
+
+You can also add Titles to your dashboard.
+
+## Filtering and time ranges
+
+All widgets on a dashboard use the time range filter applied to the dashboard.
+
+You can also filter the data by:
+
+- Scope: Environment, Project, Organization
+- Tasks
+- Queues
+
+## Creating custom dashboards
+
+1. In the sidebar click the + icon next to "Dashboards".
+2. Name your custom dashboard.
+3. From the top-right you can "Add chart" or "Add title".
+4. For charts you write [TRQL queries](/observability/query) and choose a visualization type.
+5. You can resize and reposition widgets on your dashboards.
+
+## Managing dashboards with the SDK
+
+Custom dashboards can also be created and edited from code, so you can keep them in your repository and set them up from CI or a script. `query.dashboards` covers the same operations as the dashboard UI.
+
+```ts scripts/dashboards.ts
+import { query } from "@trigger.dev/sdk";
+
+const dashboard = await query.dashboards.create({
+  title: "Email tasks",
+  widgets: [
+    { title: "Overview", display: { type: "title" } },
+    {
+      title: "Total runs",
+      query: "SELECT count() AS total FROM runs WHERE task_identifier = 'send-email'",
+      display: { type: "bignumber", column: "total", aggregation: "sum" },
+    },
+    {
+      title: "Runs per day",
+      query:
+        "SELECT timeBucket(), count() AS runs FROM runs WHERE task_identifier = 'send-email' GROUP BY timeBucket ORDER BY timeBucket",
+      display: {
+        type: "chart",
+        chartType: "bar",
+        xAxisColumn: "timebucket",
+        yAxisColumns: ["runs"],
+        groupByColumn: null,
+        stacked: false,
+        sortByColumn: null,
+        sortDirection: "asc",
+        aggregation: "sum",
+      },
+    },
+  ],
+});
+
+console.log(dashboard.id); // dashboard_...
+```
+
+Widgets without a `position` are stacked full width in the order you list them. Pass `position: { x, y, w, h }` on a 12-column grid to place a widget yourself.
+
+To keep a dashboard in sync with code, replace all of its widgets in one call. Widgets you keep, matched by `id`, stay where they are unless you pass a new `position`:
+
+```ts scripts/dashboards.ts
+const current = await query.dashboards.retrieve(dashboard.id);
+
+await query.dashboards.replace(dashboard.id, {
+  widgets: [
+    {
+      id: "failures",
+      title: "Failed runs",
+      query: "SELECT count() AS failed FROM runs WHERE status = 'Failed'",
+      display: { type: "bignumber", column: "failed", aggregation: "sum" },
+    },
+  ],
+  revision: current.revision,
+});
+```
+
+`revision` is optional. When you pass the revision you last read, the write fails with a 409 if someone changed the dashboard in the meantime, instead of overwriting their change.
+
+Every widget query is checked against the queryable tables when you save it, so a typo in a table or column name fails the request with the list of valid columns. `query.dashboards.widgets.add`, `widgets.update` and `widgets.del` change one widget at a time. Creating a dashboard or widget past your plan's limits returns a 403. See the [Query API reference](/management/query/create-dashboard) for every endpoint.
+
+## Performance considerations
+
+### Optimize queries for metrics
+
+1. **Use time bucketing** - `timeBucket()` automatically groups by appropriate intervals
+2. **Limit result size** - Add `LIMIT` clauses, especially for table widgets
+3. **Use approximate functions** - `uniq()` instead of `uniqExact()` for faster approximate counts
+
+## Exporting metric data
+
+Export data from any metric widget:
+
+1. Click the widget menu (three dots)
+2. Select "Copy JSON" or "Copy CSV"
+
+## Best practices
+
+1. **Start simple** - Begin with basic metrics and iterate based on insights
+2. **Use meaningful names** - Give widgets clear, descriptive titles
+3. **Group related metrics** - Organize dashboards by theme (performance, costs, errors)
+4. **Test queries first** - Use the Query page to develop and test before adding to dashboards
+
+## Troubleshooting
+
+### Widget shows "No data"
+
+- Check that your query returns results in the Query page
+- Verify time filters include the period with data
+- Ensure task/queue filters match existing runs
+
+### Widget is slow to load
+
+- Add time range filters to your query
+- Use `LIMIT` clauses
+- Simplify aggregations
+- Check query execution time in Query page
+
+### Chart displays incorrectly
+
+- Verify column names match visualization config
+- Check data types (numbers for charts, dates for time series)
+- Ensure `timeBucket()` is used for time-series charts
+- Review that series columns exist in query results
+
+## Limits
+
+Dashboards are powered by Query so have [the same limits](/observability/query#limits) as Query.
+
+There is a separate concurrency limits for metric widgets.
+
+| Limit                     | Details        |
+| :------------------------ | :------------- |
+| Concurrent widget queries | 30 per project |
+| Custom dashboards         | Free 0, Hobby 1, Pro 5 per organization |
+| Widgets per dashboard     | Free 0, Hobby 10, Pro 20 |
+
+See [Limits](/limits) for details.