Create custom widgets for streaming dashboards

Custom widgets let you extend the Media Streaming dashboard with bespoke chart visualizations built from your own NRQL queries. Custom widgets appear in the Quality Metrics dropdown alongside the predefined metrics, under a separate Custom Metrics category. They persist across sessions and scale within the existing dashboard.

Before you begin

Custom widgets are created from within the Media Streaming nerdpack. You need 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.

Create a custom widget

1. Open the Media Streaming dashboard and navigate to the Quality Metrics section.
2. Click + Add Custom Widget.
3. Enter a title for the widget.
4. Write your NRQL query in the NRQL editor. See Writing queries for guidance on syntax, filter placeholders, and examples.
5. Click Run Query to preview results before saving.
6. Click Save. The widget is added to the Custom Metrics section of the Quality Metrics dropdown and rendered in the dashboard.

Writing queries

The NRQL editor accepts any valid NRQL SELECT or FROM query. Write your full query directly in the editor — syntax highlighting, autocomplete, and real-time validation are provided by the editor.

Query requirements

• Queries must begin with SELECT or FROM and contain both clauses.
• Do not include a hardcoded SINCE or UNTIL clause. The dashboard's time picker injects the time range automatically at execution time.
• To respond to dashboard-level filter bar selections, include a filter placeholder in your query.

Filter placeholders

Filter placeholders are NRQL comment tokens that get replaced at runtime with the filter conditions applied in the dashboard filter bar. Add them manually to your query.

Example — no existing WHERE clause:

SELECT uniqueCount(viewId) AS 'Total Views'
FROM VideoAction /* {whereClause} */
TIMESERIES

When a filter for asn = '14618' is active:

SELECT uniqueCount(viewId) AS 'Total Views'
FROM VideoAction WHERE asn = '14618'
TIMESERIES SINCE 30 minutes ago UNTIL now

Example — existing WHERE clause:

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

Example — filter inside an aggregator function:

FROM VideoAction
SELECT (
  filter(sum(timeSinceBufferBegin),
    WHERE actionName = 'CONTENT_BUFFER_END'
    AND bufferType = 'connection' /* {aggregatorWhereClause} */
  ) /
  filter(sum(elapsedTime) OR 1,
    WHERE actionName = 'CONTENT_HEARTBEAT' /* {aggregatorWhereClause} */
  )
) AS 'Connection-induced rebuffering ratio'
TIMESERIES

Blocked keywords and characters

To prevent accidental or malicious data modification, the following are blocked in the NRQL editor:

Blocked keywords:

• DROP
• DELETE
• INSERT
• UPDATE
• CREATE
• ALTER

Blocked characters:

• Semicolons (;) — blocked to prevent query chaining or injection attacks.

Queries containing any of these will fail validation and cannot be saved or previewed.

Query examples

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

Connection-induced rebuffering ratio (advanced):

FROM VideoAction
SELECT (
  filter(sum(timeSinceBufferBegin),
    WHERE actionName = 'CONTENT_BUFFER_END'
    AND bufferType = 'connection' /* {aggregatorWhereClause} */
  ) /
  filter(sum(elapsedTime) OR 1,
    WHERE actionName = 'CONTENT_HEARTBEAT' /* {aggregatorWhereClause} */
  )
) AS 'Connection-induced rebuffering ratio'
TIMESERIES

For more query inspiration, see Bitrate metrics data dictionary for pre-built NRQL examples using VideoAction and VideoErrorAction.

Preview a widget

Click Run Query before saving to execute the query against live data and see a rendered chart. This does not save the widget.

Use the preview to:

• Confirm the chart renders the data you expect.
• Verify that filter placeholders resolve correctly when a filter is active in the filter bar.
• Catch syntax or logic errors before the widget is committed to the dashboard.

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.
3. The editor opens in edit mode with all fields pre-populated — title and existing NRQL query.
4. Make your changes, click Run Query to verify, then click Save.

When saved:

• The updatedAt timestamp is updated; the original createdAt and widget id are preserved.
• The widget immediately re-renders with the updated query.
• If you changed the title, it updates in the Quality Metrics dropdown.

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:

• The widget is removed from NerdStorage and is permanently gone.
• The widget card is immediately removed from the dashboard.
• The title is removed from the Quality Metrics dropdown.
• If the widget was selected, it is automatically deselected.

Widget limit

The soft limit of 50 widgets per account is based on NerdStorage document capacity. At 50 widgets, storage usage is approximately 21 KB — about 33% of the 64 KB per-document limit, providing a safe margin.

If you reach the limit, widget creation is blocked until an existing custom widget is deleted. Existing widgets continue to function normally.

Troubleshooting