Métricas personalizadas do agente

Este guia explica como você pode configurar o agente do Monitoring para reconhecer e exportar as métricas de seu aplicativo para o Cloud Monitoring.

O agente do Monitoring é um daemon do collectd Além de exportar muitas métricas predefinidas do sistema e de terceiros para o Cloud Monitoring, o agente pode exportar suas próprias métricas do aplicativo collectd para o Monitoring como métricas personalizadas. Seus plug-ins do collectd também podem ser exportados para o Monitoring.

Uma maneira alternativa de exportar métricas do aplicativo para o Monitoring é usar StatsD. O Cloud Monitoring fornece uma configuração padrão que mapeia as métricas do StatsD para métricas personalizadas. Se o mapeamento é suficiente para você, não é necessário passar pelas etapas de personalização descritas abaixo. Para saber mais, consulte o plug-in do StatsD.

Se você não conhece as métricas personalizadas do Monitoring, consulte Métricas, série temporal e recursos, Estrutura da série temporal e Uso de métricas personalizadas.

Antes de começar

  • Instale o agente do Monitoring mais recente em uma instância de VM e verifique se ele está funcionando. Para atualizar o agente, consulte esta página.

  • Configure o collectd para receber dados de monitoramento do aplicativo. Ele é compatível com muitas estruturas de aplicativo e endpoints de monitoramento padrão por meio dos plug-ins de leitura dele. Encontre um plug-in de leitura que funcione com sua configuração.

  • (Opcional) Para ter maior comodidade, adicione a documentação de referência do collectd do agente às páginas man do sistema. Basta atualizar a variável MANPATH e executar mandb:

    export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
        sudo mandb
        

    As páginas do manual são para stackdriver-collectd.

Diretórios e arquivos importantes

Criados durante a instalação do agente do Monitoring (collectd), os diretórios e os arquivos a seguir são importantes para usá-lo:

/etc/stackdriver/collectd.conf

O arquivo de configuração do collectd usado pelo agente. Edite esse arquivo para alterar a configuração geral.

/etc/stackdriver/collectd.d/

O diretório dos arquivos de configuração adicionados pelo usuário. Para enviar métricas personalizadas do agente, coloque os arquivos de configuração necessários nesse diretório. Os arquivos são abordados abaixo. Para compatibilidade com versões anteriores, o agente também procura por arquivos em /opt/stackdriver/collectd/etc/collectd.d/.

