Criar widgets personalizados para dashboards de streaming

Os widgets personalizados permitem que você estenda o dashboard do Media Streaming com visualizações de gráficos sob medida criadas a partir de suas próprias consultas NRQL. Os widgets personalizados aparecem no dropdown Quality Metrics ao lado das métricas predefinidas, em uma categoria Custom Metrics separada. Eles persistem entre as sessões e são dimensionados dentro do dashboard existente.

Antes de você começar

Os widgets personalizados são criados a partir do nerdpack Media Streaming. Você precisa de acesso a uma conta da New Relic com o agente de Streaming Video & Ads instalado. Consulte Instalar o agente de Streaming de Vídeo e Anúncios se você ainda não o configurou.

Criar um widget personalizado

1. Abra o dashboard de Media Streaming e navegue até a seção Quality Metrics.
2. Clique em + Add Custom Widget.
3. Insira um título para o widget.
4. Escreva sua consulta NRQL no editor NRQL. Consulte Escrevendo consultas para obter orientação sobre sintaxe, espaços reservados de filtro e exemplos.
5. Clique em Run Query para visualizar os resultados antes de salvar.
6. Clique em Save. O widget é adicionado à seção Custom Metrics do dropdown Quality Metrics e renderizado no dashboard.

Escrevendo consultas

O editor NRQL aceita qualquer consulta NRQL SELECT ou FROM válida. Escreva sua consulta completa diretamente no editor — o destaque de sintaxe, o preenchimento automático e a validação em tempo real são fornecidos pelo editor.

Requisitos da consulta

• As consultas devem começar com SELECT ou FROM e conter ambas as cláusulas.
• Não inclua uma cláusula SINCE ou UNTIL codificada. O seletor de hora do dashboard injeta o intervalo de tempo automaticamente no momento da execução.
• 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

Os espaços reservados de filtro são tokens de comentário NRQL que são substituídos no tempo de execução pelas condições de filtro aplicadas na barra de filtro do dashboard. Adicione-os manualmente à sua consulta.

Exemplo — sem cláusula WHERE existente:

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

Quando um filtro para asn = '14618' está ativo:

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

Exemplo — cláusula WHERE existente:

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

Exemplo — filtro dentro de uma função de agregador:

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

Palavras-chave e caracteres bloqueados

Para evitar a modificação acidental ou maliciosa de dados, os seguintes itens estão bloqueados no editor NRQL:

Palavras-chave bloqueadas:

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

Caracteres bloqueados:

• Ponto e vírgula (;) — bloqueado para evitar cadeia de consultas ou ataques de injeção.

Consultas contendo qualquer um destes falharão na validação e não poderão ser salvas ou visualizadas.

Exemplos 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

Taxa de rebufferização induzida pela conexão (avançado):

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

Para mais inspiração de consulta, consulte o Dicionário de Dados de Métrica de Taxa de Bits para exemplos de NRQL pré-construídos usando VideoAction e VideoErrorAction.

Visualizar um widget

Clique em Run Query antes de salvar para executar a consulta em dados ativos e ver um gráfico renderizado. Isso não salva o widget.

Use a pré-visualização para:

• Confirme se o gráfico renderiza os dados que você espera.
• Verifique se os espaços reservados de filtro são resolvidos corretamente quando um filtro está ativo na barra de filtros.
• Detecte erros de sintaxe ou lógica antes que o widget seja confirmado no dashboard.

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.
3. O editor abre no modo de edição com todos os campos pré-preenchidos — título e consulta NRQL existente.
4. Faça suas alterações, clique em Run Query para verificar e, em seguida, clique em Save.

Quando salvo:

• O timestamp updatedAt é atualizado; o createdAt original e o id do widget são preservados.
• O widget é renderizado novamente de forma imediata com a consulta atualizada.
• Se você alterou o título, ele é atualizado no dropdown de Métricas de Qualidade.

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:

• O widget é removido do NerdStorage e excluído permanentemente.
• O cartão do widget é removido imediatamente do dashboard.
• O título é removido do dropdown de Métrica de Qualidade.
• Se o widget estava selecionado, ele é desmarcado automaticamente.

Limite de widget

O limite flexível de 50 widgets por conta é baseado na capacidade de documentos do NerdStorage. Com 50 widgets, o uso de armazenamento é de aproximadamente 21 KB — cerca de 33% do limite de 64 KB por documento, fornecendo uma margem segura.

Se você atingir o limite, a criação de widgets será bloqueada até que um widget personalizado existente seja excluído. Os widgets existentes continuam funcionando normalmente.

Resolução de problemas