Integração no host: formato de configuração padrão

A propriedade name obrigatória pode funcionar de duas maneiras:

• If the exec property is set: a propriedade name fornece apenas um identificador para a instância de integração. Este identificador é usado na mensagem do log e para fornecer uma categoria/fonte de inventário padrão no formato integration/<name> (por exemplo, integration/nri-redis). Este caminho de inventário pode ser substituído pela opção de configuração inventory_source .

• If the exec property is not set: o agente procura (e executa) um executável com o valor name em qualquer uma das seguintes pastas:

  • Linux:

    • /var/db/newrelic-infra/newrelic-integrations/bin
    • /var/db/newrelic-infra/newrelic-integrations
    • /var/db/newrelic-infra/custom-integrations/bin
    • /var/db/newrelic-infra/custom-integrations

  • Windows

    • C:\Program Files\New Relic\newrelic-infra\newrelic-integrations\bin
    • C:\Program Files\New Relic\newrelic-infra\newrelic-integrations

  Caso não exista nenhum executável com este nome nas pastas acima o agente registra um erro e a integração não é executada.

  Importante

  No Windows, não anexe a extensão .exe ao nome. O agente faz isso para você (por exemplo, name: nri-mysql procuraria nri-mysql.exe nas pastas acima).

A propriedade opcional exec especifica o caminho, o comando e os argumentos de linha de comando da integração a ser executada. Quando nenhuma das pastas ou argumentos do caminho tiver espaços, ele poderá ser escrito em uma string de linha única:

- name: my-integration
  exec: /usr/bin/python /opt/integrations/my-script.py --host=127.0.0.1

Se algum dos caminhos ou argumentos tiver espaços que fazem parte de um único elemento, você poderá usar uma notação de matriz YAML. Para Windows, certifique-se de evitar barras invertidas com aspas como esta:

- name: my-integration
  exec:
    - '"C:\Program Files\My Integration\integration.exe"'
    - --host
    - 127.0.0.1
    - --port
    - 8080

O diretório de trabalho padrão é o diretório raiz da configuração do agente. Ela pode ser substituída pela propriedade working_dir .

A propriedade opcional cli_args especifica argumentos de linha de comando que devem ser transmitidos para a integração. É útil ao usar name, pois fornece apenas o identificador do nome da integração (não compatível com exec).

- name: my-integration
  cli_args: [ -interval 10s ]

O formato usual de lista multilinha YAML também pode ser usado:

- name: my-integration
  cli_args:
    - -interval
    - 10s

A propriedade when permite executar a integração somente quando todas as condições avaliadas forem bem-sucedidas.

As condições disponíveis são:

• env_exists: variáveis de ambiente existem e correspondem ao valor.

• file_exists: existe um determinado caminho de arquivo.

• feature: Desde que o sinalizador de recurso esteja ativado.

  Exemplo:

  integrations:
    - name: ssh-integration
      when:
        file_exists: /var/run/sshd.pid

  Copiar

A propriedade env permite definir variáveis de ambiente que são transmitidas ao executável. É um mapa de valor principal com as variáveis requeridas.

Exemplo:

integrations:
  - name: nri-postgresql
    env:
      DATABASE: postgres
      PORT: 6432
      COLLECTION_LIST: '["postgres"]'
      COLLECT_DB_LOCK_METRICS: false
      VERBOSE: 1

Se você espera que sua integração receba a configuração do ambiente do host em vez de especificá-la explicitamente no arquivo de configuração, será necessário definir as variáveis necessárias na propriedade de configuração global passthrough_environment do agente de infraestrutura

Esta seção descreve várias maneiras de passar informações de configuração para uma integração.

Pass configuration file directly

Alguns comandos de integração podem obter sua configuração de um arquivo externo. Se a sua integração requer um arquivo de configuração, nada impede que você passe seu caminho diretamente como um argumento de linha de comando ou uma variável de ambiente. Aqui está um exemplo usando a configuração de nossa integração Flex:

