@trigger.dev/sdk 4.5.0-rc.6 → 4.5.0-rc.7

package/docs/introduction.mdx

@@ -0,0 +1,223 @@
+---
+title: "Welcome to the Trigger.dev docs"
+sidebarTitle: "Introduction"
+description: "Find all the resources and guides you need to get started"
+mode: "center"
+---
+
+<CardGroup cols={2}>
+  <Card title="Quick start" img="/images/intro-quickstart.jpg" href="/quick-start">
+    Get started with Trigger.dev and run your first task in 3 minutes
+  </Card>
+  <Card
+    title="Guides, frameworks & examples"
+    img="/images/intro-examples.jpg"
+    href="/guides/introduction#example-tasks"
+  >
+    Browse our wide range of guides, frameworks and example projects
+  </Card>
+  <Card title="Building with AI" img="/images/intro-ai.jpg" href="/building-with-ai">
+    Learn how to build Trigger.dev projects using AI coding assistants
+  </Card>
+  <Card title="Video walkthrough" img="/images/intro-video.jpg" href="/video-walkthrough">
+    Watch an end-to-end demo of Trigger.dev in 10 minutes
+  </Card>
+</CardGroup>
+
+## What is Trigger.dev?
+
+Trigger.dev is an open source background jobs framework that lets you write reliable workflows in plain async code. Run long-running AI tasks, handle complex background jobs, and build AI agents with built-in queuing, automatic retries, and real-time monitoring. No timeouts, elastic scaling, and zero infrastructure management required.
+
+We provide everything you need to build and manage background tasks: a CLI and SDK for writing tasks in your existing codebase, support for both [regular](/tasks/overview) and [scheduled](/tasks/scheduled) tasks, full observability through our dashboard, and a [Realtime API](/realtime) with [React hooks](/realtime/react-hooks#realtime-hooks) for showing task status in your frontend. You can use [Trigger.dev Cloud](https://cloud.trigger.dev) or [self-host](/self-hosting/overview) on your own infrastructure.
+
+## Learn the concepts
+
+<CardGroup cols={2}>
+  <Card title="Writing tasks" icon="wand-magic-sparkles" href="/tasks/overview" color="#3B82F6">
+    Tasks are the core of Trigger.dev. Learn what they are and how to write them.
+  </Card>
+  <Card title="Triggering tasks" icon="bullseye-pointer" href="/triggering" color="#fbbf24">
+    Learn how to trigger tasks from your codebase.
+  </Card>
+  <Card title="Runs" icon="person-running" href="/runs" color="#EA189E">
+    Runs are the instances of tasks that are executed. Learn how they work.
+  </Card>
+  <Card title="API keys" icon="key" href="/apikeys" color="#EAEA08">
+    API keys are used to authenticate requests to the Trigger.dev API. Learn how to create and use
+    them.
+  </Card>
+</CardGroup>
+
+## Explore by feature
+
+<CardGroup>
+  <Card title="Scheduled tasks (cron)" icon="clock" href="/tasks/scheduled" color="#EAEA08">
+    Scheduled tasks are a type of task that is scheduled to run at a specific time.
+  </Card>
+  <Card title="Realtime API" icon="loader" href="/realtime" color="#22C55E">
+    The Realtime API allows you to trigger tasks and get the status of runs.
+  </Card>
+  <Card title="React hooks" icon="react" href="/realtime/react-hooks" color="#3B82F6">
+    React hooks are a way to show task status in your frontend.
+  </Card>
+  <Card title="Waits" icon="calendar-clock" href="/wait" color="#F59E0B">
+    Waits are a way to wait for a task to finish before continuing.
+  </Card>
+  <Card
+    title="Errors and retries"
+    icon="message-exclamation"
+    href="/errors-retrying"
+    color="#F43F5E"
+  >
+    Learn how to handle errors and retries.
+  </Card>
+  <Card title="Concurrency & Queues" icon="line-height" href="/queue-concurrency" color="#D946EF">
+    Configure what you want to happen when there is more than one run at a time.
+  </Card>
+  <Card
+    title="Wait for token (human-in-the-loop)"
+    icon="hand"
+    href="/wait-for-token"
+    color="#EAEA08"
+  >
+    Pause runs until a token is completed via an approval workflow.
+  </Card>
+  <Card title="Build extensions" icon="gear" href="/config/extensions/overview" color="#22C55E">
+    Customize the build process or the resulting bundle and container image.
+  </Card>
+</CardGroup>
+
+## Explore by build extension
+
+| Extension             | What it does                                                 | Docs                                                   |
+| :-------------------- | :----------------------------------------------------------- | :----------------------------------------------------- |
+| prismaExtension       | Use Prisma with Trigger.dev                                  | [Learn more](/config/extensions/prismaExtension)       |
+| pythonExtension       | Execute Python scripts in Trigger.dev                        | [Learn more](/config/extensions/pythonExtension)       |
+| playwright            | Use Playwright with Trigger.dev                              | [Learn more](/config/extensions/playwright)            |
+| puppeteer             | Use Puppeteer with Trigger.dev                               | [Learn more](/config/extensions/puppeteer)             |
+| lightpanda            | Use Lightpanda with Trigger.dev                              | [Learn more](/config/extensions/lightpanda)            |
+| ffmpeg                | Use FFmpeg with Trigger.dev                                  | [Learn more](/config/extensions/ffmpeg)                |
+| aptGet                | Install system packages with aptGet                          | [Learn more](/config/extensions/aptGet)                |
+| additionalFiles       | Copy additional files to the build directory                 | [Learn more](/config/extensions/additionalFiles)       |
+| additionalPackages    | Include additional packages in the build                     | [Learn more](/config/extensions/additionalPackages)    |
+| syncEnvVars           | Automatically sync environment variables to Trigger.dev      | [Learn more](/config/extensions/syncEnvVars)           |
+| esbuildPlugin         | Add existing or custom esbuild plugins to your build process | [Learn more](/config/extensions/esbuildPlugin)         |
+| emitDecoratorMetadata | Support for the emitDecoratorMetadata TypeScript compiler    | [Learn more](/config/extensions/emitDecoratorMetadata) |
+| audioWaveform         | Support for Audio Waveform in your project                   | [Learn more](/config/extensions/audioWaveform)         |
+
+## Explore by example
+
+<CardGroup cols={3}>
+  <Card
+    title="FFmpeg"
+    img="/images/intro-ffmpeg.jpg"
+    href="/guides/examples/ffmpeg-video-processing"
+  />
+  <Card
+    title="Fal.ai"
+    img="/images/intro-fal.jpg"
+    href="/guides/examples/fal-ai-image-to-cartoon"
+  />
+  <Card title="Puppeteer" img="/images/intro-puppeteer.jpg" href="/guides/examples/puppeteer" />
+  <Card
+    title="LibreOffice"
+    img="/images/intro-libreoffice.jpg"
+    href="/guides/examples/libreoffice-pdf-conversion"
+  />
+  <Card
+    title="OpenAI"
+    img="/images/intro-openai.jpg"
+    href="/guides/examples/open-ai-with-retrying"
+  />
+  <Card
+    title="Browserbase"
+    img="/images/intro-browserbase.jpg"
+    href="/guides/examples/scrape-hacker-news"
+  />
+  <Card
+    title="Sentry"
+    img="/images/intro-sentry.jpg"
+    href="/guides/examples/sentry-error-tracking"
+  />
+  <Card
+    title="Resend"
+    img="/images/intro-resend.jpg"
+    href="/guides/examples/resend-email-sequence"
+  />
+  <Card
+    title="Vercel AI SDK"
+    img="/images/intro-vercel.jpg"
+    href="/guides/examples/vercel-ai-sdk"
+  />
+  <Card
+    title="Sharp"
+    img="/images/intro-sharp.jpg"
+    href="/guides/examples/sharp-image-processing"
+  />
+  <Card
+    title="Deepgram"
+    img="/images/intro-deepgram.jpg"
+    href="/guides/examples/deepgram-transcribe-audio"
+  />
+  <Card
+    title="Supabase"
+    img="/images/intro-supabase.jpg"
+    href="/guides/examples/supabase-database-operations"
+  />
+  <Card
+    title="DALL•E"
+    img="/images/intro-openai.jpg"
+    href="/guides/examples/dall-e3-generate-image"
+  />
+  <Card
+    title="Firecrawl"
+    img="/images/intro-firecrawl.jpg"
+    href="/guides/examples/firecrawl-url-crawl"
+  />
+  <Card title="Lightpanda" img="/images/intro-lightpanda.jpg" href="/guides/examples/lightpanda" />
+</CardGroup>
+
+## Getting help
+
+We'd love to hear from you or give you a hand getting started. Here are some ways to get in touch with us.
+
+<CardGroup>
+  <Card
+    title="Join our Discord server"
+    icon="discord"
+    href="https://discord.gg/kA47vcd8P6"
+    color="#5865F2"
+  >
+    Our Discord is the best place to get help with any questions about Trigger.dev.
+  </Card>
+  <Card
+    title="Follow us on X (Twitter)"
+    icon={
+      <svg xmlns="http://www.w3.org/2000/svg" height="20" viewBox="0 0 512 512">
+        <path d="M389.2 48h70.6L305.6 224.2 487 464H345L233.7 318.6 106.5 464H35.8L200.7 275.5 26.8 48H172.4L272.9 180.9 389.2 48zM364.4 421.8h39.1L151.1 88h-42L364.4 421.8z" />
+      </svg>
+    }
+    href="https://twitter.com/triggerdotdev"
+    color="#1DA1F2"
+  >
+    Follow us to get the latest updates and news.
+  </Card>
+  <Card
+    title="Schedule a call"
+    icon="phone"
+    iconType="solid"
+    color="#22C55E"
+    href="https://cal.com/team/triggerdotdev/founders-call"
+  >
+    Arrange a call with one of the founders to get help with any questions.
+  </Card>
+  <Card
+    title="Give us a star on GitHub"
+    icon="star"
+    iconType="solid"
+    href="https://github.com/triggerdotdev/trigger.dev"
+    color="#fbbf24"
+  >
+    Check us out our GitHub repo and give us a star if you like what we're doing.
+  </Card>
+</CardGroup>

package/docs/limits.mdx

@@ -0,0 +1,241 @@
+---
+title: "Limits"
+description: "There are some hard and soft limits that you might hit."
+---
+
+import RateLimitHitUseBatchTrigger from "/snippets/rate-limit-hit-use-batchtrigger.mdx";
+
+You can view your current limits, quotas, and rate limit usage in real-time by visiting the **Limits** page in the dashboard (accessible from the left sidebar). This page shows current rate limit token availability, quota usage, and plan features for your organization.
+
+## Concurrency limits
+
+| Pricing tier | Limit                |
+| :----------- | :------------------- |
+| Free         | 10 concurrent runs   |
+| Hobby        | 25 concurrent runs   |
+| Pro          | 100+ concurrent runs |
+
+Extra concurrency above the Pro tier limit is available via the dashboard. Click the "Concurrency" page from the left sidebar when on the Pro plan to purchase more.
+
+## Rate limits
+
+Generally speaking each SDK call is an API call.
+
+| Limit | Details                   |
+| :---- | :------------------------ |
+| API   | 1,500 requests per minute |
+
+You can request a higher rate limit from us if you're on a paid plan.
+
+<RateLimitHitUseBatchTrigger />
+
+## Queued tasks
+
+The maximum number of runs that can be queued **per queue** (not across all queues in the environment). Each queue can hold up to its limit independently. When a queue hits its limit, new triggers to that queue are rejected.
+
+<Note>
+  The limits below apply to [Trigger.dev Cloud](https://trigger.dev). If you self-host Trigger.dev, queue size limits are configurable via the `MAXIMUM_DEV_QUEUE_SIZE` and `MAXIMUM_DEPLOYED_QUEUE_SIZE` environment variables — see [Self-hosting environment variables](/self-hosting/env/webapp#run-engine).
+</Note>
+
+| Pricing tier | Development (per queue) | Staging / Production (per queue) |
+| :----------- | :---------------------- | :-------------------------------- |
+| Free         | 500                     | 10,000                            |
+| Hobby        | 500                     | 250,000                           |
+| Pro          | 5,000                   | 1,000,000                         |
+
+## Maximum run TTL
+
+On Trigger.dev Cloud, all runs have an enforced maximum TTL of 14 days. Runs without an explicit TTL automatically receive the 14-day TTL; runs with a TTL longer than 14 days are clamped to 14 days. This prevents queued runs from accumulating indefinitely. If you self-host, you can configure a maximum TTL via the `RUN_ENGINE_DEFAULT_MAX_TTL` environment variable — see [Self-hosting environment variables](/self-hosting/env/webapp#run-engine).
+
+## Schedules
+
+| Pricing tier | Limit              |
+| :----------- | :----------------- |
+| Free         | 10 per project     |
+| Hobby        | 100 per project    |
+| Pro          | 1,000+ per project |
+
+Additional bundles above the Pro tier are available for $10/month per 1,000 schedules. Contact us via [email](https://trigger.dev/contact) or [Discord](https://trigger.dev/discord) to request more.
+
+When attaching schedules to tasks we strongly recommend you add them [in our dashboard](/tasks/scheduled#attaching-schedules-in-the-dashboard) if they're "static". That way you can control them easily per environment.
+
+If you add them [dynamically using code](/management/schedules/create) make sure you add a `deduplicationKey` so you don't add the same schedule to a task multiple times. If you don't your task will get triggered multiple times, it will cost you more, and you will hit the limit.
+
+If you're creating schedules for your user you will definitely need to request more schedules from us.
+
+## Projects
+
+| Pricing tier | Limit               |
+| :----------- | :------------------ |
+| All tiers    | 10 per organization |
+
+Each project receives its own concurrency allocation. If you need to support multiple tenants with the same codebase but different environment variables, see the [Multi-tenant applications](/deploy-environment-variables#multi-tenant-applications) section for a recommended workaround.
+
+## Preview branches
+
+| Pricing tier | Limit                |
+| :----------- | :------------------- |
+| Free         | Not available        |
+| Hobby        | 5 preview branches   |
+| Pro          | 20+ preview branches |
+
+Additional bundles above the Pro tier are available for $10/month per preview branch. Contact us via [email](https://trigger.dev/contact) or [Discord](https://trigger.dev/discord) to request more.
+
+## Realtime connections
+
+| Pricing tier | Limit                       |
+| :----------- | :-------------------------- |
+| Free         | 10 concurrent connections   |
+| Hobby        | 50 concurrent connections   |
+| Pro          | 500+ concurrent connections |
+
+Additional bundles are available for $10/month per 100 concurrent connections. Contact us via [email](https://trigger.dev/contact) or [Discord](https://trigger.dev/discord) to request more.
+
+## Task payloads and outputs
+
+| Limit                  | Details                                                            |
+| :--------------------- | :----------------------------------------------------------------- |
+| Single trigger payload | Must not exceed 3MB                                                |
+| Batch trigger payload  | Each item can be up to 3MB (SDK 4.3.1+). Prior: 1MB total combined |
+| Task outputs           | Must not exceed 10MB                                               |
+
+Payloads and outputs that exceed 512KB will be offloaded to object storage and a presigned URL will be provided to download the data when calling `runs.retrieve`. You don't need to do anything to handle this in your tasks however, as we will transparently upload/download these during operation.
+
+## Batch size
+
+A single batch can have a maximum of 1,000 items with SDK 4.3.1+. Prior versions are limited to 500 items.
+
+<SoftLimit />
+
+## Batch trigger rate limits
+
+Batch triggering uses a token bucket algorithm to rate limit the number of runs you can trigger per environment. Each run in a batch consumes one token.
+
+| Pricing tier | Bucket size | Refill rate           |
+| :----------- | :---------- | :-------------------- |
+| Free         | 1,200 runs  | 100 runs every 10 sec |
+| Hobby        | 5,000 runs  | 500 runs every 5 sec  |
+| Pro          | 5,000 runs  | 500 runs every 5 sec  |
+
+**How it works**: You can burst up to your bucket size, then tokens refill at the specified rate. For example, a Free user can trigger 1,200 runs immediately, then must wait for tokens to refill (100 runs become available every 10 seconds).
+
+<Note>
+  When you hit batch rate limits, the SDK throws a `BatchTriggerError` with `isRateLimited: true`.
+  See [Handling batch trigger errors](/triggering#handling-batch-trigger-errors) for how to detect
+  and react to rate limits in your code.
+</Note>
+
+## Batch trigger processing concurrency
+
+When you send a batch trigger, we convert it into individual runs. This limit controls the maximum number of batches being converted into runs simultaneously per environment. It is not a limit on how many batch runs can be executing at once.
+
+| Pricing tier | Limit                 |
+| :----------- | :-------------------- |
+| Free         | 5 concurrent batches  |
+| Hobby        | 10 concurrent batches |
+| Pro          | 50 concurrent batches |
+
+## Log retention
+
+| Pricing tier | Limit   |
+| :----------- | :------ |
+| Free         | 1 day   |
+| Hobby        | 7 days  |
+| Pro          | 30 days |
+
+## Log size
+
+We limit the size of logs to prevent oversized data potentially causing issues.
+
+<Expandable title="log limits">
+
+#### Attribute Limits
+
+- Span Attribute Count Limit: 256
+- Log Attribute Count Limit: 256
+- Span Attribute Value Length Limit: 131072 characters
+- Log Attribute Value Length Limit: 131072 characters
+
+#### Event and Link Limits
+
+- Span Event Count Limit: 10
+- Link Count Limit: 2
+- Attributes per Link Limit: 10
+- Attributes per Event Limit: 10
+
+#### I/O Packet Length Limit
+
+128 KB (131,072 bytes)
+
+#### Attribute Clipping Behavior
+
+- Attributes exceeding the value length limit (1028 characters) are discarded.
+- If the total number of attributes exceeds 256, additional attributes are not included.
+
+#### Attribute Value Size Calculation
+
+- Strings: Actual length of the string
+- Numbers: 8 bytes
+- Booleans: 4 bytes
+- Arrays: Sum of the sizes of all elements
+- Undefined or null: 0 bytes
+
+</Expandable>
+
+## Alerts
+
+An alert destination is a single email address, Slack channel, or webhook URL that you want to send alerts to.
+
+| Pricing tier | Limit                   |
+| :----------- | :---------------------- |
+| Free         | 1 alert destination     |
+| Hobby        | 3 alert destinations    |
+| Pro          | 100+ alert destinations |
+
+If you're on the Pro plan and need more than the plan limit, you can request more by contacting us via [email](https://trigger.dev/contact) or [Discord](https://trigger.dev/discord).
+
+## Query
+
+Query execution is subject to the following limits:
+
+| Limit              | Details               |
+| :----------------- | :-------------------- |
+| Max execution time | 10 seconds per query  |
+| Max result rows    | 10,000 rows per query |
+| Concurrent queries | 3 per project         |
+
+### Query lookback period
+
+The maximum time range a query can look back is based on your plan:
+
+| Pricing tier | Limit   |
+| :----------- | :------ |
+| Free         | 1 day   |
+| Hobby        | 7 days  |
+| Pro          | 30 days |
+
+If your query's time range exceeds your plan's lookback limit, it will be automatically clipped to the maximum allowed period.
+
+## Metric widget concurrency
+
+The number of metric widgets that can be queried concurrently per project.
+
+| Limit                     | Details        |
+| :------------------------ | :------------- |
+| Concurrent widget queries | 30 per project |
+
+## Machines
+
+The default machine is `small-1x` which has 0.5 vCPU and 0.5 GB of RAM. You can optionally configure a higher spec machine which will increase the cost of running the task but can also improve the performance of the task if it is CPU or memory bound.
+
+See the [machine configurations](/machines#machine-configurations) for more details.
+
+## Team members
+
+| Pricing tier | Limit            |
+| :----------- | :--------------- |
+| Free         | 5 team members   |
+| Hobby        | 5 team members   |
+| Pro          | 25+ team members |
+
+Additional seats are available for $20/month per seat. Contact us via [email](https://trigger.dev/contact) or [Discord](https://trigger.dev/discord) to request more.

package/docs/logging.mdx

@@ -0,0 +1,195 @@
+---
+title: "Logging, tracing & metrics"
+description: "How to use the built-in logging, tracing, and metrics system."
+---
+
+![The run log](/images/run-log.png)
+
+The run log shows you exactly what happened in every run of your tasks. It is comprised of logs, traces and spans.
+
+## Logs
+
+You can use `console.log()`, `console.error()`, etc as normal and they will be shown in your run log. This is the standard function so you can use it as you would in any other JavaScript or TypeScript code. Logs from any functions/packages will also be shown.
+
+### logger
+
+We recommend that you use our `logger` object which creates structured logs. Structured logs will make it easier for you to search the logs to quickly find runs.
+
+```ts /trigger/logging.ts
+import { task, logger } from "@trigger.dev/sdk";
+
+export const loggingExample = task({
+  id: "logging-example",
+  run: async (payload: { data: Record<string, string> }) => {
+    //the first parameter is the message, the second parameter must be a key-value object (Record<string, unknown>)
+    logger.debug("Debug message", payload.data);
+    logger.log("Log message", payload.data);
+    logger.info("Info message", payload.data);
+    logger.warn("You've been warned", payload.data);
+    logger.error("Error message", payload.data);
+  },
+});
+```
+
+## Tracing and spans
+
+Tracing is a way to follow the flow of your code. It's very useful for debugging and understanding how your code is working, especially with long-running or complex tasks.
+
+Trigger.dev uses OpenTelemetry tracing under the hood. With automatic tracing for many things like task triggering, task attempts, HTTP requests, and more.
+
+| Name          | Description                      |
+| :------------ | :------------------------------- |
+| Task triggers | Task triggers                    |
+| Task attempts | Task attempts                    |
+| HTTP requests | HTTP requests made by your code. |
+
+### Adding instrumentations
+
+![The run log](/images/auto-instrumentation.png)
+
+You can [add instrumentations](/config/config-file#instrumentations). The Prisma one above will automatically trace all Prisma queries.
+
+### Add custom traces
+
+If you want to add custom traces to your code, you can use the `logger.trace` function. It will create a new OTEL trace and you can set attributes on it.
+
+```ts
+import { logger, task } from "@trigger.dev/sdk";
+
+export const customTrace = task({
+  id: "custom-trace",
+  run: async (payload) => {
+    //you can wrap code in a trace, and set attributes
+    const user = await logger.trace("fetch-user", async (span) => {
+      span.setAttribute("user.id", "1");
+
+      //...do stuff
+
+      //you can return a value
+      return {
+        id: "1",
+        name: "John Doe",
+        fetchedAt: new Date(),
+      };
+    });
+
+    const usersName = user.name;
+  },
+});
+```
+
+## Metrics
+
+Trigger.dev collects system and runtime metrics automatically for deployed tasks, and provides an API for recording custom metrics using OpenTelemetry.
+
+You can view metrics in the [Dashboards](/observability/dashboards), query them with [TRQL](/observability/query), and export them to external services via [telemetry exporters](/config/config-file#telemetry-exporters).
+
+### Custom metrics API
+
+Import `otel` from `@trigger.dev/sdk` and use the standard OpenTelemetry Metrics API to create custom instruments.
+
+Create instruments **at module level** (outside the task `run` function) so they are reused across runs:
+
+```ts /trigger/metrics.ts
+import { task, logger, otel } from "@trigger.dev/sdk";
+
+// Create a meter — instruments are created once at module level
+const meter = otel.metrics.getMeter("my-app");
+
+const itemsProcessed = meter.createCounter("items.processed", {
+  description: "Total number of items processed",
+  unit: "items",
+});
+
+const itemDuration = meter.createHistogram("item.duration", {
+  description: "Time spent processing each item",
+  unit: "ms",
+});
+
+const queueDepth = meter.createUpDownCounter("queue.depth", {
+  description: "Current queue depth",
+  unit: "items",
+});
+
+export const processQueue = task({
+  id: "process-queue",
+  run: async (payload: { items: string[] }) => {
+    queueDepth.add(payload.items.length);
+
+    for (const item of payload.items) {
+      const start = performance.now();
+
+      // ... process item ...
+
+      const elapsed = performance.now() - start;
+
+      itemsProcessed.add(1, { "item.type": "order" });
+      itemDuration.record(elapsed, { "item.type": "order" });
+      queueDepth.add(-1);
+    }
+
+    logger.info("Queue processed", { count: payload.items.length });
+  },
+});
+```
+
+#### Available instrument types
+
+| Instrument | Method | Use case |
+| :--- | :--- | :--- |
+| Counter | `meter.createCounter()` | Monotonically increasing values (items processed, requests sent) |
+| Histogram | `meter.createHistogram()` | Distributions of values (durations, sizes) |
+| UpDownCounter | `meter.createUpDownCounter()` | Values that go up and down (queue depth, active connections) |
+
+All instruments accept optional attributes when recording values. Attributes let you break down metrics by dimension (e.g., by item type, status, or region).
+
+### Automatic system and runtime metrics
+
+Trigger.dev automatically collects the following metrics for deployed tasks. No configuration is needed. Requires SDK version **4.4.1 or later**.
+
+| Metric name | Type | Unit | Description |
+| :--- | :--- | :--- | :--- |
+| `process.cpu.utilization` | gauge | ratio | Process CPU usage (0-1) |
+| `process.cpu.time` | counter | seconds | CPU time consumed |
+| `process.memory.usage` | gauge | bytes | Process memory usage |
+| `nodejs.event_loop.utilization` | gauge | ratio | Event loop utilization (0-1) |
+| `nodejs.event_loop.delay.p95` | gauge | seconds | Event loop delay p95 |
+| `nodejs.event_loop.delay.max` | gauge | seconds | Event loop delay max |
+| `nodejs.heap.used` | gauge | bytes | V8 heap used |
+| `nodejs.heap.total` | gauge | bytes | V8 heap total |
+
+<Note>
+In dev mode (`trigger dev`), only `process.*` and custom metrics are available.
+</Note>
+
+### Context attributes
+
+All metrics (both automatic and custom) are tagged with run context so you can filter and group them:
+
+- `run_id` — the run that produced the metric
+- `task_identifier` — the task slug
+- `attempt_number` — the attempt number
+- `machine_name` — the machine preset (e.g., `small-1x`)
+- `worker_version` — the deployed worker version
+- `environment_type` — `PRODUCTION`, `STAGING`, `DEVELOPMENT`, or `PREVIEW`
+
+### Querying metrics
+
+Use [TRQL](/observability/query) to query metrics data. For example, to see average CPU utilization over time:
+
+```sql
+SELECT
+  timeBucket(),
+  avg(value) AS avg_cpu
+FROM metrics
+WHERE metric_name = 'process.cpu.utilization'
+GROUP BY timeBucket
+ORDER BY timeBucket
+LIMIT 1000
+```
+
+See the [Query page](/observability/query#metrics-table-columns) for the full `metrics` table schema.
+
+### Exporting metrics
+
+You can send metrics to external observability services (Axiom, Honeycomb, Datadog, etc.) by configuring [telemetry exporters](/config/config-file#telemetry-exporters) in your `trigger.config.ts`.