O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Métricas definidas pelo usuário 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 para o Cloud Monitoring várias métricas predefinidas do sistema e de terceiros, o agente pode exportar suas 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.

Uma maneira alternativa 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 você estiver satisfeito com esse mapeamento, não precisará seguir as etapas de personalização descritas abaixo. Para saber mais, consulte o plug-in do StatsD.

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

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 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 do Collectd 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 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: As métricas do Collectd 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

Você configura 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 é definida com um descritor de métrica. Esses conceitos são apresentados em Métricas, série temporal e recursos e descritos em detalhes em Estrutura das séries temporais e Visão geral das métricas definidas pelo usuário.

Para que uma métrica do collectd seja tratada como uma métrica 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 só aceitam uma fonte de dados, todas as métricas do collectd que você quiser usar com essa facilidade 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. Vamos enviá-las ao Monitoring 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, 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`¹
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 processa os detalhes da interpretação dos vários tipos 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 de métrica para sua métrica definida pelo usuário. O descritor a seguir é uma opção 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 criar o descritor de métrica, use projects.metricDescriptors.create para criá-lo ou deixe que ele seja criado para você com base nos 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

As informações da sua métrica definida 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. Para mais detalhes, consulte Visão geral das métricas definidas pelo usuário e Estrutura das séries temporais.

Descritores de métrica. Um descritor de métrica tem as seguintes partes importantes:

Um tipo da postura 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 conferir as regras exatas de nomenclatura, consulte Nomenclatura de 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 double". 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 e a classe de valor 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 descritor de métrica cumulativa ou de medidor. 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 usando um tipo de métrica que não está definido, um novo descritor de métrica será criado para o ponto de dados. 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étricas 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

Para saber mais sobre os preços do Cloud Monitoring, consulte a página Preços do Google Cloud Observability.

Limites

O Cloud Monitoring tem limites para o número de séries temporais de métricas e de descritores de métricas 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"}]