integrations:
  - name: nri-flex
    env:
      CONFIG_FILE: /etc/nri-flex/configs/http-service.yaml
  - name: other-integration
    exec: /opt/integration/integration -f /opt/integration/config.properties

O exemplo acima pressupõe que os arquivos http-service.yaml e config.properties existam. Podemos ver que a integração nri-flex espera o caminho completo http-service.yaml por meio da variável de ambiente CONFIG_FILE e o other-integration espera o caminho config.properties completo após o sinalizador de linha de comando -f .

No exemplo acima, é necessário para o instalador/configurador de integração que os arquivos de configuração existam no caminho fornecido e que o agente e a integração tenham permissões de leitura sobre eles.

Pass configuration through config section

Se preferir manter seu arquivo de configuração com o restante da configuração de integração, você pode usar a seção config na entrada de integração, que pode conter um objeto YAML válido ou apenas uma string de várias linhas:

integrations:
  - name: nri-flex
    env:
      CONFIG_FILE: ${config.path}
    config:
      name: csvFileExample
      apis:
        - name: csvFile
          file: /Users/hello/test.csv
  - name: other-integration
    exec: /opt/integration/integration -f ${config.path}
    config: |
      example.cfg.verbose=true
      example.cfg.logger=/var/logs/integration.log
      example.cfg.hostname=localhost
      example.cfg.port=9025

Nos exemplos acima, sempre que a integração nri-flex é executada, o agente cria um arquivo temporário com o seguinte conteúdo:

name: csvFileExample
apis:
  - name: csvFile
    file: /Users/hello/test.csv

O YAML acima é apenas um exemplo de configuração para a integração nri-flex . O agente ignora o seu conteúdo; em vez disso, ele cria um arquivo temporário e substitui o espaço reservado da variável ${config.path} pelo seu caminho. Quando a integração conclui a execução, o arquivo temporário é removido.

Além disso, o agente cria outro arquivo temporário antes de executar a integração other-integration :

example.cfg.verbose=true
example.cfg.logger=/var/logs/integration.log
example.cfg.hostid=localhost
example.cfg.port=9025

Ele substitui o espaço reservado da linha de comando -f ${config.path} pelo caminho temporário do arquivo gravado.

Por convenção, se você não colocar a variável ${config.path} em nenhum argumento de linha de comando ou valor de variável de ambiente, o agente transmitirá o caminho do arquivo de configuração por meio da variável de ambiente CONFIG_PATH :

# assuming that nri-example command is prepared to receive the configuration
# file via the CONFIG_PATH environment variable
integrations:
  - name: nri-example
    config:
      name: csvFileExample
      apis:
        - name: csvFile
          file: /Users/hello/test.csv

Pass secrets and discovery through config section

O principal benefício de usar uma seção config em vez de codificar o caminho completo de um arquivo externo é que você pode inserir ${variable} espaço reservado para aplicar nosso recurso de auto-descoberta e gerenciamento de segredos.

Aqui está um exemplo seguido de algumas explicações:

variables:
  my_credentials:
    vault:
      http:
        url: http://my.vault.host/v1/newengine/data/secret
        headers:
          X-Vault-Token: my-vault-token
discovery:
  docker:
    match:
      label.service: foo
integrations:
  - name: foo-monitor
    exec: /opt/foo/bin/monitor --config=${config.path}
    config: |
      foo.host=${discovery.ip}
      foo.port=${discovery.port}
      foo.user=${my_credentials.user}
      foo.password=${my_credentials.password}

O exemplo acima baseia-se nas seguintes premissas:

• Existe um serviço Vault que permite recuperar um objeto JSON formado pelos campos user e password .
• Pode haver um número variável de contêineres Docker rotulados com service=foo, que são acessíveis a partir do host do agente por meio de um IP e porta públicos detectáveis.
• O usuário configurou a integração foo-monitor para monitor todos os service=foo contêineres rotulados, que compartilham usuário e senha comuns. Cada instância da integração foo-monitor requer a execução do executável /opt/foo/bin/monitor, passando a configuração de texto dentro da seção config por meio do argumento de linha de comando --config=<path> .