/opt/stackdriver/collectd/share/man/*

A documentação da versão do agente do collectd. Adicione essas páginas ao conjunto de páginas man do sistema. Consulte Antes de começar para ver os detalhes.

/etc/init.d/stackdriver-agent

O script de init do agente.

Como o Monitoring processa métricas do collectd

O agente processa as métricas do collectd em segundo plano e as envia para o Monitoring, que processa cada métrica como um membro de uma destas categorias:

  • Métricas personalizadas: as métricas do collectd que têm a chave de metadados stackdriver_metric_type e uma única origem de dados são tratadas como métricas personalizadas e enviadas para o Monitoring usando o método projects.timeSeries.create na API Monitoring.

  • Métricas selecionadas: Todas as outras métricas do collectd são enviadas para o Monitoring usando uma API interna. Somente as métricas na lista de métricas selecionadas são aceitas e processadas.

  • Métricas descartadas: O Monitoring descarta as métricas do collectd que não estão na lista de métricas selecionadas e não são personalizadas. O próprio agente desconhece quais métricas são aceitas ou descartadas.

Como gravar métricas personalizadas com o agente

Configure o agente para enviar pontos de dados de métricas ao Monitoring. Cada ponto precisa estar associado a uma métrica personalizada que você define com um descritor de métrica. Esses conceitos são apresentados em métricas, séries temporais e recursos e descritos em detalhes em Estrutura de séries temporais e Uso de métricas personalizadas.

É possível gerenciar uma métrica do collectd como uma métrica personalizada. Basta adicionar os metadados adequados a ela:

  • stackdriver_metric_type: (obrigatório) o nome da métrica exportada. Exemplo: custom.googleapis.com/my_custom_metric.

  • label:[LABEL]: (opcional) rótulos a mais para a métrica exportada. Por exemplo, se você quiser um rótulo de Monitoramento STRING chamado color, sua chave de metadados será label:color e o valor da chave será "blue". É possível ter até 10 rótulos por tipo de métrica.

É possível usar uma cadeia de filtros do collectd para modificar os metadados das métricas. Como as cadeias de filtro não podem alterar a lista de fontes de dados, e as métricas personalizadas são compatíveis apenas com uma única fonte de dados, quaisquer métricas do collectd que você queira usar com essa instalação precisam ter uma única fonte de dados.

Exemplo

Neste exemplo, monitoraremos as conexões Nginx ativas de dois serviços Nginx, my_service_a e my_service_b. Elas serão enviadas ao Monitoring por meio de uma métrica personalizada. Seguiremos estas etapas:

  1. Identificar as métricas do collectd para cada serviço do Nginx.

  2. Definir um descritor de métrica do Monitoring.

  3. Configurar uma cadeia de filtros do collectd para adicionar metadados às métricas do collectd e atender às expectativas do agente do Monitoring.

Métricas de entrada do collectd

Para o collectd, as métricas precisam incluir os seguintes componentes. Os cinco primeiros componentes formam o identificador do collectd para a métrica:

        Host, Plugin, Plugin-instance, Type, Type-instance, [value]
    

Neste exemplo, as métricas que você quer enviar como uma métrica personalizada têm os seguintes valores:

Componente Valores esperados
Host qualquer um
Plug-in curl_json
Instância do plug-in nginx_my_service_a ou
nginx_my_service_b1
Tipo gauge
Instância de tipo active-connections
[value] qualquer valor2

Anotações:
1 no exemplo, esse valor codifica o aplicativo (Nginx) e o nome do serviço conectado.
2 O valor costuma ser um carimbo de data/hora e um número de dupla precisão. O Monitoring gerencia os detalhes de interpretação das várias classes de valores. No momento, valores compostos não são aceitos pelo agente do Monitoring.

Descritor de métrica e série temporal do Monitoring

No Monitoring, crie um descritor para a métrica personalizada. O descritor a seguir é uma ótima opção para os dados neste exemplo:

  • Nome: custom.googleapis.com/nginx/active_connections
  • Rótulos:
    • service_name (STRING): o nome do serviço conectado ao Nginx.
  • classe: GAUGE
  • tipo: DOUBLE

Depois de criar o descritor de métrica, você pode criá-lo usando projects.metricDescriptors.create ou permitir que ele seja criado a partir dos metadados de série temporal abordados abaixo. Para saber mais, consulte Como criar descritores de métrica nesta página.

Por conta da forma como o descritor de métrica é definido, os dados da série temporal dele precisam conter as informações a seguir:

  • Nome da métrica: custom.googleapis.com/nginx/active_connections
  • Valores de rótulo da métrica:
    • service_name: é "my_service_a" ou "my_service_b"

Outras informações da série temporal, incluindo o recurso monitorado associado (a instância de VM que envia os dados) e o ponto de dados da métrica, são recebidas automaticamente pelo agente para todas as métricas. Você não precisa fazer nada especial.

Cadeia de filtros

Crie um arquivo, /opt/stackdriver/collectd/etc/collectd.d/nginx_curl_json.conf, contendo o seguinte código:

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">
      <Rule "jump_to_custom_metrics_from_curl_json">
        # If the plugin name and instance match, this is PROBABLY a metric we're looking for:
        <Match regex>
          Plugin "^curl_json$"
          PluginInstance "^nginx_"
        </Match>
        <Target "jump">
          # Go execute the following chain; then come back.
          Chain "PreCache_curl_json"
        </Target>
      </Rule>
      # Continue processing metrics in the default "PreCache" chain.
    </Chain>

    # Following is a NEW filter chain, just for your metric.
    # It is only executed if the default chain "jumps" here.
    <Chain "PreCache_curl_json">

      # The following rule does all the work for your metric:
      <Rule "rewrite_curl_json_my_special_metric">
        # Do a careful match for just your metrics; if it fails, drop down
        # to the next rule:
        <Match regex>
          Plugin "^curl_json$"                   # Match on plugin.
          PluginInstance "^nginx_my_service_.*$" # Match on plugin instance.
          Type "^gauge$"                         # Match on type.
          TypeInstance "^active-connections$"    # Match on type instance.
        </Match>

        <Target "set">
          # Specify the metric descriptor name:
          MetaData "stackdriver_metric_type" "custom.googleapis.com/nginx/active_connections"
          # Specify a value for the "service_name" label; clean it up in the next Target:
          MetaData "label:service_name" "%{plugin_instance}"
        </Target>

        <Target "replace">
          # Remove the "nginx_" prefix in the service_name to get the real service name:
          MetaData "label:service_name" "nginx_" ""
        </Target>
      </Rule>

      # The following rule is run after rewriting your metric, or
      # if the metric wasn't one of your custom metrics. The rule returns to
      # the default "PreCache" chain. The default processing
      # will write all metrics to Cloud Monitoring,
      # which will drop any unrecognized metrics: ones that are not
      # in the list of curated metrics and do not have
      # the custom metric metadata.
      <Rule "go_back">
        Target "return"
      </Rule>
    </Chain>
    

Carregar a nova configuração

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 personalizada começarão a ser transmitidas para o Monitoring.

Referência e práticas recomendadas

Descritores de métrica e séries temporais

Para uma introdução sobre as métricas do Cloud Monitoring, consulte Métricas, série temporal e recursos. Mais detalhes estão disponíveis em Como usar métricas personalizadas e Estrutura da série temporal.

Descritores de métrica. Eles contêm estas partes importantes:

  • Um nome do formulário custom.googleapis.com/[NAME1]/.../[NAME0]. Exemplo:

    custom.googleapis.com/my_measurement
        custom.googleapis.com/instance/network/received_packets_count
        custom.googleapis.com/instance/network/sent_packets_count
        

    Os nomes de métricas personalizadas precisam começar com custom.googleapis.com/. A nomeação recomendada é hierárquica para possibilitar que as pessoas acompanhem as métricas com mais facilidade. Os nomes das métricas não podem conter hífens. Para ver as regras de nomenclatura exatas, consulte Como nomear tipos de métrica e rótulos.

  • Até 10 rótulos para fazer uma anotação nos dados da métrica, como device_name, fault_type ou response_code. Os valores dos marcadores não são especificados no descritor de métrica.

  • A classe e o tipo dos pontos de dados, como "um valor de medidor do tipo duplo". Para mais informações, consulte MetricKind e ValueType.

Série temporal. Um ponto de dados de métricas tem estas partes importantes:

  • O nome do descritor de métrica associado.

  • Valores para todos os marcadores do descritor de métrica.

  • Um valor de data/hora consistente com o tipo e classe do descritor de métrica.

  • O recurso monitorado de origem dos dados, normalmente uma instância de VM. O espaço do recurso é interno. Portanto, o descritor não precisa de um marcador separado para ele.

Como criar descritores de métrica

Você não precisa criar um descritor de métrica com antecedência. Quando um ponto de dados chega ao Monitoring, você pode usar o valor, os marcadores e o nome da métrica do ponto para criar automaticamente um medidor ou um descritor de métrica cumulativo. Para saber mais, consulte Criação automática de métricas personalizadas.

No entanto, você aproveita algumas vantagens ao criar o próprio descritor de métrica:

  • É possível incluir documentação inteligente para a métrica e os marcadores dela.

  • É possível especificar classes e tipos adicionais de métricas. As únicas combinações deles compatíveis com o agente são (GAUGE, DOUBLE) e (CUMULATIVE, INT64). Para saber mais, consulte Classes de métricas e tipos de valores.

  • É possível especificar tipos de rótulos diferentes de STRING.

Se você gravar um ponto de dados no Monitoring que use um nome de métrica não definido, será criado um novo descritor de métrica para o ponto de dados. Isso pode ser um problema quando você está depurando o código que grava dados de métricas. Erros de ortografia no nome da métrica resultam em descritores de métrica falsos.

Depois que você cria um descritor de métrica ou ele é criado para você, não é possível alterá-lo. Por exemplo, não é possível adicionar ou remover marcadores. Você só pode excluir o descritor de métrica, o que remove todos os dados dele. Em seguida, recrie o descritor da maneira que quiser.

Para ver mais detalhes sobre como criar descritores de métrica, consulte Como definir a métrica.

Custos e limites

O Cloud Monitoring cobra pelas métricas do conjunto, definidas pelo usuário e pelas métricas do agente, com base no volume de dados de métricas recebidos. Para detalhes, consulte Preços das operações do Google Cloud.

Além dos preços, o Cloud Monitoring tem limites no número de séries temporais de métricas e no número de descritores de métrica definidos pelo usuário em cada projeto do GCP. Para ver mais detalhes, consulte Cotas e limites.

Se você descobrir que criou descritores de métrica que não quer mais, poderá encontrar e excluir os descritores usando a API Monitoring. Veja mais informações nestes links: projects.metricDescriptors.

Como solucionar problemas

Esta seção explica como configurar o plug-in write_log do agente do Monitoring para despejar o conjunto completo de pontos da métrica, incluindo metadados. Você pode usá-lo para determinar quais pontos precisam ser transformados e garantir que suas transformações funcionem como esperado.

Como ativar o write_log

O plug-in write_log está incluído no pacote stackdriver-agent. Para ativar o plug-in, siga estas etapas:

  1. Como raiz, edite o seguinte arquivo de configuração:

    /etc/stackdriver/collectd.conf
        
  2. Logo depois de LoadPlugin write_gcm, adicione:

    LoadPlugin write_log
        
  3. Logo depois de <Plugin "write_gcm">…</Plugin>, adicione:

    <Plugin "write_log">
          Format JSON
        </Plugin>
        
  4. Pesquise <Target "write">…</Target> e, após cada Plugin "write_gcm", adicione:

    Plugin "write_log"
        
  5. Salve as alterações e reinicie o agente:

    sudo service stackdriver-agent restart
        

Essas alterações imprimirão uma linha de registro por valor de métrica reportado, incluindo o identificador completo do collectd, as entradas de metadados e o valor.

Saída do write_log

Se você tiver êxito na etapa anterior, deverá ver a saída de write_log nos registros do sistema:

  • Linux baseado em Debian: /var/log/syslog
  • Linux baseado em Red Hat: /var/log/messages

As amostras de linha listadas abaixo foram formatadas para facilitar a leitura neste documento.

Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
        "values":[1933524992], "dstypes":["gauge"], "dsnames":["value"],
        "time":1481210025.252, "interval":60.000,
        "host":"test-write-log.c.test-write-log.internal",
        "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"free"}]

    Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
        "values":[0], "dstypes":["gauge"], "dsnames":["value"],
        "time":1481210025.252, "interval":60.000,
        "host":"test-write-log.c.test-write-log.internal",
        "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"reserved"}]