Esta página foi traduzida pela API Cloud Translation.

Métricas definidas pelo utilizador a partir do agente

Este guia explica como pode configurar o agente de monitorização para reconhecer e exportar as métricas da sua aplicação para o Cloud Monitoring.

O agente de monitorização é um daemon collectd. Além de exportar muitas métricas predefinidas do sistema e de terceiros para o Cloud Monitoring, o agente pode exportar as suas próprias métricas da aplicação collectd para o Monitoring como métricas definidas pelo utilizador. Os seus plug-ins collectd também podem ser exportados para o Monitoring.

Uma forma alternativa de exportar métricas de aplicações para o Monitoring é usar o StatsD. O Cloud Monitoring fornece uma configuração predefinida que mapeia as métricas do StatsD para métricas definidas pelo utilizador. Se estiver satisfeito com esse mapeamento, não precisa dos passos de personalização descritos abaixo. Para mais informações, consulte o plug-in StatsD.

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

Esta funcionalidade só está disponível para agentes executados no Linux. Não está disponível no Windows.

Antes de começar

Instale o agente de monitorização mais recente numa instância de VM e verifique se está a funcionar. Para atualizar o agente, consulte o artigo Atualizar o agente.
Configure o collectd para receber dados de monitorização da sua aplicação. O Collectd suporta muitas estruturas de aplicações e pontos finais de monitorização padrão através dos respetivos plug-ins de leitura. Encontre um plug-in de leitura que seja adequado para si.
(Opcional) Para maior comodidade, adicione a documentação de referência do collectd do agente às páginas man do seu sistema atualizando a variável MANPATH e, em seguida, executando mandb:
```
export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
sudo mandb
```
As páginas de manual são para stackdriver-collectd.

Ficheiros e diretórios importantes

Os seguintes ficheiros e diretórios, criados através da instalação do agente, são relevantes para a utilização do agente de monitorização (collectd):

/etc/stackdriver/collectd.conf: O ficheiro de configuração do collectd usado pelo agente. Edite este ficheiro para alterar a configuração geral.