Como exemplo de fluxo de trabalho, imagine que a invocação do Vault retorne o seguinte JSON:

{"user":"monitorer","password":"5up3r53cr3t!"}

No momento da execução da integração foo-monitor, existem três contêineres em execução rotulados com service=foo:

1. ip: 10.0.0.3, porta: 8080
2. ip: 10.0.0.3, porta: 8081
3. ip: 10.0.0.3, porta: 8082

O agente então cria os três arquivos temporários a seguir, usando o conteúdo da propriedade config como modelo, mas substituindo ${placeholders} pelas variáveis adquiridas e itens descobertos (o caminho dos arquivos é inventado por uma questão de simplicidade):

• Primeira correspondência (/tmp/123_discovered):

  foo.host=10.0.0.3
  foo.port=8080
  foo.user=monitorer
  foo.password=5up3r53cr3t!

  Copiar

• Segunda correspondência (/tmp/456_discovered):

  foo.host=10.0.0.3
  foo.port=8081
  foo.user=monitorer
  foo.password=5up3r53cr3t!

  Copiar

• Terceira partida (/tmp/789_discovered)

  foo.host=10.0.0.3
  foo.port=8082
  foo.user=monitorer
  foo.password=5up3r53cr3t!

  Copiar

Após a substituição da variável config espaço reservado e a criação dos arquivos temporários, o executável /opt/foo/bin/monitor é executado três vezes (uma por contêiner correspondente), substituindo a ${config.path} linha de comando espaço reservado pelo arquivo temporário correspondente para cada configuração descoberta:

• Primeira partida: /opt/foo/bin/monitor --config=/tmp/123_discovered
• Segunda partida: /opt/foo/bin/monitor --config=/tmp/456_discovered
• Terceira partida: /opt/foo/bin/monitor --config=/tmp/789_discovered

Para garantir a segurança e minimizar a chance de vazamento de segredos para o disco, o agente:

• Cria os arquivos pertencentes ao usuário do agente, por exemplo, root ou nri-agent, dependendo do usuário que você configurou para executar o agente.
• Define permissões de leitura apenas para o proprietário.
• Remove os arquivos criados quando a instância de integração finaliza sua execução.

Se você quiser usar o gerenciamento e a descoberta de segredos nos arquivos de configuração que está passando para o executável de integração, mas preferir mantê-los como um arquivo individual, poderá usar a opção config_template_path: <path> . Funciona exatamente como na seção config :

1. O agente aplica gerenciamento e descoberta de segredos ao conteúdo do arquivo.

2. O agente cria diferentes arquivos temporários que são transmitidos para a integração por meio do espaço reservado ${config.path} (ou da variável de ambiente CONFIG_PATH ).

   Exemplo:

   discovery:
       docker:
         match:
           name: /^redis/
     integrations:
       - name: nri-flex
         env:
           CONFIG_FILE: ${config.path}
         config_template_path: /etc/flex-configs/redis.yml

   Copiar

   No exemplo acima, o arquivo externo redis.yml pode conter a variável de descoberta do contêiner espaço reservado, como ${discovery.ip} ou ${discovery.port}.

Os comandos de integração são executados pelo mesmo usuário que o agente (geralmente root ou nri-agent). Se devido a restrições de permissão uma integração precisar ser executada como outro usuário, seu nome deverá ser especificado na propriedade integration_user .

Exemplo:

integrations:
  - name: dbus-inventory
    exec: python my-dbus-script.py
    integration_user: dbus

A opção interval define o tempo entre execuções consecutivas de uma integração. O formato aceito é um número inteiro imediatamente seguido por uma unidade de tempo (s para segundos, m para minutos, h para horas).

O padrão é 30s e o valor mínimo aceito é 15s. Qualquer valor inferior a 15s é automaticamente definido como 15s.

Exemplo:

integrations:
  - name: nri-nginx
    env:
      STATUS_URL: http://127.0.0.1/status
      STATUS_MODULE: discover
    interval: 20s

