Changelog #72
Add tags to your runs
You can add tags to your runs then filter them using the dashboard or SDK.
CEO, Trigger.dev
Tagging runs is a powerful feature that makes debugging easier and allows you to build things that weren't possible before.
Here we're filtering runs in the dashboard by user and org:
You can do the same filtering using the runs.list() function in the SDK. Here we're adding up the total compute cost for an organization using our usage tracking:
_16import { runs } from "@trigger.dev/sdk/v3";_16_16async function getComputeDollarCostForOrg(orgId: string) {_16 let totalCost = 0;_16_16 // This loops through every single run matching the tag and status_16 for await (const run of runs.list({_16 tag: orgId,_16 status: ["COMPLETED"],_16 })) {_16 // Use our usage data to calculate the total cost_16 totalCost += run.costInCents + run.baseCostInCents;_16 }_16_16 return totalCost / 100;_16}
What are tags?
Tags are strings between 1 and 64 characters long that can be attached to a run. You can add up to 3 tags to each run when you trigger and/or during the run.
Here are some example tags:
user_123456: the user ID associated with the run.org_654321: the organization ID associated with the run.subscriber,free-trial: for the type of user the run belongs to.
We strongly recommend that you prefix your tags with the type at the beginning using an underscore or colon, like user_123456. This makes it easier to filter and search for tags – we also make them look nicer in the dashboard:
NOTE
Lots of popular APIs already prefix their IDs so you can just throw them into
your tags. Stripe for example uses cus_123456 for customers.
How to add tags
You can add tags to a run when you trigger it:
_10const handle = await myTask.trigger(_10 { message: "hello world" },_10 // A string or an array of up to 3 strings_10 { tags: ["user_123456", "org_abcdefg"] }_10);
Or you can add tags during a run:
_13import { task, tags } from "@trigger.dev/sdk/v3";_13_13export const myTask = task({_13 id: "my-task",_13 run: async (payload: { message: string }, { ctx }) => {_13 // Get the tags from when the run was triggered using the context_13 // This is not updated if you add tags during the run_13 logger.log("Tags from the run context", { tags: ctx.run.tags });_13_13 // Add tags during the run (a single string or array of strings)_13 await tags.add("product_1234567");_13 },_13});
NOTE
Remember the total tags on a run are limited to 3. So if you trigger with 2 tags you can only add 1 more during the run.
Updating to beta 51
You need to ensure your packages are at least @trigger.dev/[email protected] to use tags. Read our upgrading packages guide for the fastest way to do that.
For the full details on tags, check out our tags documentation.