Métricas personalizadas do agente

Neste guia, explicamos como configurar o agente do Stackdriver Monitoring para reconhecer e exportar as métricas do aplicativo para o Stackdriver.

O agente do Monitoring é um daemon do collectd. Ele exporta para o Stackdriver várias métricas predefinidas do sistema e de terceiros e faz a exportação das métricas de aplicativo do collectd como métricas personalizadas. Os plug-ins do collectd também exportam para o Stackdriver.

Outro jeito de exportar métricas de aplicativo para o Stackdriver é usar o StatsD. O Stackdriver 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 Stackdriver, consulte Métricas, séries temporais e recursos, Estrutura dos tipos de métrica e Como usar 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 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 "man" 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 garantir compatibilidade com versões anteriores, o agente também procura 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 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 fonte de dados são processadas como métricas personalizadas e enviadas ao Monitoring. É usado o método projects.timeSeries.create na API Monitoring.

  • Métricas selecionadas: todas as outras métricas do collectd são enviadas ao Monitoring por uma API interna. Apenas 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. Apresentamos esses conceitos em Métricas, séries temporais e recursos e mostramos detalhes sobre eles em Estrutura dos tipos de métrica e Como usar 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. Por exemplo: custom.googleapis.com/my_custom_metric.

  • label:[LABEL] (opcional): rótulos adicionais da métrica exportada. Por exemplo, se você quiser um rótulo STRING do Monitoring chamado color, a chave de metadados será label:color, e o valor dela poderá 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 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, faremos o monitoramento das conexões ativas de dois serviços do 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 do tipo active-connections
[value] qualquer valor2

Observações:
1 No exemplo, o 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.
  • marcadores:
    • 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. Se preferir, deixe 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:

  • nome da métrica: custom.googleapis.com/nginx/active_connections
  • valores de marcador 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 de diferente.

Cadeia de filtros

Crie um arquivo /opt/stackdriver/collectd/etc/collectd.d/nginx_curl_json.conf que contenha 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 Stackdriver 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 ver uma introdução sobre as métricas do Stackdriver, consulte Métricas, séries temporais e recursos. Veja mais detalhes em Como usar métricas personalizadas e Estrutura dos tipos de métrica.

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

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

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

    Os nomes das 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 não podem conter hifens. Para ver todas as regras de nomeação, consulte Regras de nomes de métricas e rótulos.

  • Até 10 rótulos para anotar os dados de métricas 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 ("kind" e "type") dos pontos de dados como "um valor de medidor do tipo duplo". Para saber mais, 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 ("kind" e "type") 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, 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 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 saber mais, consulte Tipos de métricas e 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 Stackdriver cobra por métricas do collectd, tanto as definidas pelo usuário quanto as do agente, com base no volume de dados de métricas recebidos. Para mais detalhes, consulte Preços do Stackdriver.

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

Quando você não quiser mais os descritores de métrica que criou, localize e exclua esses descritores usando a API Monitoring. Para saber mais, consulte projects.metricDescriptors.

Solução de problemas

Nesta seção, explicamos como configurar o plug-in write_log do agente do Monitoring para despejar o conjunto completo de pontos de 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 root, edite o seguinte arquivo de configuração:

    /etc/stackdriver/collectd.conf
    
  2. Logo após LoadPlugin write_gcm, adicione:

    LoadPlugin write_log
    
  3. Logo após <Plugin "write_gcm">…</Plugin>, adicione:

    <Plugin "write_log">
      Format JSON
    </Plugin>
    
  4. Procure por <Target "write">…</Target> e, depois de 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 conseguido realizar a etapa anterior, a saída do write_log será exibida nos registros do sistema:

  • Linux com base em Debian: /var/log/syslog
  • Linux com base 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"}]
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Stackdriver Monitoring
Precisa de ajuda? Acesse nossa página de suporte.