Criar e gerenciar relatórios personalizados

Você está visualizando a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Os relatórios personalizados permitem detalhar as métricas específicas da API e ver os dados exatos. É possível criar um relatório personalizado usando qualquer uma das métricas e dimensões incorporadas ao Edge. É possível também anexar a política StatisticsCollector aos proxies da API para coletar métricas personalizadas, como ID do usuário ou produto, preço, ação REST, versão de destino, URL de destino e tamanho da mensagem.

Vídeos

Assista os vídeos em inglês a seguir para saber mais sobre relatórios personalizados.

Vídeo	Descrição
Criar relatórios personalizados usando a IU	Saiba como criar relatórios personalizados usando a interface do Edge.
Visão geral dos relatórios personalizados	Tenha uma visão geral do uso de relatórios personalizados.
Rastrear a latência da API	Veja como rastrear a latência da API usando relatórios personalizados.
Rastrear respostas de erros da API	Use os relatórios personalizados para rastrear as respostas de erros da API.

Sobre relatórios personalizados

Ao criar um relatório personalizado, você seleciona os dados que quer ver (métricas), agrupa-os de modo coerente (dimensões) e, opcionalmente, limita os dados retornados com base em características específicas (filtros).

Também é possível definir o tipo de gráfico exibido no relatório personalizado como um gráfico de linhas ou colunas. Nas imagens a seguir, mostramos exemplos de gráficos de métricas de transações por segundo agrupadas por dimensão do proxy de API:

• Coluna: cada proxy de API é representado por uma coluna diferente:

  

• Linha: cada API é representada como uma linha diferente:

  

Como definir métricas e dimensões

As métricas escolhidas para seu relatório personalizado especificam os dados que você está avaliando. Veja a seguir algumas métricas comuns:

• Transações por segundo
• Tempo de resposta
• Erros de política

É possível definir uma função de agregação para ser executada em algumas métricas. Por exemplo, é possível usar as funções de agregação a seguir com a métrica de tempo de resposta:

• avg: retorna o tempo médio de resposta.
• min: retorna o tempo mínimo de resposta.
• max: retorna o tempo máximo de resposta.
• sum: retorna a soma dos tempos de resposta.

Algumas métricas não aceitam todas as funções de agregação. A documentação sobre métricas inclui uma tabela que especifica o nome da métrica e a função (sum, avg, min, max) que ela aceita.

A dimensão especifica como agrupar os dados das métricas. Por exemplo, se você quer criar um relatório personalizado que mostre a métrica de tempo de resposta, use as dimensões para agrupar os dados das métricas por produto de API, proxy de API ou e-mail do desenvolvedor para ver:

• o tempo de resposta por produto de API;
• o tempo de resposta por proxy de API;
• o tempo de resposta por e-mail do desenvolvedor.

A maneira como a dimensão é exibida no gráfico do relatório personalizado depende do tipo de gráfico:

• Coluna: cada coluna corresponde a um valor diferente da dimensão.
• Linha: cada linha no gráfico corresponde a um valor diferente da dimensão, e o eixo X representa o tempo.

Como criar métricas e dimensões personalizadas

Adicione a política StatisticsCollector aos proxies de API para coletar dados de análise personalizados, como ID do usuário ou produto, preço, ação REST, versão de destino, URL de destino e tamanho da mensagem. Os dados podem ter origem em variáveis de fluxo predefinidas pela Apigee, cabeçalhos de solicitação, parâmetros de consulta ou variáveis personalizadas que você define. Depois que os dados forem coletados, será possível criar um relatório personalizado para visualizá-los.

A maneira como você exibe os dados de análise personalizados em um relatório depende do tipo de dados:

• Para dados do tipo string, use os dados estatísticos como referência de dimensão em um relatório personalizado.
• Para tipos de dados numéricos (número inteiro/flutuante/longo/duplo), use os dados estatísticos em um relatório personalizado como referência de dimensão ou métrica.

Consulte a política StatisticsCollector para ver exemplos de coleta de dados de análise personalizados.