Qualquer item de inventário deve ser catalogado sob uma taxonomia category/source . Por padrão, cada inventário de integração é armazenado como valor integration/ + name (por exemplo, integration/nri-apache, integration/nri-mysql).

A propriedade inventory_source permite substituir a taxonomia padrão dos dados de inventário.

Exemplo:

integrations:
  - name: nri-nginx
  - name: nri-apache
    exec:
      - /var/db/newrelic-infra/newrelic-integrations/bin/nri-apache
      - --inventory
    inventory_source: config/apache

No exemplo acima, o inventário nri-nginx, se houver, estaria visível na interface New Relic na origem integration/nri-nginx. O inventário nri-apache ficaria visível em config/apache.

labels é um mapa de valor principal que permite fornecer metadados extras para a integração. O agente utiliza esses rótulos para decorar as métricas, eventos e inventários que recebe de uma determinada instância de integração.

Exemplo:

integrations:
  - name: nri-apache
    inventory_source: config/apache
    labels:
      env: production
      role: load_balancer

No exemplo acima, o agente decora todas as métricas e eventos da instância nri-apache com os seguintes campos:

• label.env: production
• label.role: load_balancer

Além disso, as seguintes entradas são adicionadas ao inventário de integração:

• config/apache/labels/env: production
• config/apache/labels/role: load_balancer

Se uma integração não retornou nenhuma métrica (ou uma mensagem de pulsação conforme descrito abaixo) antes do tempo especificado no valor timeout, o agente encerra o processo de integração e o reinicia após o interval correspondente. O formato aceito é um número inteiro imediatamente seguido (sem espaços) por uma unidade de tempo (ms para milissegundos, s para segundos, m para minutos, h para horas).

Se um valor timeout zero (ou negativo) for fornecido, a integração poderá ser executada indefinidamente sem ser interrompida pela expiração do tempo limite.

Para integrações de longa duração (integrações que continuam em execução, retornando periodicamente métrica/evento/inventário), cada vez que a integração envia uma carga de métrica/evento/inventário, o prazo de timeout é reiniciado. Isso significa que a integração de longa duração deve retornar uma carga JSON válida em um intervalo menor que timeout.

O retorno de um JSON vazio ({}) é interpretado como uma mensagem de pulsação que reinicia o tempo limite, evitando que a integração de longa duração seja encerrada, mesmo que eles não tenham informações para relatar.

O padrão é 120s e o valor mínimo aceito é 100ms. Qualquer valor inferior a 100ms é automaticamente definido como 100ms.

Exemplo:

integrations:
  - name: nri-jmx
    cli_args:
      JMX_HOST: jmx-host.localnet
      JMX_PORT: 7096
      COLLECTION_FILES: "/etc/newrelic-infra/integrations.d/jvm-metrics.yml"
    timeout: 30s

working_dir define o diretório de trabalho do comando. Se estiver vazio ou não especificado, o agente executa o comando no diretório atual do agente de infraestrutura.

O padrão é o diretório raiz do agente de infraestrutura.

Exemplo:

integrations:
  - name: my-integration
    exec: /opt/integration/bin/integration
    working_dir: /opt/integration/scratch-zone

O caminho usado abaixo é o local padrão para integração baseada em Linux. Talvez seja necessário ajustar o caminho se estiver usando um local personalizado:

newrelic agent config migrateV3toV4 \
 -d /var/db/newrelic-infra/newrelic-integrations/redis-definition.yml \
 -c /etc/newrelic-infra/integrations.d/redis-config.yml \
 -o /etc/newrelic-infra/integrations.d/redis.yml

O caminho usado abaixo é o local padrão para integração baseada em Windows. Talvez seja necessário ajustar o caminho se estiver usando um local personalizado:

newrelic agent config migrateV3toV4 ^
 -d 'C:\Program Files\New Relic\newrelic-infra\newrelic-integrations\mssql-definition.yml' ^
 -c 'C:\Program Files\New Relic\newrelic-infra\integrations.d\mssql-config.yml' ^
 -o 'C:\Program Files\New Relic\newrelic-infra\integrations.d\mssql.yml'