As métricas personalizadas permitem que você acompanhe qualquer coisa significativa em sua aplicação — desde o número de usuários ativos em um determinado momento, até quantas faturas foram geradas na última hora, ou o tamanho atual do seu banco de dados. Ao enviar métricas personalizadas para o AppSignal, você pode criar gráficos em seus dashboards que relacionam esses dados a sinais críticos como taxas de erro e tempos de resposta, fornecendo contexto para identificar e resolver problemas rapidamente.Além disso, as métricas personalizadas ajudam você a trabalhar proativamente em vez de reativamente. Enquanto o logging ajuda a depurar problemas depois que ocorrem, as métricas personalizadas permitem que você detecte tendências e problemas potenciais antes que seus clientes percebam. Você pode se concentrar nos dados que importam para o seu negócio — como contagens de usuários ativos, KPIs ou volumes de vendas — sem ter que filtrar linhas de log ou listas de incidentes. Você também pode definir gatilhos em métricas personalizadas para avisá-lo quando os valores ficarem fora dos intervalos esperados.As métricas personalizadas não são uma substituição para instrumentação personalizada, mas uma ferramenta complementar para tornar dados específicos da aplicação visíveis e mensuráveis ao longo do tempo.O AppSignal oferece três tipos de métricas personalizadas:
Um gauge registra um valor em um ponto específico no tempo. Se você reportar vários gauges com a mesma chave dentro da mesma janela de tempo, apenas o último valor é persistido.Use gauges quando você quer saber o estado atual de algo — o número de itens que existem agora, ou o tamanho atual de um recurso. Todas as métricas de host do AppSignal são armazenadas como gauges.Gauges são frequentemente usados com minutely probes para reportar periodicamente um valor instantâneo, como consultar o número de carrinhos de compras recentemente ativos ou conexões de banco de dados abertas a cada minuto.Exemplos: contagem de usuários ativos, tamanho do banco de dados, uso de disco, número de conexões abertas.
# O primeiro argumento é uma string, o segundo argumento um número# Appsignal.set_gauge(metric_name, value)Appsignal.set_gauge("database_size", 100)Appsignal.set_gauge("database_size", 10)# Criará a métrica "database_size" com o valor 10
A partir da versão 3.1.0, a integração Node.js permite que você defina gauges e counters usando o provedor de métricas OpenTelemetry. Você deve habilitar o servidor HTTP OpenTelemetry do agente para reportar essas métricas ao AppSignal; você pode fazer isso definindo a opção enableOpentelemetryHttp como true.As integrações Java e Go também usam métricas OpenTelemetry para reportar métricas personalizadas ao AppSignal.Você pode ler mais sobre métricas OpenTelemetry na documentação de métricas OpenTelemetry. Para Node.js, veja a documentação de métricas OpenTelemetry JS para mais informações.
Um measurement rastreia uma dispersão de valores ao longo do tempo. O AppSignal armazena a média e a contagem para cada janela de tempo, permitindo que você crie gráficos como duração média, percentil 90/95 e throughput.Use measurements quando você está registrando um valor que varia entre eventos individuais e quer entender sua distribuição — não apenas seu valor atual. Por exemplo, você pode rastrear a duração de um job de background crítico (como e-mails de confirmação de pedido) para detectar lentidões antes que afetem seus usuários.Uma métrica measurement cria vários campos de métrica:
Count: quantas vezes o helper foi chamado. Útil para gráficos de throughput.
Mean: o valor médio da métrica para o ponto no tempo.
90th percentile: o percentil 90 do valor da métrica para o ponto no tempo.
95th percentile: o percentil 95 do valor da métrica para o ponto no tempo.
Exemplos: tempos de resposta HTTP, durações de jobs em background, valores de carrinhos de usuários, tempos de execução de queries.
# O primeiro argumento é uma string, o segundo argumento um número# Appsignal.add_distribution_value(metric_name, value)Appsignal.add_distribution_value("memory_usage", 100)Appsignal.add_distribution_value("memory_usage", 110)# Criará uma métrica "memory_usage" com o valor do campo mean 105# Criará uma métrica "memory_usage" com o valor do campo count 2
Um counter acumula uma contagem total durante uma janela de tempo. Os valores do counter são somados para cada resolução — então na resolução de minuto ele mostra o total para esse minuto, e na resolução de hora ele mostra o total para essa hora.Use counters quando você quer acompanhar quantas vezes algo aconteceu, não que valor teve. Counters são especialmente úteis para monitorar a frequência de eventos críticos para o negócio. Por exemplo, ao rastrear tanto pedidos feitos quanto faturas criadas, você pode verificar se esses counters relacionados permanecem sincronizados e detectar discrepâncias precocemente.Quando o helper é chamado várias vezes, o total/soma de todas as chamadas é persistido. Counters são não-monotônicos: tanto valores positivos quanto negativos são suportados, então você pode incrementar e decrementar o mesmo counter. Para counters monotônicos de outros sistemas, não há validação de que os valores do counter só aumentem.Exemplos: pedidos feitos, faturas criadas, logins de usuários, jobs em background enfileirados, tentativas de pagamento falhas.
Gauge vs. Counter: Use um gauge para rastrear quantos de algo existem
agora (por exemplo, usuários atualmente ativos). Use um counter para rastrear quantas vezes
algo aconteceu em um determinado período (por exemplo, novos logins no último minuto).
# O primeiro argumento é uma string, o segundo argumento um número# Appsignal.increment_counter(metric_name, value)Appsignal.increment_counter("login_count", 1)Appsignal.increment_counter("login_count", 1)# Criará a métrica "login_count" com o valor 2 para um ponto na resolução de minuto/hora
Nota: No AppSignal, counters são projetados para armazenar apenas valores inteiros.
Embora a API aceite valores float para facilitar a integração, esses valores são convertidos internamente para inteiros.Valores decimais são arredondados para baixo, para o inteiro mais próximo.
O valor 0.0001 se torna 0, e 1.2, 1.5 e 1.7 se tornam 1.
Recomendamos nomear suas métricas de forma facilmente reconhecível. Embora você possa usar curinga em partes do nome da métrica para criação de dashboards, recomendamos usar isso apenas para pequenos agrupamentos e não usar IDs em nomes de métricas.Os nomes de métricas suportam apenas números, letras, pontos e sublinhados ([a-z0-9._]) como caracteres válidos. Quaisquer outros caracteres serão substituídos por um sublinhado pelo nosso processador. Você pode encontrar a lista de métricas conforme processadas em “Add Dashboard”.Alguns exemplos de bons nomes de métricas são:
database_size
account_count
users.count
notifier.failed
notifier.perform
notifier.success
Por padrão, o AppSignal já rastreia métricas para sua aplicação, como métricas de host. Veja a lista de métricas na página “Add Dashboard” para as métricas que já estão disponíveis para sua aplicação.
Nota: Não recomendamos adicionar valores dinâmicos aos seus nomes de métricas
assim: eu.database_size, us.database_size e asia.database_size. Isso
cria várias métricas que servem ao mesmo propósito. Em vez disso, recomendamos
usar tags de métrica para isso.
Métricas suportam apenas números como valores válidos. Qualquer outro valor será silenciosamente ignorado ou gerará um erro conforme acionado pelo parser de números da linguagem de implementação. Para Ruby e Elixir suportamos double e integer como valores válidos:
Os gráficos do AppSignal têm vários formatos de exibição, como números, tamanhos de arquivo, durações,
etc. Esses formatos ajudam na apresentação dos valores das métricas de uma forma legível por humanos.Selecionar uma entrada de formatador de valor não afeta os dados armazenados em nossos sistemas, apenas como ele é exibido.Para mostrar os valores das métricas corretamente usando esses formatadores, por favor verifique a tabela abaixo de como o valor deve ser reportado.
Formatador
Valor reportado
Descrição
Number
Valor de exibição
Um número formatado de forma legível por humanos. Os valores devem ser reportados na mesma escala em que são exibidos. O valor 1 é exibido como “1”, 10_000 como “10 K” e 1_000_000 é exibido como “1 M”.
Percentage
Valor de exibição
Um valor de métrica formatado como porcentagem. Os valores devem ser reportados na mesma escala em que são exibidos. O valor 40 é exibido como “40 %”.
Throughput
Valor de exibição
Um valor de métrica formatado como requisições por minuto/hora. Os valores devem ser reportados na mesma escala em que são exibidos. Exibirá o throughput formatado como um número tanto para o minuto quanto para a hora. O valor 10_000 é exibido “10k / hour 166 / min”. Comumente usado para métricas counter.
Duration
Milissegundos
Uma duração de tempo. Os valores devem ser reportados como milissegundos. O valor 100 é exibido como “100 ms” e 60_000 como “60 sec”. Comumente usado para a métrica measurement.
Um tamanho de arquivo formatado como megabytes por padrão. 1.0 megabytes é exibido como 1Mb. Em qual unidade de tamanho de arquivo o valor da métrica reportada é lido pode ser personalizado no graph builder.
Valores de métrica que representam um tamanho de arquivo podem usar o formatador de tamanho de arquivo. Para especificar qual unidade de tamanho o valor reportado representa, o formatador de tamanho de arquivo permite vários valores de entrada.As opções disponíveis são:
Size in Bit
Size in Bytes
Size in Kilobits
Size in Kilobytes
Size in Megabytes
Ao enviar uma métrica com o seguinte valor:
Appsignal.set_gauge("database_size", 1024)
O gráfico renderizará o seguinte valor de exibição para o formatador de tamanho de arquivo especificado:
As tags de métricas personalizadas requerem a seguinte versão do pacote/gem do AppSignal ou
superior:
Gem Ruby versão 2.6.0
Pacote Elixir 1.6.0
Pacote Node.js 1.0.0
Pacote Python 0.3.0
Uma única métrica pode consistir em vários grupos de dados; por exemplo, uma métrica personalizada ‘total_orders’ poderia consistir em pedidos pendentes e processados.Você pode adicionar várias tags às métricas para insights mais profundos sobre os dados da métrica que o AppSignal está reportando. Cada tag será representada por sua linha em um gráfico do AppSignal.Por padrão, os helpers de métrica do AppSignal não definem tags em uma métrica personalizada.Como você pode usar tags em gráficos do AppSignal:Tags podem “rotular” uma linha na legenda do gráfico, facilitando a visualização do que cada linha representa quando você passa o mouse sobre elas.
A filtragem com tags pode mostrar a mesma métrica em contextos diferentes em gráficos diferentes.Para aproveitar ao máximo as tags de métricas, aconselhamos o seguinte:
Seja consistente com a marcação: Para rastreamento e legibilidade ótimos do gráfico, recomendamos não reportar uma métrica personalizada tanto com quanto sem tags. Reportar a mesma métrica de maneiras diferentes pode criar confusão e dificultar a interpretação precisa dos dados.
Sempre use as mesmas tags de métrica quando: Recomendamos usar a mesma combinação de tags sempre que você reportar uma métrica. Por exemplo, se uma métrica usa tags A e B em uma área da sua aplicação, ela deve usá-las em todas as áreas. Evite alterar as tags, pois a marcação consistente facilitará a criação de gráficos.
Use um intervalo limitado de valores para tags de métricas: Para evitar gráficos excessivamente complexos ou ilegíveis, recomendamos usar um intervalo limitado de tags em suas métricas personalizadas, como regiões (EU, US e Ásia). Você pode realizar uma análise mais ampla dos dados de métrica da sua aplicação ao usar um intervalo limitado e preciso de tags para todos os dados de métrica da sua aplicação.
Em geral, ao implementar a marcação de métricas, considere desenvolver uma estratégia robusta de marcação que possa ser aplicada de forma consistente em toda a sua aplicação e que precisará de pouco ou nenhum ajuste a longo prazo.
Se você criou uma métrica personalizada e tem várias tags associadas a ela, você pode renderizar a métrica com e sem a tag ao mesmo tempo em um gráfico.
Uma vez que você começou a registrar métricas personalizadas, pode rastreá-las em gráficos personalizados usando o Graph Builder. Navegue até um dashboard existente ou use o botão “Add dashboard” na navegação do Dashboard para criar um novo e depois clique em “Add graph”.Ao criar um gráfico, você pode selecionar quais métricas e tags deseja exibir e configurar as legendas e rótulos do seu gráfico. Uma vez criado, o gráfico será adicionado ao dashboard e exibirá todos os dados de métricas personalizadas registrados para o período de tempo especificado.Você pode ler mais sobre dashboards e gráficos em nossa documentação de Dashboards.