Como definir filtros

Um filtro permite limitar os dados de métricas exibidos no relatório personalizado definindo características específicas sobre os dados que serão retornados. Por exemplo, é possível criar um filtro para ver os dados de métricas somente para um tempo de resposta maior que um valor específico ou apenas para um proxy de API com um determinado nome.

Os filtros usam uma sintaxe condicional que permite criar filtros complexos usando operadores como eq, ne, gt, lt e etc.

Exemplos de relatórios personalizados

No tipo mais simples de relatório personalizado, você especifica uma única métrica e dimensão. Por exemplo, você define um relatório personalizado com as seguintes configurações:

• Tipo = Coluna
• Métrica = Média de transações por segundo
• Dimensão = Proxy de API

O relatório personalizado tem um gráfico de colunas com os dados da métrica "Média de transações por segundo" agrupados pela dimensão do proxy de API:

As métricas que exibem médias também incluem o link Mostrar dispersão à direita do gráfico, conforme apresentado no gráfico acima. Passe o cursor sobre o link para abrir a caixa de dispersão. Uma caixa de dispersão exibe as tendências principais dos seus dados.

É possível adicionar várias métricas a um relatório personalizado. Por exemplo, você define um relatório personalizado com duas métricas:

• Tipo = Coluna
• Métrica = Média de transações por segundo
• Métrica = Erros de política
• Dimensão = Proxy de API

O relatório personalizado contém um gráfico separado para cada métrica:

É possível adicionar várias dimensões a um relatório personalizado. Por exemplo, você define um relatório personalizado com as seguintes configurações, que incluem duas métricas e duas dimensões:

• Tipo = Coluna
• Métrica = Média de transações por segundo
• Métrica = Erros de política
• Dimensão = Proxy de API
• Dimensão = Verbo "request"

Inicialmente, o gráfico mostra as métricas agrupadas por proxy, a primeira dimensão que foi especificada quando você criou o relatório personalizado:

Use o menu suspenso Proxy, correspondente à primeira dimensão, para selecionar um proxy individual. No gráfico atualizado, agora aparecem as métricas do proxy selecionadas pelo verbo "request":

Conforme você adiciona dimensões ao relatório personalizado, a IU é ajustada para permitir o detalhamento do relatório por cada dimensão.

Como ver todos os relatórios personalizados

Acesse a página de relatórios personalizados, conforme descrito abaixo.

São exibidos todos os relatórios personalizados que foram criados para sua organização, conforme mostrado na figura a seguir:

Como destacado na figura, na página de relatórios personalizados, é possível:

• ver uma lista de todos os relatórios personalizados;
• adicionar um relatório personalizado;
• clicar no nome de um relatório na lista para personalizá-lo. Por padrão, o relatório é gerado usando os dados coletados na última hora, e os dados são exibidos no painel de relatórios personalizados. Consulte Como explorar o painel de relatórios personalizados;
• pesquisar a lista de relatórios personalizados inserindo toda ou parte de uma string relevante na caixa de pesquisa. A pesquisa pela string é feita em todos os campos exibidos;
• excluir um relatório personalizado.

Como explorar o painel de relatórios personalizados

O painel de relatórios personalizados exibe os resultados de um relatório personalizado durante um período específico, incluindo a coluna ou o gráfico de linhas da métrica especificada:

No painel de relatórios personalizados, é possível:

• ver os dados de relatórios personalizados referentes ao período selecionado;
• selecionar o Ambiente com os dados do relatório personalizado que você quer ver;
• selecionar uma dimensão específica para filtrar os dados do relatório personalizado. Essa área apenas será ativada quando você especificar várias dimensões para o relatório;

• selecionar a visualização gráfica ou em tabela;

• analisar uma métrica selecionando o ícone na linha da métrica associada na tabela; ver anomalias e compará-las com um período anterior ou com outras métricas;
• executar o relatório personalizado clicando e definindo o período;
• fazer o download do relatório personalizado como um arquivo CSV. O nome do arquivo é este: metric.csv. Por exemplo: Average_of_total_response_time.csv.
• editar o relatório personalizado.

