Metrics Builder

Metrics Builder helps teams create custom metrics, inspect the logic behind a metric, and turn metric results into charts and dashboards. Use Metrics Builder when the pre-built dashboards do not answer a specific reporting question or when your team needs a tailored view of engineering activity.

What Metrics Builder does

Metrics Builder gives advanced users a controlled workflow for building custom metrics on top of LinearB engineering data. Depending on your access, you can use it to:

• Create custom metrics for questions that are not covered by standard dashboard widgets.
• Generate charts from metric results and use them in custom dashboards.
• Inspect and refine SQL when a metric needs more precise logic.
• Iterate on metric definitions before sharing them more broadly with your organization.

Access Metrics Builder

1. In LinearB, select Metrics from the left navigation.
2. Select Metrics Builder.

Before you begin

• Your organization must have Metrics Builder enabled by LinearB.
• You must have the LinearB Admin role.

When to use Metrics Builder

Use Metrics Builder when you need to answer an engineering metrics question that requires more flexibility than a pre-built LinearB dashboard.

• You want a custom chart for a specific team, repository, workflow, or operational question.
• You need to combine filters or dimensions in a way that is not available in a standard dashboard widget.
• You want to validate a custom metric before adding it to a dashboard or sharing it with other stakeholders.
• You are working with LinearB as part of the Metrics Builder beta or design-partner program.

Using the Metrics Builder workspace

Metrics Builder includes a dashboard workspace for reviewing saved metric views and a custom metric builder for creating or refining metric logic.

• Dashboard shows saved dashboards and the widgets added to the selected dashboard.
• Custom Metric Builder is where you create or update custom metric logic before adding the result to a dashboard.
• Date Range controls the reporting window used by the dashboard widgets.
• AI Assistant can help generate or refine metric questions and SQL during the beta workflow.

Create a dashboard

1. Select Dashboard.
2. In the dashboard list, select + New dashboard.
3. Enter a dashboard Name.
4. Optionally add a Description.
5. Use the Public toggle if the dashboard should be visible to other users with the required LinearB access.
6. Select Create.

Change the dashboard date range

Use the Date Range picker to choose the start and end dates for the dashboard. Dashboard widgets use that selected range when querying metric data.

Using Quick Queries

Quick Queries provide predefined metric templates that can be used as starting points for custom metrics. Selecting a query loads the SQL into the editor, where you can review, modify, validate, and run it.

Build a custom metric

1. Select Custom Metric Builder.
2. Choose a starting point from Quick Queries, write a query in the SQL Query Editor, or use Ask AI to start from scratch.
3. Use Validate to check the query syntax and references.
4. Select Run Query, or press Ctrl+Enter, to run the query for the selected date range.
5. Review the result in Query Results.
6. Choose Table, Bar Chart, Line Chart, or Metric to change how the result is displayed.
7. Select Save as widget when the result is ready to add to a dashboard.

Using template variables

The SQL editor supports template variables for the dashboard date range:

{start_date}
          {end_date}

These values are substituted when the query runs. Use them to keep custom metrics aligned with the selected Date Range.

Press Ctrl+Space in the editor to trigger autocomplete for tables, columns, metrics, and SQL keywords. Use Ask AI when you want help drafting or refining a query.

Use in-editor help

The SQL Query Editor includes inline suggestions while you write a query.

• Press Ctrl+Space, press Space, or start typing to open the suggestion menu.
• Type part of an element name to filter suggestions. For example, typing v_ shows available views.
• Select a suggestion to insert it into the query.
• Use the information panel to review short descriptions for suggested views, columns, metrics, and SQL elements.
• When a suggestion has a > option, open it to read more detailed information about that element.

Create a metric with Ask AI

1. Select Ask AI from the Custom Metric Builder workspace.
2. Enter the metric question or result you want to create. For example, ask for a metric that shows bug age, PRs opened per week, or AI code longevity.
3. Select Send.
4. Review the generated SQL in the Ask AI panel.
5. Select Load into Editor to copy the generated SQL into the SQL Query Editor.
6. Review the query and make any required edits.
7. Select Validate. A Valid status appears when the query passes validation.
8. Select Run Query to generate the result.
9. Configure the result as a table, chart, or metric, then select Save as widget to add it to a dashboard.

Use New Chat when you want to start a separate Ask AI request without continuing the current conversation.

Configure query results

After a query runs, the Query Results panel shows the returned rows and the query runtime. You can switch between display types before saving the result as a widget.

• Table shows the raw result rows and columns.
• Bar Chart lets you select the X-Axis, Y-Axis, optional Group By field, and Stacked or Grouped bar mode.
• Line Chart is useful for time-series results, such as weekly or daily trends.
• Metric is useful when the query returns a single value or summary result.

Manage dashboard widgets

Each dashboard widget has a menu with the following actions:

• Edit opens the widget settings.
• Clone copies the widget so you can reuse and adjust it.
• Delete removes the widget from the dashboard.

Edit widget settings

In Widget Settings, you can update the widget title, chart display, query, and series colors.

• Title controls the widget name shown on the dashboard.
• Chart Type supports Table, Bar Chart, Line Chart, and Metric.
• Bar Mode controls whether bar charts are Stacked or Grouped.
• SQL Query contains the query used to generate the widget result.
• Validate checks whether the query can run successfully.
• Run Query runs the query so you can review the result before saving.
• Series colors lets you control the color used for each returned series.
• Save applies the widget changes to the dashboard.

Beta considerations

• Metrics Builder is intended for advanced users during the beta period.
• Some workflows may require LinearB support or design-partner coordination.
• Available fields, metric patterns, and SQL-editing behavior may change as the beta progresses.
• Metrics Builder should respect your organization’s LinearB permissions and data access settings.

Troubleshooting

No data appears in the result

Verify that the selected date range contains relevant activity and that the selected filters match data available in LinearB. If the metric depends on Git or project-management data, confirm that the required integrations are connected and syncing.

You can also reopen Ask AI from the Custom Metric Builder workspace and explain that the query returned no visible data. You can also use Ask AI to refine the query or generate an alternative SQL statement based on the metric you are trying to create., and can suggest changes to the query. Load the updated SQL into the editor, run it again, and continue iterating until the result matches the metric question.

The chart does not match the expected metric

Review the metric definition, grouping, and filters. For custom metrics, small differences in date range, team selection, repository scope, or issue-state logic can change the result.

A user cannot access a metric or dashboard

Confirm that the user has access to Metrics Builder and to the underlying LinearB data included in the dashboard. During beta, access may be limited to selected users or admin-only workflows.

Related resources

Understanding Metrics Dashboards in LinearB

Building Custom Metrics Reports in LinearB

Metrics Inspection in LinearB