Plug-in StatsD

O StatsD é um protocolo para envio de métricas e um daemon para agregação de dados de métricas. Ao configurar o plug-in StatsD, o agente do Monitoring funciona como um daemon que grava métricas no Monitoring.

Usar o plug-in StatsD com a configuração padrão é a forma mais fácil de adquirir as métricas definidas pelo usuário para o Monitoring. O plug-in StatsD está disponível apenas no agente do Stackdriver Monitoring para Linux.

O agente do Monitoring também pode exportar outros dados definidas pelo usuário, mas não há uma configuração padrão simples. Consulte Métricas definidas pelo usuário pelo agente para mais detalhes.

Essa funcionalidade está disponível apenas para agentes em execução no Linux. Não está disponível no Windows.

Discovery

O Monitoring não detecta automaticamente o StatsD. Para usar as métricas do StatsD, configure o plug-in conforme descrito na próxima seção.

Como configurar o plug-in StatsD

Pré-requisitos

O plug-in StatsD requer a versão 5.5.2-356 ou posterior do agente do Monitoring. Para atualizar o agente, consulte esta página.

Como ativar o plug-in

Faça o seguinte na instância de VM compatível em execução no Linux:

  1. Faça o download de statsd.conf (em inglês) e coloque-o em /etc/stackdriver/collectd.d/, usando o seguinte comando:

    (cd /etc/stackdriver/collectd.d/ && sudo curl -O https://raw.githubusercontent.com/Stackdriver/stackdriver-agent-service-configs/master/etc/collectd.d/statsd.conf)
    
  2. O arquivo de configuração padrão instrui o agente a aceitar as métricas do StatsD na porta padrão dele, 8125.

    Se quiser enviar algumas métricas para o próprio daemon do StatsD e outras para o daemon do agente, altere as definições da porta no arquivo de configuração.

  3. Reinicie o agente do Monitoring para selecionar a configuração do StatsD executando o seguinte comando:

    sudo service stackdriver-agent restart
    

Para mais informações sobre o plug-in collectd statsd, consulte Plugin:StatsD (em inglês).

Mapeamento padrão para métricas definidas pelo usuário

Para começar rapidamente, o plug-in StatsD do agente vem com um Configuração do collectd que mapeia das métricas do StatsD para o Stackdriver definidas pelo usuário:

  • Todas as métricas do plug-in StatsD têm statsd no componente plugin do collectd.

  • Cada tipo de métrica do StatsD, localizado no type do collectd componente: tem um nome de tipo de métrica correspondente definido pelo usuário.

  • O nome da métrica do StatsD, retido no componente type_instance do collectd, é armazenado como o valor de um rótulo denominado metric.

    O valor do rótulo metric é diferente para o tipo de métrica Timer. Ele inclui o nome da métrica e o nome do contador: average, upper, lower, sum, percentile-50 e percentile-95.

Por exemplo, a tabela a seguir mostra como os tipos de métrica compatíveis do StatsD e o nome da métrica são mapeados nas métricas definidas pelo usuário do Monitoring:

Tipo de StatsD Nome do StatsD Tipo de métrica do Stackdriver Classe da métrica Tipo de valor Marcadores da métrica
Counter my.counter custom.googleapis.com/statsd/derive Cumulative Int64 metric:my.counter
Gauge my.gauge custom.googleapis.com/statsd/gauge Gauge Double metric:my.gauge
Set my.set custom.googleapis.com/statsd/objects Gauge Double metric:my.set
Timer1 my.timer custom.googleapis.com/statsd/latency Gauge Double metric:my.timer-average
(igual) (igual) (igual) metric:my.timer-upper
(igual) (igual) (igual) metric:my.timer-lower
(igual) (igual) (igual) metric:my.timer-sum
(igual) (igual) (igual) metric:my.timer-percentile-50
(igual) (igual) (igual) metric:my.timer-percentile-95
custom.googleapis.com/statsd/gauge Gauge (igual) metric:my.timer-count

Observações:
1 Há uma sequência de entrada relativa a métricas de tempo do StatsD com o mesmo nome. O agente as agrega e exporta os dados de resumo para sete séries temporais diferentes.

Para saber mais sobre os tipos de StatsD, consulte a Especificação do StatsD.

Como personalizar as métricas exportadas

A configuração padrão do StatsD foi projetada para que você comece rapidamente. Nesta seção, você aprende a personalizar a configuração para atender a necessidades mais complexas.

Você precisa conhecer as métricas definidas pelo usuário. Para uma introdução às métricas, consulte Métricas, séries temporais e recursos. Para mais informações, consulte Visão geral das métricas definidas pelo usuário.

É possível personalizar o seguinte:

  • É possível alterar os valores atribuídos ao rótulo metric padrão. Usar mais valores de rótulo resulta em mais série temporal na métrica definida pelo usuário. Usar menos valores de rótulo resulta em menos série temporal.

  • É possível mudar os tipos de métricas definidas pelo usuário. Não é necessário usar o método predefinidos fornecidos na configuração padrão. Por exemplo, identifique as métricas com um determinado nome e use um tipo de métrica definido pelo usuário diferente para elas.

  • Se você alterar os tipos de métrica definidos pelo usuário, também será possível os rótulos associados a cada tipo. A configuração padrão tem um único rótulo, mas é possível alterar a chave dele ou adicionar outros rótulos.

Se você alterar os tipos de métrica, deverá definir sua nova métrica definida pelo usuário na API Monitoring. Para mais detalhes, consulte a seção a seguir: Como projetar um tipo de métrica.

Exemplo

Suponha que você esteja usando o StatsD para monitorar um aplicativo que consiste em dois serviços, my_service_a e my_service_b. Em cada serviço, você quer exportar para o Monitoring uma métrica de contador que representa o número de solicitações com falha, mas não quer usar os tipos de métrica padrão do StatsD.

Métricas de entrada do collectd

Antes de definir os próprios tipos de métrica, é importante entender a estrutura de uma métrica coletada e como uma métrica do StatsD é mapeada para métricas definidas pelo usuário por padrão.

As métricas do collectd, incluindo as do StatsD, contam com os seguintes componentes:

    Host, Plugin, Plugin-instance, Type, Type-instance

Neste exemplo, as métricas do StatsD que você quer exportar têm os seguintes identificadores no collectd:

Componente Valores esperados
Host qualquer um
Plug-in statsd
Instância do plug-in não definido1
Tipo derive2
Instância de tipo [SERVICE_NAME].GET.[CODE]3
[VALUE] qualquer valor4

Observações:
1 No momento, o plug-in StatsD deixa esse componente em branco.
2 Uma métrica de contador do StatsD é mapeada no tipo derive de collectd. 3 Por exemplo, uma instância de tipo pode ser my_service_a.GET.500. 4 [VALUE] costuma ser um carimbo de data/hora e um número de dupla precisão.

A tabela a seguir mostra como esta métrica é mapeada por padrão:

Tipo de StatsD Nome do StatsD Tipo de métrica do Stackdriver Classe da métrica Tipo de valor Marcadores da métrica
Counter my_service_a.GET.500 custom.googleapis.com/statsd/derive Cumulative Int64 metric:my_servce_a.GET.500
Counter my_service_b.GET.403 custom.googleapis.com/statsd/derive Cumulative Int64 metric:my_servce_b.GET.403

Talvez você tenha dificuldades no mapeamento padrão:

  • Essa métrica de contador específica ([SERVICE_NAME].GET.[CODE]) está no mesmo definido pelo usuário como todas as outras métricas de contador. Não é fácil conseguir apenas os dados dessa métrica porque o Stackdriver não é compatível atualmente com pesquisas de expressões regulares nos rótulos.

  • Não é fácil conseguir dados para serviços individuais ou códigos de resposta individuais nos seus dados. Por exemplo, não é fácil conseguir o número total de erros (de todos os tipos) que ocorreram em my_service_a.

  • A configuração padrão exporta todas as métricas do StatsD para o Stackdriver. Esse pode ser um processo caro para você se estiver interessado apenas em determinadas métricas.

Como projetar um tipo de métrica

Para informações completas sobre a criação de tipos de métrica, consulte Criar um tipo de métrica definido pelo usuário.

O tipo de métrica definido pelo usuário a seguir é uma opção razoável para os dados neste exemplo, porque ele contém apenas a métrica do StatsD do seu interesse e porque a escolha dos rótulos ajuda a organizar melhor os dados:

  • Tipo: custom.googleapis.com/http/request_errors
  • Rótulos:
    • service_name (STRING): o nome do serviço
    • response_code (INT64): o código de resposta HTTP
  • Tipo: CUMULATIVE
  • Tipo de valor: INT64

A tabela a seguir mostra o mapeamento desejado do StatsD para o Stackdriver:

Tipo de StatsD Nome do StatsD Tipo de métrica do Stackdriver Classe da métrica Tipo de valor Marcadores da métrica
Counter my_service_a.GET.500 custom.googleapis.com/http/request_errors Cumulative Int64 service_name:my_service_a, response_code:500
Counter my_service_b.GET.403 custom.googleapis.com/http/request_errors Cumulative Int64 service_name:my_service_b, response_code:403

Depois de projetar o tipo de métrica, use metricDescriptors.create para criá-lo. Para mais informações sobre como o Monitoring pode criar o tipo de métrica para você, consulte Criação automática de descritores de métrica.

Configuração do mapeamento

Para exportar a métrica do StatsD para o novo tipo de métrica definida pelo usuário, substitua o conteúdo da configuração padrão do plug-in StatsD, /etc/stackdriver/collectd.d/statsd.conf, pelo seguinte código:

<Plugin statsd>
  Host "127.0.0.1"
  Port "8125"
  DeleteSets true
  TimerPercentile 50.0
  TimerPercentile 95.0
  TimerLower true
  TimerUpper true
  TimerSum true
  TimerCount true
</Plugin>

LoadPlugin match_regex
LoadPlugin target_set
LoadPlugin target_replace

# Insert a new rule in the default "PreCache" chain, to divert your metrics.
PreCacheChain "PreCache"
<Chain "PreCache">
  # The following rule does all the work for your metric:
  <Rule "rewrite_request_errors">
    # Do a careful match for just your metrics; if it fails, drop down
    # to the next rule:
    <Match regex>
      Plugin "^statsd$"
      TypeInstance "^.*\\.GET\\..*$"    # Match on type instance.
    </Match>

    <Target "set">
      # Specify the metric descriptor type:
      MetaData "stackdriver_metric_type" "custom.googleapis.com/http/request_errors"
      # Initialize the labels from the "type_instance" label; clean the values up in the next Target below.
      MetaData "label:service_name" "%{type_instance}"
      MetaData "label:response_code" "%{type_instance}"
    </Target>

    <Target "replace">
      # Remove ".GET.[code]" to get the real service name.
      MetaData "label:service_name" "\\.GET\\.[0-9]*$" ""
      # Remove "[service].GET." to get the real response code.
      MetaData "label:response_code" "^[^\\.]*\\.GET\\." ""
    </Target>
  </Rule>
</Chain>

Reiniciar o agente

Reinicie o agente para escolher a nova configuração. Basta executar o seguinte comando na instância de VM:

sudo service stackdriver-agent restart

As informações da métrica definidas pelo usuário começam a ser transmitidas para o Monitoring imediatamente.

Próximas etapas

A personalização do plug-in StatsD é igual à personalização de métricas do collectd no Monitoring. Para mais informações, consulte as seções "Referência" e "Solução de problemas" em Métricas definidas pelo usuário do agente.