Explorar o painel de análise de métricas

Se você selecionar o ícone em uma linha da tabela de resumo, os gráficos a seguir serão exibidos. O gráfico superior aparecerá apenas se você configurar o relatório para usar várias métricas:

Esses gráficos apresentam as seguintes informações:

• Comparar com: se você configurou o relatório para usar várias métricas, compare-as.
• Comparar com o período anterior: veja a métrica do período anterior. Por exemplo, se você quiser ver o relatório personalizado das últimas 24 horas, esse gráfico mostrará os dados desse período.

• Analisar anomalias: exibe os pontos de dados isolados nos dados do relatório. Este gráfico mostra dois valores:

  • A média móvel da métrica representada como uma linha. Para um determinado ponto na linha, o valor da média móvel é calculado como a média do valor da métrica nesse ponto no tempo e os valores da métrica dos dois pontos de dados anteriores.
  • A área azul do gráfico define os valores médios mínimo e máximo da métrica. A média máxima é de 1,2 * (média móvel) e a média mínima é de 0,8 * (média móvel).

  Se a média móvel estiver fora desse intervalo máximo ou mínimo, ela será considerada uma possível anomalia e representada como um ponto vermelho no gráfico.

Como adicionar um relatório personalizado

Se você adicionar relatórios personalizados, será possível criar um conjunto de gráficos com informações de todos os aspectos do seu programa de API.

Depois de adicionar o relatório personalizado, execute-o de maneira síncrona ou assíncrona.

Para adicionar um relatório personalizado:

1. Acesse a página "Relatórios personalizados".
2. Clique em + Relatório personalizado.
3. Na seção "Básico", digite as seguintes informações:

   Campo	Descrição
   Nome do relatório	Nome do relatório.
   Descrição do relatório	Descrição do relatório.
   Tipo de gráfico	Selecione o estilo do gráfico que será usado para apresentar os dados personalizados de análise. Coluna: o eixo X representa os grupos designados por dimensões. Linha: o eixo X representa o tempo.

4. Na seção "Métricas", faça o seguinte:
   1. Clique no ícone ao lado de Métricas.
   2. Selecione a métrica que você quer analisar.
   3. Selecione uma Função de agregação para exibir os valores de soma, média, mínimo ou máximo.
   4. Clique em Salvar.
   5. Clique no ícone para adicionar outras métricas.
5. Na seção Dimensões, clique em e selecione uma dimensão, como "Proxy", para restringir o conjunto de dados usado para gerar os relatórios. É possível adicionar outras dimensões para restringir ainda mais os dados.

6. Na seção Filtros, restrinja ainda mais os dados exibidos adicionando filtros à definição do relatório. Por exemplo, adicione um filtro que exclua os dados do proxy da API Weather ou da desenvolvedora jane@example.com.

   1. Clique em e selecione o nome da entidade que você quer filtrar, um operador como = ou != e um valor.
   2. Clique em Adicionar para salvar o filtro.
   3. Clique em para adicionar outros filtros e selecione um conector AND ou OR.

7. Para limitar quem pode acessar o relatório personalizado, edite os Papéis definidos no relatório.

   1. Clique em para editar as configurações de papel personalizado.
   2. Selecione o papel personalizado necessário para acessar o relatório e o nível de acesso (visualizar, editar, excluir).
   3. Clique em Adicionar.
   4. Clique em para editar outros papéis.
8. Clique em Salvar para salvar o relatório.

Como gerar um relatório personalizado

O Edge Analytics permite gerar um relatório de maneira síncrona ou assíncrona.

• Para um relatório síncrono, você executa a solicitação de relatório, e a solicitação fica bloqueada até o servidor de análise retornar uma resposta. No entanto, como um relatório pode precisar processar uma grande quantidade de dados (por exemplo, centenas de GB), um relatório síncrono pode expirar.

  Um relatório síncrono pode ter um período máximo de 14 dias. Se você selecionar um período de 15 dias ou mais, o relatório será sempre executado de forma assíncrona.

