Create custom widgets for streaming dashboards

Custom widgets let you extend the Media Streaming dashboard with chart visualizations built from your own NRQL queries. Use them when the built-in quality metrics don't cover a specific data point your team needs to monitor.

Before you begin

You need the following before creating a custom widget:

• Access to a New Relic account with the Streaming Video & Ads agent installed. See Install the Streaming Video & Ads agent if you haven't set it up yet.
• The + Add Custom Widget button visible in the Quality Metrics section. If it isn't, contact your New Relic account team to request access.

Write your NRQL query

The NRQL editor supports any valid NRQL query. For an introduction to NRQL syntax, see Introduction to NRQL.

Query requirements

Custom widget queries have two additional requirements beyond standard NRQL:

• Don't write a SINCE or UNTIL clause directly in your query. The dashboard time picker adds the time range automatically when the query runs.
• To respond to dashboard-level filter bar selections, include a filter placeholder in your query.

Filter placeholders

The dashboard applies global filters when a query runs. If you write a plain WHERE clause directly in your query, the dashboard can't inject user-selected filter conditions into it. Filter placeholders are special NRQL comments that get replaced with the active filter conditions when the query runs.

Example — no existing WHERE clause:

SELECT count(*) FROM VideoAction /* {whereClause} */

With filter City = Ashburn applied:

SELECT count(*) FROM VideoAction WHERE city = 'Ashburn' SINCE 30 minutes ago UNTIL now

Example — existing WHERE clause:

SELECT count(*) FROM VideoAction
WHERE actionName = 'QOE_AGGREGATE' /* {andWhereClause} */

With filter City = Ashburn applied:

SELECT count(*) FROM VideoAction
WHERE actionName = 'QOE_AGGREGATE' AND city = 'Ashburn' SINCE 30 minutes ago UNTIL now

Example — ratio query with mixed aggregators:

FROM VideoAction
SELECT filter(sum(elapsedTime), WHERE actionName = 'CONTENT_HEARTBEAT' /* {andWhereClause} */)
     / filter(uniqueCount(viewId) /* {aggregatorWhereClause} */)
  AS 'avgWatchTime'
TIMESERIES

With filter City = Ashburn applied:

FROM VideoAction
SELECT filter(sum(elapsedTime), WHERE actionName = 'CONTENT_HEARTBEAT' AND city = 'Ashburn')
     / filter(uniqueCount(viewId), WHERE city = 'Ashburn')
  AS 'avgWatchTime'
TIMESERIES SINCE 30 minutes ago UNTIL now

Without any active filter:

FROM VideoAction
SELECT filter(sum(elapsedTime), WHERE actionName = 'CONTENT_HEARTBEAT')
     / uniqueCount(viewId)
  AS 'avgWatchTime'
TIMESERIES SINCE 30 minutes ago UNTIL now

Blocked keywords and characters

To prevent accidental data modification, the NRQL editor rejects queries that contain:

• The keywords DROP, DELETE, INSERT, UPDATE, CREATE, or ALTER
• Semicolons (;), which would allow query chaining

Queries containing any of these fail validation and can't be saved or previewed.

Sample queries

The following examples show common query patterns for video and ad monitoring. Each uses the appropriate filter placeholder for its query structure.

Basic timeseries — total video starts:

SELECT count(*) AS 'Video Starts'
FROM VideoAction
WHERE actionName = 'CONTENT_START' /* {andWhereClause} */
TIMESERIES

Unique viewer count with filter integration:

SELECT uniqueCount(viewId) AS 'Unique Viewers'
FROM VideoAction /* {whereClause} */
TIMESERIES

Error rate across event types:

SELECT count(*) AS 'Error Count'
FROM VideoErrorAction, VideoAction
WHERE actionName = 'CONTENT_ERROR' /* {andWhereClause} */
TIMESERIES

Average watch time (ratio with nested aggregators):

FROM VideoAction
SELECT filter(sum(elapsedTime), WHERE actionName = 'CONTENT_HEARTBEAT' /* {andWhereClause} */)
     / filter(uniqueCount(viewId) /* {aggregatorWhereClause} */)
  AS 'avgWatchTime'
