Créer des widgets personnalisés pour les dashboards de streaming

Les widgets personnalisés vous permettent d’étendre le dashboard Media Streaming avec des visualisations de graphiques créées à partir de vos propres requêtes NRQL. Utilisez-les lorsque les métriques de qualité intégrées ne couvrent pas un point de données spécifique que votre équipe doit monitorer.

Avant de commencer

Vous avez besoin des éléments suivants avant de créer un widget personnalisé :

• Accès à un compte New Relic avec l’agent Streaming Video & Ads installé. Consultez Installer l’agent Streaming vidéo et publicitaire si vous ne l’avez pas encore configuré.
• Le bouton + Add Custom Widget visible dans la section Métriques de qualité. Si ce n’est pas le cas, contactez votre équipe de compte New Relic pour demander l’accès.

Écrivez votre requête NRQL

L’éditeur NRQL prend en charge toute requête NRQL valide. Pour une introduction à la syntaxe NRQL, consultez Introduction à NRQL.

Exigences de la requête

Les requêtes de widget personnalisées ont deux exigences supplémentaires au-delà du NRQL standard :

• N’écrivez pas de clause SINCE ou UNTIL directement dans votre requête. Le sélecteur d’intervalle de temps du dashboard ajoute automatiquement la plage de temps lorsque la requête s’exécute.
• Pour répondre aux sélections de la barre de filtres au niveau du dashboard, incluez un espace réservé de filtre dans votre requête.

Espaces réservés de filtrage

Le dashboard applique des filtres globaux lorsqu’une requête s’exécute. Si vous écrivez une clause WHERE simple directement dans votre requête, le dashboard ne peut pas y injecter les conditions de filtre sélectionnées par l’utilisateur. Les espaces réservés de filtre sont des commentaires NRQL spéciaux qui sont remplacés par les conditions de filtre actives lorsque la requête s’exécute.

Exemple — aucune clause WHERE existante :

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

Avec le filtre City = Ashburn appliqué :

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

Exemple — clause WHERE existante :

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

Avec le filtre City = Ashburn appliqué :

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

Exemple — requête de ratio avec des agrégateurs mixtes :

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

Avec le filtre City = Ashburn appliqué :

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

Sans aucun filtre actif :

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

Mots-clés et caractères bloqués

Pour éviter toute modification accidentelle des données, l’éditeur NRQL rejette les requêtes qui contiennent :

• Les mots-clés DROP, DELETE, INSERT, UPDATE, CREATE, ou ALTER
• Les points-virgules (;), qui permettraient une chaîne de requêtes

Les requêtes contenant l’un de ces éléments échouent à la validation et ne peuvent pas être enregistrées, ou prévisualisées.

Exemples de requêtes

Les exemples suivants montrent des modèles de requête courants pour le monitoring vidéo et publicitaire. Chacun utilise l’espace réservé de filtre approprié pour sa structure de requête.

Série chronologique de base — nombre total de lancements de vidéos :

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

Nombre de spectateurs uniques avec intégration de filtre :

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

Taux d’erreur sur l’ensemble des types d’événements :

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

Temps de visionnage moyen (ratio avec des agrégateurs imbriqués) :

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

Limites

Certains modèles de requête NRQL ont une prise en charge limitée ou non testée lorsque les filtres globaux sont actifs. Consultez Limitations pour le Streaming vidéo et publicitaire pour obtenir la liste complète.

Créer un widget personnalisé

Pour créer un widget personnalisé :

1. Allez dans one.newrelic.com > All Capabilities > Streaming Video & Ads, puis sélectionnez Video Overview ou Ads Overview.
2. Faites défiler vers le bas jusqu'à la section Video Quality Metrics ou Ad Quality Metrics.
3. Cliquez sur + Add Custom Widget dans l’en-tête de la section.
4. Saisissez un titre unique pour le widget.
5. Écrivez votre requête NRQL dans l’éditeur NRQL. Consultez Écrivez votre requête NRQL ci-dessus pour obtenir des conseils sur la syntaxe, les espaces réservés de filtre et des exemples.
6. Cliquez sur Run Query pour prévisualiser les résultats par rapport aux données en direct. Cela n’enregistre pas le widget. Utilisez l’aperçu pour confirmer que le graphique affiche les données que vous attendez, vérifier que les espaces réservés de filtre se résolvent correctement lorsqu’un filtre est actif, et détecter toute erreur de syntaxe ou de logique avant d’enregistrer.
7. Lorsque l’aperçu se charge, le sélecteur de type de graphique apparaît. La valeur par défaut est Line : sélectionnez un type différent si nécessaire. Certains types de graphiques peuvent apparaître grisés s’ils ne sont pas recommandés pour les résultats de votre requête, mais vous pouvez toujours sélectionner l’un d’entre eux : Billboard, Line, Area, Bar, Table, ou Pie.
8. Cliquez sur Save. New Relic ajoute le widget à la section Custom Metrics de la liste déroulante du sélecteur de métrique et l’affiche en haut de la grille des métriques de qualité. Les widgets persistent d’une session à l’autre.