Nota: a configuração collectd predefinida do sistema, /etc/collectd.conf, não é usada pelo agente de monitorização.
/etc/stackdriver/collectd.d/: O diretório para ficheiros de configuração adicionados pelo utilizador. Para enviar métricas definidas pelo utilizador a partir do agente, coloque os ficheiros de configuração necessários, abordados abaixo, neste diretório. Para retrocompatibilidade, o agente também procura ficheiros em /opt/stackdriver/collectd/etc/collectd.d/.
/opt/stackdriver/collectd/share/man/*: A documentação para a versão do agente do collectd. Pode adicionar estas páginas ao conjunto de páginas man do seu sistema. Consulte a secção Antes de começar para ver detalhes.
/etc/init.d/stackdriver-agent: O script de inicialização do agente.

Como o Monitoring processa as métricas do collectd

Como contexto, os processos do agente de monitorização recolhem métricas do collectd e enviam-nas para o Monitoring, que trata cada métrica como um membro de uma das seguintes categorias:

Métricas definidas pelo utilizador. As métricas recolhidas que têm a chave de metadados stackdriver_metric_type e uma única origem de dados são processadas como métricas definidas pelo utilizador e enviadas para o Monitoring através do método projects.timeSeries.create na API Monitoring.
Métricas organizadas. Todas as outras métricas do collectd são enviadas para o Monitoring através de uma API interna. Apenas as métricas na lista de métricas organizadas são aceites e processadas.
Métricas rejeitadas. As métricas recolhidas que não estão na lista de métricas organizadas e não são métricas definidas pelo utilizador são ignoradas pelo Monitoring. O próprio agente não sabe que métricas são aceites ou rejeitadas.

Escreva métricas definidas pelo utilizador com o agente

Configura o agente para enviar pontos de dados de métricas para o Monitoring. Cada ponto tem de estar associado a uma métrica definida pelo utilizador, que define com um descritor de métricas. Estes conceitos são introduzidos no artigo Métricas, séries cronológicas e recursos e descritos detalhadamente nos artigos Estrutura das séries cronológicas e Vista geral das métricas definidas pelo utilizador.

Pode tratar uma métrica collectd como uma métrica definida pelo utilizador adicionando os metadados adequados à métrica:

stackdriver_metric_type : (obrigatório) o nome da métrica exportada. Exemplo: custom.googleapis.com/my_custom_metric.
label:[LABEL] : (opcional) etiquetas adicionais para a métrica exportada. Por exemplo, se quiser uma etiqueta STRING de monitorização denominada color, a chave de metadados seria label:color e o valor da chave poderia ser "blue". Pode ter até 10 etiquetas por tipo de métrica.

Pode usar uma cadeia de filtros collectd para modificar os metadados das suas métricas. Uma vez que as cadeias de filtros não podem modificar a lista de origens de dados e as métricas definidas pelo utilizador só suportam uma única origem de dados, todas as métricas collectd que quiser usar com esta funcionalidade têm de ter uma única origem de dados.

Exemplo

Neste exemplo, vamos monitorizar as ligações ativas do Nginx a partir de dois serviços do Nginx, my_service_a e my_service_b. Vamos enviá-los para o Monitoring através de uma métrica definida pelo utilizador. Vamos seguir os seguintes passos:

Identifique as métricas do collectd para cada serviço Nginx.
Defina um descritor de métrica de monitorização.
Configure uma cadeia de filtros collectd para adicionar metadados às métricas collectd, de modo a cumprir as expetativas do agente de monitorização.

Métricas collectd recebidas

O Collectd espera que as métricas consistam nos seguintes componentes. Os primeiros cinco componentes formam o identificador do collectd para a métrica:

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

Neste exemplo, as métricas que quer enviar como métrica definida pelo utilizador têm os seguintes valores:

Componente	Valores esperados
Anfitrião	qualquer
Plug-in	`curl_json`
Instância do plug-in	`nginx_my_service_a` ou `nginx_my_service_b`¹
Tipo	`gauge`
Type instance	`active-connections`
`[value]`	qualquer valor²

Notas:
¹ No exemplo, este valor codifica a aplicação (Nginx) e o nome do serviço ligado.
² Normalmente, o valor é uma data/hora e um número de precisão dupla. A monitorização processa os detalhes da interpretação dos vários tipos de valores. Os valores compostos não são suportados pelo agente de monitorização.

Descritor de métricas de monitorização e intervalos temporais

No lado da monitorização, crie um descritor de métricas para a sua métrica definida pelo utilizador. O seguinte descritor é uma escolha razoável para os dados neste exemplo:

Nome: custom.googleapis.com/nginx/active_connections
Etiquetas:
- service_name (STRING): o nome do serviço ligado ao Nginx.
Tipo: GAUGE
Tipo: DOUBLE

Depois de criar o descritor de métricas, pode criá-lo através de projects.metricDescriptors.create, ou pode permitir que seja criado automaticamente a partir dos metadados de intervalos temporais, abordados abaixo. Para mais informações, consulte Criar descritores de métricas nesta página.

Os dados de séries cronológicas para este descritor de métricas têm de conter as seguintes informações, devido à forma como o descritor de métricas está definido:

Tipo de métrica: custom.googleapis.com/nginx/active_connections
Valores das etiquetas de métricas:
- service_name: "my_service_a" ou "my_service_b"

Outras informações de séries cronológicas, incluindo o recurso monitorizado associado (a instância de VM que envia os dados) e o ponto de dados da métrica, são obtidas automaticamente pelo agente para todas as métricas. Não tem de fazer nada de especial.

A sua cadeia de filtros

Crie um ficheiro, /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 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>

Carregue a nova configuração

Reinicie o agente para aplicar a nova configuração executando o seguinte comando na instância de VM:

sudo service stackdriver-agent restart

As informações das métricas definidas pelo utilizador começam a fluir para a Monitorização.

Referência e práticas recomendadas

Descritores de métricas e intervalos temporais

Para uma introdução às métricas do Cloud Monitoring, consulte o artigo Métricas, séries cronológicas e recursos. Estão disponíveis mais detalhes nos artigos Vista geral das métricas definidas pelo utilizador e Estrutura das séries cronológicas.

Descritores de métricas. Um descritor de métricas tem os seguintes elementos significativos:

Um tipo 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
```
A nomenclatura recomendada é hierárquica para que as pessoas possam acompanhar mais facilmente as métricas. Os tipos de métricas não podem conter hífenes. Para ver as regras de nomenclatura exatas, consulte o artigo Atribuir nomes a tipos de métricas e etiquetas.
Até 10 etiquetas para anotar os dados das métricas, como device_name, fault_type ou response_code. Os valores das etiquetas não estão especificados no descritor de métricas.
O tipo e o tipo de valor dos pontos de dados, como "um valor de indicador do tipo double". Para mais informações, consulte MetricKind e ValueType.

Intervalos temporais. Um ponto de dados de métricas tem os seguintes elementos significativos:

O tipo do descritor de métricas associado.
Valores para todas as etiquetas do descritor de métricas.
Um valor com indicação de data/hora consistente com o tipo de valor e o tipo do descritor de métricas.
O recurso monitorizado de onde os dados foram provenientes, normalmente uma instância de VM. O espaço para o recurso está incorporado, pelo que o descritor não precisa de uma etiqueta separada para o mesmo.

Criar descritores de métricas

Não tem de criar um descritor de métricas antecipadamente. Quando um ponto de dados chega ao Monitoring, o tipo de métrica, as etiquetas e o valor do ponto podem ser usados para criar automaticamente um descritor de métrica de indicador ou cumulativo. Para mais informações, consulte o artigo Criação automática de descritores de métricas.

No entanto, existem vantagens em criar o seu próprio descritor de métricas:

Pode incluir alguma documentação ponderada para a métrica e as respetivas etiquetas.
Pode especificar outros tipos de métricas. As únicas combinações (kind, type) suportadas pelo agente são (GAUGE, DOUBLE) e (CUMULATIVE, INT64). Para mais informações, consulte Tipos de métricas e tipos de valores.
Pode especificar tipos de etiquetas diferentes de STRING.

Se escrever um ponto de dados na monitorização que use um tipo de métrica que não esteja definido, é criado um novo descritor de métrica para o ponto de dados. Este comportamento pode ser um problema quando está a depurar o código que escreve dados de métricas. Se escrever incorretamente o tipo de métrica, obtém descritores de métricas espúrios.

Depois de criar um descritor de métricas ou depois de este ser criado por si, não pode ser alterado. Por exemplo, não pode adicionar nem remover etiquetas. Só pode eliminar o descritor de métricas, o que elimina todos os respetivos dados, e, em seguida, recriar o descritor da forma que quiser.

Para mais detalhes sobre a criação de descritores de métricas, consulte o artigo Crie a sua 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 aplicações externos não o são. As métricas faturáveis são faturadas pelo número de bytes ou pelo número de amostras carregadas.

Para mais informações, consulte as secções do Cloud Monitoring na página de preços do Google Cloud Observability.

Limites

O Cloud Monitoring tem limites no número de séries temporais de métricas e no número de descritores de métricas definidos pelo utilizador em cada projeto. Para ver detalhes, consulte o artigo Quotas e limites.

Se descobrir que criou descritores de métricas que já não quer, pode encontrá-los e eliminá-los através da API Monitoring. Para mais informações, consulte projects.metricDescriptors.

Resolução de problemas

Esta secção explica como configurar o plug-in write_log do agente de monitorização para exportar o conjunto completo de pontos de métricas, incluindo metadados. Pode usar esta opção para determinar que pontos têm de ser transformados, bem como para garantir que as transformações têm o comportamento esperado.

Ativar write_log

O plug-in write_log está incluído no pacote stackdriver-agent. Para ativar o plugin:

Como root, edite o seguinte ficheiro de configuração:
```
/etc/stackdriver/collectd.conf
```
Imediatamente após LoadPlugin write_gcm, adicione:
```
LoadPlugin write_log
```
Imediatamente após <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"
```
Guarde as alterações e reinicie o agente:
```
sudo service stackdriver-agent restart
```

Estas alterações vão imprimir uma linha de registo por valor da métrica comunicado, incluindo o identificador collectd completo, as entradas de metadados e o valor.

Saída de write_log

Se tiver êxito no passo anterior, deve ver o resultado de write_log nos registos do sistema:

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

As linhas de exemplo 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"}]