TIMESERIES

Limitations

Some NRQL query patterns have limited or untested support when global filters are active. See Limitations for Streaming Video & Ads for the full list.

Create a custom widget

To create a custom widget:

1. Go to one.newrelic.com > All Capabilities > Streaming Video & Ads, then select Video Overview or Ads Overview.
2. Scroll down to the Video Quality Metrics or Ad Quality Metrics section.
3. Click + Add Custom Widget in the section header.
4. Enter a unique title for the widget.
5. Write your NRQL query in the NRQL editor. See Write your NRQL query above for guidance on syntax, filter placeholders, and examples.
6. Click Run Query to preview results against live data. This doesn't save the widget. Use the preview to confirm the chart renders the data you expect, verify filter placeholders resolve correctly when a filter is active, and catch any syntax or logic errors before saving.
7. When the preview loads, the chart type picker appears. The default is Line—select a different type if needed. Some chart types may appear grayed out if they aren't recommended for your query results, but you can still select any of them: Billboard, Line, Area, Bar, Table, or Pie.
8. Click Save. New Relic adds the widget to the Custom Metrics section of the metric selector dropdown and renders it at the top of the quality metrics grid. Widgets persist across sessions.

Edit a custom widget

To edit a custom widget:

1. In the Quality Metrics section, locate the custom widget you want to change.
2. Click the pencil icon on the widget card. The editor opens with your existing title and query pre-populated.
3. Make your changes, click Run Query to verify, then click Save.

When saved:

• Your original creation date and widget identity are preserved.
• The widget immediately re-renders with the updated query.
• If you changed the title, it updates in the metric selector dropdown.

Delete a custom widget

To delete a custom widget:

1. In the Quality Metrics section, click the icon on the widget card.
2. Select Delete.
3. Confirm in the prompt: "Are you sure you want to delete '[Widget Title]'? This action cannot be undone."

When deleted:

• New Relic permanently deletes the widget.
• The dashboard immediately removes the widget card.
• The metric selector dropdown removes the title entry.
• If the widget was selected, the dashboard deselects it automatically.

Troubleshoot

Find your symptom below. Issues are ordered from most to least common.

Widget doesn't update when I apply a dashboard filter

Your query is missing a filter placeholder. Without /* {whereClause} */, /* {andWhereClause} */, or /* {aggregatorWhereClause} */, the widget always runs the query as written and ignores dashboard filter bar selections. See Filter placeholders to choose the right one for your query structure.

Filters apply but the query returns an error or no data

You may have used the wrong placeholder type. Check:

• If your query has no WHERE clause, use /* {whereClause} */.
• If your query already has a WHERE clause at the query level, use /* {andWhereClause} */.
• If the placeholder is inside a filter() aggregator with no existing inner WHERE, use /* {aggregatorWhereClause} */.

The wrong placeholder produces invalid NRQL when the query runs, causing it to fail.

My query fails validation or won't save

Check whether your query contains a blocked keyword or character, such as DROP, DELETE, or a semicolon. Also check that the query meets these requirements:

• The query contains both SELECT and FROM clauses.
• There are no syntax errors flagged by the editor's inline validation.

Widget won't save — title already exists

If a widget with the same title already exists in the same dashboard context (Video or Ad quality metrics), saving fails with a toast notification:

• Title: Failed to save widget
• Description: A widget with this name already exists

Title matching is case-insensitive — My Widget and MY WIDGET are treated as the same title. Choose a distinct title or rename the existing widget first.

Widget saves but disappears after a page refresh

This may indicate a save failure. Check for a toast notification that appeared at save time — it will indicate whether the save failed due to a network error. Retry saving, or contact your New Relic account team if the issue persists.

I can't add a new widget

You've reached the 50-widget soft limit for this dashboard context (Video or Ad quality metrics). Delete at least one existing custom widget, then try adding a new one.

+ Add Custom Widget button is not visible

New Relic controls access to this feature. Contact your New Relic account team to request access.