Criar widgets personalizados para dashboards de streaming

Os widgets personalizados permitem estender o dashboard de Media Streaming com visualizações de gráficos criadas a partir de suas próprias consultas NRQL. Use-os quando as métricas de qualidade integradas não cobrirem um ponto de dados específico que sua equipe precisa monitorar.

Antes de você começar

Você precisa do seguinte antes de criar um widget personalizado:

• Acesso a uma conta da New Relic com o agente Streaming Video & Ads instalado. Consulte Instalar o agente de Streaming de Vídeo e Anúncios se você ainda não o configurou.
• O botão + Add Custom Widget visível na seção Métricas de qualidade. Se não estiver, entre em contato com a equipe da sua conta da New Relic para solicitar acesso.

Escreva sua consulta NRQL

O editor NRQL suporta qualquer consulta NRQL válida. Para uma introdução à sintaxe NRQL, consulte Introdução ao NRQL.

Requisitos da consulta

As consultas de widget personalizadas têm dois requisitos adicionais além do NRQL padrão:

• Não escreva uma cláusula SINCE ou UNTIL diretamente na sua consulta. O seletor de hora do dashboard adiciona o intervalo de tempo automaticamente quando a consulta é executada.
• Para responder às seleções da barra de filtros no nível do dashboard, inclua um espaço reservado de filtro em sua consulta.

Espaços reservados de filtro

O dashboard aplica filtros globais quando uma consulta é executada. Se você escrever uma cláusula WHERE simples diretamente na sua consulta, o dashboard não pode injetar nela as condições de filtro selecionadas pelo usuário. Os espaços reservados de filtro são comentários especiais em NRQL que são substituídos pelas condições de filtro ativas quando a consulta é executada.

Exemplo — sem cláusula WHERE existente:

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

Com o filtro City = Ashburn aplicado:

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

Exemplo — cláusula WHERE existente:

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

Com o filtro City = Ashburn aplicado:

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

Exemplo — consulta de proporção com agregadores mistos:

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

Com o filtro City = Ashburn aplicado:

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

Sem nenhum filtro ativo:

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

Palavras-chave e caracteres bloqueados

Para evitar a modificação acidental de dados, o editor de NRQL rejeita consultas que contêm:

• As palavras-chave DROP, DELETE, INSERT, UPDATE, CREATE ou ALTER
• Ponto e vírgula (;), que permitiria a cadeia de consultas

Consultas que contêm qualquer um destes falham na validação e não podem ser salvas ou pré-visualizadas.

Consultas de exemplo

Os exemplos a seguir mostram padrões comuns de consulta para monitoramento de vídeo e anúncios. Cada um usa o espaço reservado de filtro apropriado para sua estrutura de consulta.

Série temporal básica — total de inícios de vídeo:

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

Contagem de espectadores únicos com integração de filtro:

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

Taxa de erros entre tipos de evento:

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

Tempo médio de exibição (proporção com agregadores aninhados):

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

Limitações

Alguns padrões de consulta NRQL têm suporte limitado ou não testado quando os filtros globais estão ativos. Consulte Limitações de Streaming de Vídeo e Anúncios para ver a lista completa.

Criar um widget personalizado

Para criar um widget personalizado:

1. Vá para one.newrelic.com > All Capabilities > Streaming Video & Ads e, em seguida, selecione Video Overview ou Ads Overview.
2. Role para baixo até a seção Video Quality Metrics ou Ad Quality Metrics.
3. Clique em + Add Custom Widget no cabeçalho da seção.
4. Insira um título exclusivo para o widget.
5. Escreva sua consulta NRQL no editor NRQL. Consulte Escreva sua consulta NRQL acima para obter orientações sobre sintaxe, espaços reservados de filtro e exemplos.
6. Clique em Run Query para visualizar os resultados com dados em tempo real. Isso não salva o widget. Utilize a pré-visualização para confirmar se o gráfico renderiza os dados esperados, verificar se os espaços reservados de filtro são resolvidos corretamente quando um filtro está ativo e detectar quaisquer erros de sintaxe ou lógica antes de salvar.
7. Quando a visualização é carregada, o seletor de tipo de gráfico é exibido. O padrão é Line— selecione um tipo diferente, se necessário. Alguns tipos de gráfico podem aparecer esmaecidos se não forem recomendados para os resultados da sua consulta, mas você ainda pode selecionar qualquer um deles: Billboard, Line, Area, Bar, Table ou Pie.
8. Clique em Save. A New Relic adiciona o widget à seção Custom Metrics do dropdown do seletor de métricas e o renderiza na parte superior da grade de métricas de qualidade. Os widgets persistem entre as sessões.