Modifier un widget personnalisé

Pour modifier un widget personnalisé :

1. Dans la section Quality Metrics, localisez le widget personnalisé que vous souhaitez modifier.
2. Cliquez sur l’icône en forme de crayon sur la carte du widget. L’éditeur s’ouvre avec votre titre et votre requête existants préremplis.
3. Apportez vos modifications, cliquez sur Run Query pour vérifier, puis cliquez sur Save.

Lors de l’enregistrement :

• Votre date de création d’origine et l’identité du widget sont préservées.
• le widget se réaffiche immédiatement avec la requête mise à jour.
• Si vous avez modifié le titre, il se met à jour dans la liste déroulante du sélecteur de métrique.

Supprimer un widget personnalisé

Pour supprimer un widget personnalisé :

1. Dans la section Quality Metrics, cliquez sur l’icône sur la carte du widget.
2. Sélectionnez Delete.
3. Confirmez dans le prompt : « Êtes-vous sûr de vouloir supprimer “[Widget Title]” ? Cette action ne peut pas être annulée. »

Une fois supprimé :

• New Relic supprime définitivement le widget.
• Le dashboard supprime immédiatement la carte du widget.
• La liste déroulante du sélecteur de métrique supprime l’entrée du titre.
• Si le widget a été sélectionné, le dashboard le désélectionne automatiquement.

Dépannage

Trouvez votre symptôme ci-dessous. Les problèmes sont classés du plus au moins courant.

Le widget ne se met pas à jour lorsque j’applique un filtre de dashboard

Il manque un espace réservé de filtre à votre requête. Sans /* {whereClause} */, /* {andWhereClause} */ ou /* {aggregatorWhereClause} */, le widget exécute toujours la requête telle qu’elle est écrite et ignore les sélections de la barre de filtres du dashboard. Consultez Espaces réservés de filtre pour choisir celui qui convient à la structure de votre requête.

Les filtres s’appliquent mais la requête renvoie une erreur ou aucune donnée

Vous avez peut-être utilisé le mauvais type d'espace réservé. Vérifier :

• Si votre requête n'a pas de clause WHERE, utilisez /* {whereClause} */.
• Si votre requête possède déjà une clause WHERE au niveau de la requête, utilisez /* {andWhereClause} */.
• Si l’espace réservé se trouve dans un agrégateur filter() sans WHERE interne existant, utilisez /* {aggregatorWhereClause} */.

Le mauvais espace réservé produit un NRQL non valide lors de l'exécution de la requête, ce qui entraîne son échec.

Ma requête échoue à la validation ou ne s’enregistre pas

Vérifiez si votre requête contient un mot-clé ou caractère bloqué, tel que DROP, DELETE, ou un point-virgule. Vérifiez également que la requête répond à ces exigences :

• La requête contient à la fois les clauses SELECT et FROM.
• Il n'y a aucune erreur de syntaxe signalée par la validation en ligne de l'éditeur.

Le widget ne s’enregistre pas : le titre existe déjà

Si un widget avec le même titre existe déjà dans le même contexte de dashboard (métriques de qualité vidéo ou publicitaire), l’enregistrement échoue avec une notification toast :

• Titre : échec de l’enregistrement du widget
• Description : un widget avec ce nom existe déjà

La correspondance des titres est insensible à la casse : My Widget et MY WIDGET sont traités comme le même titre. Choisissez un titre distinct ou renommez d'abord le widget existant.

Le widget s'enregistre mais disparaît après une actualisation de la page

Cela peut indiquer un échec d’enregistrement. Vérifiez si une notification toast est apparue au moment de l’enregistrement : elle indiquera si l’enregistrement a échoué en raison d’une erreur réseau. Réessayez d’enregistrer, ou contactez votre équipe de compte New Relic si le problème persiste.

Je ne peux pas ajouter de nouveau widget

Vous avez atteint la limite souple de 50 widgets pour ce contexte de dashboard (métriques de qualité vidéo ou publicitaire). Supprimez au moins un widget personnalisé existant, puis essayez d’en ajouter un nouveau.

Le bouton + Ajouter un widget personnalisé n’est pas visible

New Relic contrôle l’accès à cette fonctionnalité. Contactez votre équipe de compte New Relic pour demander l’accès.