Dashboards

​

Overview

​

Available metrics data

​

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.)

​

Filtering and time ranges

• 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 and choose a visualization type.
5. You can resize and reposition widgets on your dashboards.

​

Managing dashboards with the SDK

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_...

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,
});

​

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

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