Skip to content

Commit c9f7ea8

Browse files
samejrsamejr
authored
Docs/various docs improvements (#1716)
* Adds more Prisma documentation * Adds more info and a diagram to improve idempotencyKeyTTLs * Adds more clarity to the run with TTL docs section * Limits page copy improvements * Adds schema properties to the alert webhooks
1 parent d6c869e commit c9f7ea8

File tree

6 files changed

+321
-5
lines changed

6 files changed

+321
-5
lines changed

‎docs/config/config-file.mdx

+20-3
Original file line numberDiff line numberDiff line change
@@ -397,10 +397,12 @@ This is usually required if you are using certain ORMs, like TypeORM, that requi
397397

398398
If you are using Prisma, you should use the prisma build extension.
399399

400-
- Automatically handles copying prisma files to the build directory.
401-
- Generates the prisma client during the deploy process
400+
- Automatically handles copying Prisma files to the build directory
401+
- Generates the Prisma client during the deploy process
402402
- Optionally will migrate the database during the deploy process
403-
- Support for TypedSQL and multiple schema files.
403+
- Support for TypedSQL and multiple schema files
404+
- You can use `prismaSchemaFolder` to specify just the directory containing your schema file, instead of the full path
405+
- You can add the extension twice if you have multiple separate schemas in the same project (example below)
404406

405407
You can use it for a simple Prisma setup like this:
406408

@@ -522,6 +524,21 @@ These environment variables are only used during the build process and are not e
522524

523525
</Note>
524526

527+
If you have multiple separate schemas in the same project you can add the extension multiple times:
528+
529+
```ts
530+
prismaExtension({
531+
schema: 'prisma/schema/main.prisma',
532+
version: '6.2.0',
533+
migrate: false,
534+
}),
535+
prismaExtension({
536+
schema: 'prisma/schema/secondary.prisma',
537+
version: '6.2.0',
538+
migrate: false,
539+
}),
540+
```
541+
525542
#### syncEnvVars
526543

527544
The `syncEnvVars` build extension replaces the deprecated `resolveEnvVars` export. Check out our [syncEnvVars documentation](/deploy-environment-variables#sync-env-vars-from-another-service) for more information.

‎docs/idempotency.mdx

+8
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,14 @@ await tasks.batchTrigger("my-task", [
9494

9595
## `idempotencyKeyTTL` option
9696

97+
The `idempotencyKeyTTL` option defines a time window during which a task with the same idempotency key will only run once. Here's how it works:
98+
99+
1. When you trigger a task with an idempotency key and set `idempotencyKeyTTL: "5m"`, it creates a 5-minute window.
100+
2. During this window, any subsequent triggers with the same idempotency key will return the original task run instead of creating a new one.
101+
3. Once the TTL window expires, the next trigger with that idempotency key will create a new task run and start a new time window.
102+
103+
![idempotency-key-ttl](/images/idempotency-key-ttl.png)
104+
97105
By default idempotency keys are stored for 30 days. You can change this by passing the `idempotencyKeyTTL` option when triggering a task:
98106

99107
```ts

‎docs/images/idempotency-key-ttl.png

38.1 KB
Loading

‎docs/limits.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ We limit the size of logs to prevent oversized data potentially causing issues.
114114

115115
## Alerts
116116

117-
An alert destination is a single email address, Slack channel, or webhook URL that you want to send alerts to. If you're on the Pro and need more than 100 alert destinations, you can request more by contacting us via [email](https://trigger.dev/contact) or [Discord](https://trigger.dev/discord).
117+
An alert destination is a single email address, Slack channel, or webhook URL that you want to send alerts to. 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).
118118

119119
| Pricing tier | Limit |
120120
| :----------- | :---------------------- |

‎docs/runs.mdx

+3-1
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,9 @@ You can set a TTL when triggering a run:
133133
await yourTask.trigger({ foo: "bar" }, { ttl: "10m" });
134134
```
135135

136-
If the run hasn't started within the specified TTL, it will automatically expire. This is useful for time-sensitive tasks. Note that dev runs automatically have a 10-minute TTL.
136+
If the run hasn't started within the specified TTL, it will automatically expire, returning the status `Expired`. This is useful for time-sensitive tasks where immediate execution is important. For example, when you queue many runs simultaneously and exceed your concurrency limits, some runs might be delayed - using TTL ensures they only execute if they can start within your specified timeframe.
137+
138+
Note that dev runs automatically have a 10-minute TTL. In Staging and Production environments, no TTL is set by default.
137139

138140
![Run with TTL](/images/run-with-ttl.png)
139141

‎docs/troubleshooting-alerts.mdx

+289
Original file line numberDiff line numberDiff line change
@@ -94,3 +94,292 @@ export async function action({ request }: ActionFunctionArgs) {
9494
}
9595
}
9696
```
97+
98+
### Common properties
99+
100+
When you create a webhook alert, you'll receive different payloads depending on the type of alert. All webhooks share some common properties:
101+
102+
<ParamField path="id" type="string">
103+
A unique identifier for this webhook event
104+
</ParamField>
105+
106+
<ParamField path="created" type="datetime">
107+
When this webhook event was created
108+
</ParamField>
109+
110+
<ParamField path="webhookVersion" type="string">
111+
The version of the webhook payload format
112+
</ParamField>
113+
114+
<ParamField path="type" type="string">
115+
The type of alert webhook. One of: `alert.run.failed`, `alert.deployment.success`, or `alert.deployment.failed`
116+
</ParamField>
117+
118+
### Run Failed Alert
119+
120+
This webhook is sent when a run fails. The payload is available on the `object` property:
121+
122+
<ParamField path="object.task.id" type="string">
123+
Unique identifier for the task
124+
</ParamField>
125+
126+
<ParamField path="object.task.filePath" type="string">
127+
File path where the task is defined
128+
</ParamField>
129+
130+
<ParamField path="object.task.exportName" type="string">
131+
Name of the exported task function
132+
</ParamField>
133+
134+
<ParamField path="object.task.version" type="string">
135+
Version of the task
136+
</ParamField>
137+
138+
<ParamField path="object.task.sdkVersion" type="string">
139+
Version of the SDK used
140+
</ParamField>
141+
142+
<ParamField path="object.task.cliVersion" type="string">
143+
Version of the CLI used
144+
</ParamField>
145+
146+
<ParamField path="object.run.id" type="string">
147+
Unique identifier for the run
148+
</ParamField>
149+
150+
<ParamField path="object.run.number" type="number">
151+
Run number
152+
</ParamField>
153+
154+
<ParamField path="object.run.status" type="string">
155+
Current status of the run
156+
</ParamField>
157+
158+
<ParamField path="object.run.createdAt" type="datetime">
159+
When the run was created
160+
</ParamField>
161+
162+
<ParamField path="object.run.startedAt" type="datetime">
163+
When the run started executing
164+
</ParamField>
165+
166+
<ParamField path="object.run.completedAt" type="datetime">
167+
When the run finished executing
168+
</ParamField>
169+
170+
<ParamField path="object.run.isTest" type="boolean">
171+
Whether this is a test run
172+
</ParamField>
173+
174+
<ParamField path="object.run.idempotencyKey" type="string">
175+
Idempotency key for the run
176+
</ParamField>
177+
178+
<ParamField path="object.run.tags" type="string[]">
179+
Associated tags
180+
</ParamField>
181+
182+
<ParamField path="object.run.error" type="object">
183+
Error information
184+
</ParamField>
185+
186+
<ParamField path="object.run.isOutOfMemoryError" type="boolean">
187+
Whether the run was an out-of-memory error
188+
</ParamField>
189+
190+
<ParamField path="object.run.machine" type="string">
191+
Machine preset used for the run
192+
</ParamField>
193+
194+
<ParamField path="object.run.dashboardUrl" type="string">
195+
URL to view the run in the dashboard
196+
</ParamField>
197+
198+
<ParamField path="object.environment.id" type="string">
199+
Environment ID
200+
</ParamField>
201+
202+
<ParamField path="object.environment.type" type="string">
203+
Environment type (STAGING or PRODUCTION)
204+
</ParamField>
205+
206+
<ParamField path="object.environment.slug" type="string">
207+
Environment slug
208+
</ParamField>
209+
210+
<ParamField path="object.organization.id" type="string">
211+
Organization ID
212+
</ParamField>
213+
214+
<ParamField path="object.organization.slug" type="string">
215+
Organization slug
216+
</ParamField>
217+
218+
<ParamField path="object.organization.name" type="string">
219+
Organization name
220+
</ParamField>
221+
222+
<ParamField path="object.project.id" type="string">
223+
Project ID
224+
</ParamField>
225+
226+
<ParamField path="object.project.ref" type="string">
227+
Project reference
228+
</ParamField>
229+
230+
<ParamField path="object.project.slug" type="string">
231+
Project slug
232+
</ParamField>
233+
234+
<ParamField path="object.project.name" type="string">
235+
Project name
236+
</ParamField>
237+
238+
### Deployment Success Alert
239+
240+
This webhook is sent when a deployment succeeds. The payload is available on the `object` property:
241+
242+
<ParamField path="object.deployment.id" type="string">
243+
Deployment ID
244+
</ParamField>
245+
246+
<ParamField path="object.deployment.status" type="string">
247+
Deployment status
248+
</ParamField>
249+
250+
<ParamField path="object.deployment.version" type="string">
251+
Deployment version
252+
</ParamField>
253+
254+
<ParamField path="object.deployment.shortCode" type="string">
255+
Short code identifier
256+
</ParamField>
257+
258+
<ParamField path="object.deployment.deployedAt" type="datetime">
259+
When the deployment completed
260+
</ParamField>
261+
262+
<ParamField path="object.tasks" type="array">
263+
Array of deployed tasks with properties: id, filePath, exportName, and triggerSource
264+
</ParamField>
265+
266+
<ParamField path="object.environment.id" type="string">
267+
Environment ID
268+
</ParamField>
269+
270+
<ParamField path="object.environment.type" type="string">
271+
Environment type (STAGING or PRODUCTION)
272+
</ParamField>
273+
274+
<ParamField path="object.environment.slug" type="string">
275+
Environment slug
276+
</ParamField>
277+
278+
<ParamField path="object.organization.id" type="string">
279+
Organization ID
280+
</ParamField>
281+
282+
<ParamField path="object.organization.slug" type="string">
283+
Organization slug
284+
</ParamField>
285+
286+
<ParamField path="object.organization.name" type="string">
287+
Organization name
288+
</ParamField>
289+
290+
<ParamField path="object.project.id" type="string">
291+
Project ID
292+
</ParamField>
293+
294+
<ParamField path="object.project.ref" type="string">
295+
Project reference
296+
</ParamField>
297+
298+
<ParamField path="object.project.slug" type="string">
299+
Project slug
300+
</ParamField>
301+
302+
<ParamField path="object.project.name" type="string">
303+
Project name
304+
</ParamField>
305+
306+
### Deployment Failed Alert
307+
308+
This webhook is sent when a deployment fails. The payload is available on the `object` property:
309+
310+
<ParamField path="object.deployment.id" type="string">
311+
Deployment ID
312+
</ParamField>
313+
314+
<ParamField path="object.deployment.status" type="string">
315+
Deployment status
316+
</ParamField>
317+
318+
<ParamField path="object.deployment.version" type="string">
319+
Deployment version
320+
</ParamField>
321+
322+
<ParamField path="object.deployment.shortCode" type="string">
323+
Short code identifier
324+
</ParamField>
325+
326+
<ParamField path="object.deployment.failedAt" type="datetime">
327+
When the deployment failed
328+
</ParamField>
329+
330+
<ParamField path="object.error.name" type="string">
331+
Error name
332+
</ParamField>
333+
334+
<ParamField path="object.error.message" type="string">
335+
Error message
336+
</ParamField>
337+
338+
<ParamField path="object.error.stack" type="string">
339+
Error stack trace (optional)
340+
</ParamField>
341+
342+
<ParamField path="object.error.stderr" type="string">
343+
Standard error output (optional)
344+
</ParamField>
345+
346+
<ParamField path="object.environment.id" type="string">
347+
Environment ID
348+
</ParamField>
349+
350+
<ParamField path="object.environment.type" type="string">
351+
Environment type (STAGING or PRODUCTION)
352+
</ParamField>
353+
354+
<ParamField path="object.environment.slug" type="string">
355+
Environment slug
356+
</ParamField>
357+
358+
<ParamField path="object.organization.id" type="string">
359+
Organization ID
360+
</ParamField>
361+
362+
<ParamField path="object.organization.slug" type="string">
363+
Organization slug
364+
</ParamField>
365+
366+
<ParamField path="object.organization.name" type="string">
367+
Organization name
368+
</ParamField>
369+
370+
<ParamField path="object.project.id" type="string">
371+
Project ID
372+
</ParamField>
373+
374+
<ParamField path="object.project.ref" type="string">
375+
Project reference
376+
</ParamField>
377+
378+
<ParamField path="object.project.slug" type="string">
379+
Project slug
380+
</ParamField>
381+
382+
<ParamField path="object.project.name" type="string">
383+
Project name
384+
</ParamField>
385+

0 commit comments

Comments
 (0)