Métricas personalizadas do agente

Beta

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

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 as próprias métricas de aplicativo do collectd para o Monitoring como métricas definidas pelo usuário. Os plug-ins do collectd também exportam para o Monitoring.

Outra maneira de exportar métricas de aplicativos para o Monitoring é usar o StatsD. O Cloud Monitoring fornece uma configuração padrão que mapeia métricas do StatsD para métricas definidas pelo usuário. Se o mapeamento for satisfatório para você, não é necessário passar pelas etapas de personalização descritas abaixo. Para saber mais, consulte o plug-in do StatsD.

Para mais informações sobre métricas, consulte os seguintes documentos:

• Métricas, série temporal e recursos.
• Estrutura de séries temporais.
• Visão geral das métricas definidas pelo usuário.

Observação: essa funcionalidade está disponível apenas para agentes em execução no Linux. Ela não está disponível no Windows.

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 frameworks 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.

Observação: a configuração collectd padrão do sistema, /etc/collectd.conf, não é usada pelo agente do Monitoring.

/etc/stackdriver/collectd.d/

O diretório dos arquivos de configuração adicionados pelo usuário. Para enviar métricas definidas pelo usuário a partir do agente, coloque os arquivos de configuração necessários, discutidos abaixo, nesse diretório. 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 definidas pelo usuário. As métricas coletadas que têm a chave de metadados stackdriver_metric_type e uma única fonte de dados são processadas como métricas definidas pelo usuário e enviadas ao Monitoring pelo 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: As métricas do Coletor que não estão na lista de métricas selecionadas e não são definidas pelo usuário são descartadas silenciosamente pelo Monitoring. O próprio agente não sabe quais métricas são aceitas ou descartadas.

Gravar métricas definidas pelo usuário 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 definida pelo usuário, que você define com um descritor de métrica. Apresentamos esses conceitos em Métricas, série temporal e recursos e descrevemos detalhadamente em Estrutura de séries temporais e Visão geral das métricas definidas pelo usuário.

Para que uma métrica do collectd seja tratada como definida pelo usuário, adicione 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.

Você pode usar uma cadeia de filtros do collectd para modificar os metadados das métricas. Como as cadeias de filtros não podem modificar a lista de fontes de dados, e as métricas definidas pelo usuário aceitam apenas uma única fonte, todas as métricas do collectd que você quer 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. Eles serão enviados ao Monitoring usando uma métrica definida pelo usuário. 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 definida pelo usuário 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_b^1
Tipo	gauge
Instância de tipo	active-connections
[value]	qualquer valor^2

Anotações:
¹ no exemplo, esse valor codifica o aplicativo (Nginx) e o nome do serviço conectado.
² O valor costuma ser um carimbo de data/hora e um número de dupla precisão. O Monitoring lida com os detalhes da interpretação dos vários tipos de valores. Valores compostos não são compatíveis com o agente do Monitoring.

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

No Monitoring, crie um descritor de métrica para a métrica definida pelo usuário. O descritor a seguir é uma escolha razoável 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 projetar o descritor de métrica, é possível criá-lo usando projects.metricDescriptors.create ou deixar que ele seja criado para você a partir dos metadados da série temporal discutidos 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:

• Tipo de 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

Observação: é preciso vincular sua nova cadeia de filtros à cadeia de filtros PreCache.

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 type:
      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 user-defined 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 aren't
  # in the list of curated metrics and don't have
  # the user-defined 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 de métricas definidas pelo usuário começam a fluir 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éries temporais e recursos. Mais detalhes estão disponíveis em Visão geral das métricas definidas pelo usuário e Estrutura de séries temporais.

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

• Um tipo no formato 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
  

  A nomeação recomendada é hierárquica para possibilitar que as pessoas acompanhem as métricas com mais facilidade. Os tipos de métricas não podem conter hifens. Para ver as regras de nomenclatura exatas, consulte Como nomear tipos de métricas 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 rótulos não são especificados no descritor de métrica.

• O tipo e o tipo de valor 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 tipo do descritor de métrica associado.

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

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

• O recurso monitorado de origem dos dados, normalmente uma instância de VM. O espaço do recurso é integrado. Portanto, o descritor não precisa de um rótulo 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, o tipo de métrica, os rótulos e o valor do ponto podem ser usados para criar automaticamente um medidor ou um descritor de métrica cumulativo. Para saber mais, consulte Criação automática de descritores de métricas.

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 tipos ("kind" e "type") adicionais de métricas. As únicas combinações deles compatíveis com o agente são (GAUGE, DOUBLE) e (CUMULATIVE, INT64). Para mais informações, consulte Classes de métricas e tipos de valor.

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

Se você gravar um ponto de dados no Monitoring que use um tipo de métrica não definido, um novo descritor de métrica será criado para o ponto de dados. Esse comportamento pode ser um problema quando você está depurando o código que grava dados de métricas. Erros de digitação no tipo de métrica resultam em descritores 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.

Preços

Em geral, as métricas de sistema do Cloud Monitoring são gratuitas, já as métricas de sistemas, agentes ou aplicativos externos não. As métricas faturáveis são cobradas pelo número de bytes ou de amostras ingeridas.

Para mais informações sobre os preços do Cloud Monitoring, consulte os seguintes documentos:

• Resumo de preços do Cloud Monitoring.
• Preços do Cloud Monitoring.

Limites

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. 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. Para mais informações, consulte projects.metricDescriptors.

Solução de 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.

Observação: isso produzirá uma grande quantidade de saída nos registros do sistema. Recomendamos que você desligue o recurso no final da sessão de solução de problemas. Se você tiver configurado o agente do Cloud Logging, poderá visualizar as entradas de registro do sistema no Cloud Logging.

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 root, 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"}]