Esta página foi traduzida pela API Cloud Translation.

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

Uma maneira alternativa de exportar métricas de aplicativo para o Monitoring é use o StatsD. O Cloud Monitoring tem uma configuração padrão que mapeia Métricas do StatsD para métricas definidas pelo usuário. Se você estiver satisfeito com esse mapeamento, você não precisa das etapas de personalização descritas abaixo. Para saber mais, consulte o plug-in do StatsD.

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

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 mensagens definidas pelo usuário as métricas do agente, você coloca os arquivos de configuração necessários, abaixo, neste 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. Métricas coletadas que têm a chave de metadados stackdriver_metric_type e um único fonte de dados são gerenciadas como métricas definidas pelo usuário e enviadas ao o monitoramento 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: Métricas coletadas que não estão nas métricas selecionadas e não são definidas pelo usuário são descartadas silenciosamente pelo e monitoramento. 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 aos e monitoramento. Cada ponto deve ser associado a um métrica definida pelo usuário, que você define com um descritor de métrica. Esses conceitos são apresentados em Métricas, série temporal e recursos e descritas em detalhes em Estrutura de séries temporais e Visão geral das métricas definidas pelo usuário.

Você pode tratar uma métrica coletada como uma métrica definida pelo usuário adicionando 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 só aceitam uma única fonte de dados, qualquer métrica do collectd que você quer usar com essa instalação precisa 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. Nós os enviaremos para monitorar usando uma métrica definida pelo usuário; Seguiremos estas etapas:

Identificar as métricas do collectd para cada serviço do Nginx.
Definir um descritor de métrica do Monitoring.
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, 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`¹
Tipo	`gauge`
Instância de tipo	`active-connections`
`[value]`	qualquer valor²

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 de valores. 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 definida pelo usuário. O descritor a seguir é uma boa opção para o 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, você pode criá-lo usando projects.metricDescriptors.create, ou é possível criá-la para você dos metadados de 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

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

Suas informações de métricas definidas pelo usuário começam a ser transmitidas e monitoramento.

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 de 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
```
A nomeação recomendada é hierárquica para possibilitar que as pessoas acompanhem as métricas com mais facilidade. Os tipos de métrica não podem conter hifens. para saber o nome exato 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 de carimbo de data/hora consistente com o tipo de valor do descritor de métrica e tipo
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 respectivo o tipo de métrica, os rótulos e o valor do ponto podem ser usados para criar um medidor ou um descritor de métrica cumulativa. 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 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 tipo de métrica que não for definido, um novo descritor de métrica será criado para os dados ponto Esse comportamento pode ser um problema ao depurar o código que grava dados de métricas. Erros de ortografia no tipo de métrica resultam em descritores de métrica espúrios.

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 do sistema do Cloud Monitoring são gratuitas, e as métricas de sistemas, agentes ou aplicativos externos. As métricas faturáveis são faturadas pelo número de bytes ou de amostras ingeridas.

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

Limites

O Cloud Monitoring tem limites para o tempo de métrica e o 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.

Resolver 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:

Como root, edite o seguinte arquivo de configuração:
```
/etc/stackdriver/collectd.conf
```
Logo depois de LoadPlugin write_gcm, adicione:
```
LoadPlugin write_log
```
Logo depois de <Plugin "write_gcm">…</Plugin>, adicione:
```
<Plugin "write_log">
  Format JSON
</Plugin>
```
Pesquise <Target "write">…</Target> e, após cada Plugin "write_gcm", adicione:
```
Plugin "write_log"
```
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"}]