Editar um widget personalizado

Para editar um widget personalizado:

1. Na seção Quality Metrics, localize o widget personalizado que você deseja alterar.
2. Clique no ícone de lápis no cartão do widget. O editor é aberto com o título e a consulta existentes pré-preenchidos.
3. Faça suas alterações, clique em Run Query para verificar e, em seguida, clique em Save.

Quando salvo:

• Sua data de criação original e a identidade do widget são preservadas.
• O widget é renderizado novamente de forma imediata com a consulta atualizada.
• Se você alterou o título, ele será atualizado no dropdown do seletor de métricas.

Excluir um widget personalizado

Para excluir um widget personalizado:

1. Na seção Quality Metrics, clique no ícone no cartão do widget.
2. Selecione Delete.
3. Confirme no prompt: "Tem certeza de que deseja excluir '[Título do Widget]'? Esta ação não pode ser desfeita."

Quando excluído:

• A New Relic exclui permanentemente o widget.
• O dashboard remove imediatamente o cartão do widget.
• O dropdown do seletor de métrica remove a entrada de título.
• Se o widget foi selecionado, o dashboard o desmarca automaticamente.

Solucionar problemas

Encontre seu sintoma abaixo. Os problemas estão ordenados do mais para o menos comum.

O widget não é atualizado quando aplico um filtro de dashboard

Falta um espaço reservado de filtro na sua consulta. Sem /* {whereClause} */, /* {andWhereClause} */ ou /* {aggregatorWhereClause} */, o widget sempre executa a consulta conforme escrita e ignora as seleções da barra de filtros do dashboard. Consulte Espaços reservados de filtro para escolher o correto para a estrutura da sua consulta.

Os filtros se aplicam, mas a consulta retorna um erro ou nenhum dado

Você pode ter usado o tipo de espaço reservado errado. Verifique:

• Se a sua consulta não tiver uma cláusula WHERE, use /* {whereClause} */.
• Se a sua consulta já tiver uma cláusula WHERE no nível da consulta, use /* {andWhereClause} */.
• Se o espaço reservado estiver dentro de um agregador filter() sem nenhum WHERE interno existente, use /* {aggregatorWhereClause} */.

O espaço reservado errado produz um NRQL inválido quando a consulta é executada, fazendo com que ela falhe.

Minha consulta falha na validação ou não é salva

Verifique se a sua consulta contém uma palavra-chave ou caractere bloqueado, como DROP, DELETE ou um ponto e vírgula. Verifique também se a consulta atende a estes requisitos:

• A consulta contém as cláusulas SELECT e FROM.
• Não há erros de sintaxe sinalizados pela validação embutida do editor.

O widget não será salvo — o título já existe

Se um widget com o mesmo título já existir no mesmo contexto do dashboard (métricas de qualidade de vídeo ou anúncio), o salvamento falha com uma notificação toast:

• Título: falha ao salvar o widget
• Descrição: um widget com este nome já existe

A correspondência de títulos não diferencia maiúsculas de minúsculas — My Widget e MY WIDGET são tratados como o mesmo título. Escolha um título distinto ou renomeie o widget existente primeiro.

O widget é salvo, mas desaparece após uma atualização da página

Isso pode indicar uma falha ao salvar. Verifique se há uma notificação toast que apareceu no momento do salvamento — ela indicará se o salvamento falhou devido a um erro de rede. Tente salvar novamente ou entre em contato com a equipe da sua conta da New Relic se o problema persistir.

Não consigo adicionar um novo widget

Você atingiu o limite flexível de 50 widgets para este contexto de dashboard (métricas de qualidade de vídeo ou anúncio). Exclua pelo menos um widget personalizado existente e, em seguida, tente adicionar um novo.

O botão + Adicionar widget personalizado não está visível

A New Relic controla o acesso a esse recurso. Entre em contato com a equipe da sua conta da New Relic para solicitar acesso.