Changelog #72

·

Add tags to your runs

You can add tags to your runs then filter them using the dashboard or SDK.

Matt Aitken

Matt Aitken

CEO, Trigger.dev

Image for Add tags to your runs

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:


_16
import { runs } from "@trigger.dev/sdk/v3";
_16
_16
async 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:

Tagging runs 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:


_10
const 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:


_13
import { task, tags } from "@trigger.dev/sdk/v3";
_13
_13
export 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.

#71
#73

Ready to start building?

Build and deploy your first task in 3 minutes.

Get started now
,