• Para um relatório assíncrono, você executa a solicitação de relatório e recupera os resultados posteriormente. Veja a seguir algumas situações em que o processamento de consulta assíncrona pode ser uma boa alternativa:

  • Análise e criação de relatórios que abrangem períodos longos
  • Análise de dados com uma variedade de dimensões de agrupamento e outras restrições que aumentam a complexidade da consulta
  • Gerenciamento de consultas quando você perceber que os volumes de dados aumentaram significativamente para alguns usuários ou organizações

  Neste documento, descrevemos como iniciar um relatório assíncrono usando a IU. A API também pode ser usada conforme descrito em Como usar a API de relatórios personalizados assíncronos.

Para gerar um relatório personalizado referente a um período específico:

1. Acesse a página "Relatórios personalizados".
2. Selecione o relatório que será gerado. Por padrão, o relatório exibe os dados da hora anterior.

3. Para gerar o relatório de um período diferente:

   1. Clique na área de período na parte superior do relatório para abrir o menu pop-up Seleção de período do relatório personalizado.
   2. Selecione uma destas opções:
      • Um período predefinido, como Última hora, Ontem ou Últimos 7 dias.

      • Um Intervalo personalizado, selecionando uma data e hora De/Até ou usando o calendário para selecionar as datas de início e de término. Clique em UTC para usar o fuso horário UTC.

   3. Para gerar o relatório, selecione uma destas opções:

      • Aplicar para gerar o relatório de maneira síncrona. Os resultados serão exibidos no painel de relatórios personalizados após a conclusão do relatório. Se o relatório levar mais de 60 segundos para ser gerado, ele será convertido automaticamente em um relatório assíncrono.

      • Enviar job para gerar o relatório de maneira assíncrona como um job em segundo plano. A seguinte caixa de diálogo é exibida:

        

        Clique em Visualizar status na caixa de diálogo para ver o status do job de relatório personalizado.

Como ver jobs de relatórios personalizados assíncronos

Para ver os jobs de relatórios personalizados assíncronos, selecione uma das seguintes opções:

• Clique em Visualizar status na caixa de diálogo "Relatório enviado como job em segundo plano".
• Selecione Analisar > Relatórios personalizados > Jobs de relatório na barra de navegação à esquerda.

A página "Jobs de relatório" é exibida, conforme mostrado na figura a seguir:

Na página "Jobs de relatório", é possível:

• ver todos os resultados de jobs de relatórios personalizados assíncronos que foram enviados nos últimos sete dias;

• selecionar o ambiente com os jobs de relatórios personalizados que você quer exibir.

• Para ver o relatório personalizado, verifique se o Status dele é "Concluído". Em seguida, passe o cursor do mouse sobre a linha correspondente ao relatório. Os ícones e são exibidos. Selecione para ver o relatório.

• Clique em para fazer o download do relatório personalizado.

  O download do relatório completo é feito como um arquivo ZIP chamado OfflineQueryResult-xxx.zip, que contém os arquivos CSV.

• Pesquise na lista de relatórios personalizados inserindo a string inteira ou parte dela na caixa de pesquisa. A pesquisa pela string é feita em todos os campos exibidos.

Como editar um relatório personalizado

Para editar um relatório personalizado:

1. Acesse a página "Relatórios personalizados".
2. Mova o cursor do mouse sobre o nome do relatório que você quer editar. Os ícones de edição e de exclusão aparecem no lado direito da página.
3. Clique no ícone de edição.
4. Edite os detalhes do relatório personalizado.
5. Clique em Salvar.

Você verá os resultados do relatório personalizado.

Como excluir um relatório personalizado

Para excluir um relatório personalizado:

1. Acesse a página "Relatórios personalizados".
2. Mova o cursor do mouse sobre o nome do relatório que você quer editar. Os ícones de edição e de exclusão aparecem no lado direito da página.
3. Clique no ícone de exclusão para excluir o relatório.