オンホストの統合標準的な設定フォーマット

必須の name プロパティは、次の 2 つの方法で機能します。

• If the exec property is set: nameプロパティは、統合インスタンスの識別子のみを提供します。 この識別子はログメッセージで使用され、デフォルトのインベントリ カテゴリ/ソースをintegration/<name>の形式で提供します (例: integration/nri-redis )。 このインベントリ パスは、 inventory_source設定オプションで上書きできます。

• If the exec property is not set: エージェントは、次のいずれかのフォルダーで、 name値を持つ実行可能ファイルを検索 (そして実行) します。

  • 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

  • ウィンドウズ

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

  上記のフォルダにこの名前の実行ファイルがない場合、エージェントはエラーを記録し、統合は実行されません。

  重要

  Windows では、名前に拡張子 .exe を追加しないでください。エージェントがこれを行います (たとえば、 name: nri-mysql 上記のフォルダーで nri-mysql.exe を検索します)。

exec オプションのプロパティは、実行する統合のパス、コマンド、およびコマンドライン引数を指定します。パス フォルダーまたは引数にスペースが含まれていない場合は、単一行の文字列で記述することができます。

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

パスまたは引数のいずれかに単一要素の一部であるスペースが含まれている場合は、YAML 配列表記を使用できます。 Windows の場合は、次のようにバックスラッシュを引用符でエスケープしてください。

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

デフォルトの作業ディレクトリは、エージェント構成のルート ディレクトリです。これは、 working_dir プロパティでオーバーライドできます。

cli_args オプションのプロパティは、統合に渡す必要があるコマンド ライン引数を指定します。これは、統合名識別子のみを提供するため、 name を使用する場合に便利です ( execとは互換性がありません)。

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

通常のYAMLの複数行リスト形式も使用できます。

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

when プロパティを使用すると、評価された条件がすべて成功した場合にのみ統合を実行できます。

利用できる条件は

• env_exists: 環境変数が存在し、値が一致しています。

• file_exists: 指定されたファイル パスが存在します。

• feature: 機能フラグが有効になっている場合。

  例：

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

  コピー

env プロパティを使用すると、実行可能ファイルに渡される環境変数を設定できます。これは、必要な変数を含むキーと値のマップです。

例：

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

統合が構成ファイルで明示的に指定するのではなく、ホストの環境から構成を受信することを期待している場合は、インフラストラクチャ エージェントの passthrough_environment グローバル構成プロパティで必要な変数を設定する必要があります。

ここでは、インテグレーションに設定情報を渡すさまざまな方法について説明します。

Pass configuration file directly

統合コマンドの中には、外部ファイルから設定を取得するものがあります。インテグレーションが設定ファイルを必要とする場合、そのパスをコマンドライン引数や環境変数として直接渡すことを妨げるものは何もありません。ここでは、 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

上の例では、 http-service.yaml と config.properties ファイルが存在することを前提としています。 nri-flex 統合は、 CONFIG_FILE 環境変数を介して http-service.yaml 完全なパスを期待し、 other-integration は、 -f コマンドライン フラグの後の完全な config.properties パスを期待していることがわかります。

上記の例では、統合インストーラー/コンフィギュレーターにとって、設定ファイルが提供されたパスに存在し、エージェントと統合がそれらに対して読み取り権限を持っていることが必要です。

Pass configuration through config section

構成ファイルを残りの統合構成とともに保持したい場合は、統合エントリの config セクションを使用できます。このセクションには、有効な YAML オブジェクトまたは単なる複数行の文字列を含めることができます。

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

上記の例では、 nri-flex 統合が実行されるたびに、エージェントは次の内容の一時ファイルを作成します。

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

上記の YAML は、 nri-flex 統合の構成例にすぎません。エージェントはその内容を無視します。代わりに、一時ファイルを作成し、 ${config.path} 変数プレースホルダーをそのパスに置き換えます。統合の実行が完了すると、一時ファイルは削除されます。

また、エージェントは、 other-integration 統合を実行する前に別の一時ファイルを作成します。

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

これにより、 -f ${config.path} コマンドライン プレースホルダーが、書き込まれたファイルの一時パスに置き換えられます。

慣例により、コマンドライン引数または環境変数値に ${config.path} 変数を配置しない場合、エージェントは、 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

外部ファイルのフルパスをハードコーディングする代わりに config セクションを使用する主な利点は、 ${variable} プレースホルダを挿入して 自動検出機能 と シークレット管理を適用できることです。

ここでは、その例を挙げて説明します。

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}

上記の例は、以下の前提に基づいています。

• user フィールドと password フィールドで形成された JSON オブジェクトを取得できる Vault サービスがあります。
• service=fooというラベルが付けられた Docker コンテナが可変数存在する場合があります。これらのコンテナには、検出可能なパブリック IP とポートを介してエージェント ホストからアクセスできます。
• ユーザーは、共通のユーザーとパスワードを共有するすべての service=foo ラベル付きコンテナを監視するように foo-monitor 統合を構成しました。 foo-monitor 統合の各インスタンスでは、 /opt/foo/bin/monitor 実行可能ファイルを実行し、 --config=<path> コマンドライン引数を介して config セクション内のテキスト構成を渡す必要があります。

ワークフローの例として、Vaultの呼び出しが次のようなJSONを返すとします。

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

foo-monitor 統合を実行する時点では、 service=fooというラベルが付いた実行中のコンテナが 3 つあります。

1. IP: 10.0.0.3、ポート: 8080
2. IP: 10.0.0.3、ポート: 8081
3. IP: 10.0.0.3、ポート: 8082

次に、エージェントは、 config プロパティの内容をテンプレートとして使用して、次の 3 つの一時ファイルを作成します。ただし、 ${placeholders} は取得した変数と検出された項目に置き換えられます (ファイルのパスはわかりやすくするために作成されています)。

• 最初の一致 (/tmp/123_discovered):

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

  コピー

• 2 番目の一致 (/tmp/456_discovered):

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

  コピー

• 3 番目の一致 (/tmp/789_discovered)

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

  コピー

config 変数プレースホルダーが置き換えられ、一時ファイルが作成された後、 /opt/foo/bin/monitor 実行可能ファイルが 3 回 (一致したコンテナごとに 1 回) 実行され、 ${config.path} コマンドライン プレースホルダーがそれぞれに対応する一時ファイルに置き換えられます。発見された構成:

• 最初の一致: /opt/foo/bin/monitor --config=/tmp/123_discovered
• 2 番目の試合: /opt/foo/bin/monitor --config=/tmp/456_discovered
• 3番目の試合: /opt/foo/bin/monitor --config=/tmp/789_discovered

セキュリティを確保し、秘密がディスクに漏れる可能性を最小限にするために、エージェントは

• エージェントを実行するように構成したユーザーに応じて、エージェント ユーザー (たとえば、 root または nri-agentが所有するファイルを作成します。
• オーナーに対してのみ読み取り権限を設定します。
• 統合インスタンスの実行終了時に、作成したファイルを削除します。

統合実行可能ファイルに渡す構成ファイルでシークレットの管理と検出を使用したいが、それらを個別のファイルとして保持したい場合は、 config_template_path: <path> オプションを使用できます。これは、 config セクションとまったく同じように機能します。

1. エージェントは、 秘密管理 と 発見 をファイルの内容に適用します。

2. エージェントは、 ${config.path} プレースホルダー (または CONFIG_PATH 環境変数) を介して統合に渡されるさまざまな一時ファイルを作成します。

   例：

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

   コピー

   上記の例では、 redis.yml 外部ファイルには、 ${discovery.ip} や ${discovery.port}などのコンテナ検出変数プレースホルダを含めることができます。

統合コマンドは、エージェントと同じユーザー (通常は root または nri-agent) として実行されます。権限の制限により、統合を別のユーザーとして実行する必要がある場合は、その名前を integration_user プロパティで指定する必要があります。

例：

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

interval オプションは、統合の連続実行間の時間を設定します。受け入れられる形式は、整数の直後に時間単位が続きます (s は秒、 m は分、 h は時間) です。

デフォルトは 30sで、許容される最小値は 15sです。 15s より小さい値は自動的に 15sに設定されます。

例：

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

在庫品目はすべて、 category/source 分類法に基づいてカタログ化する必要があります。デフォルトでは、各統合インベントリは integration/ + name 値として保存されます (例: integration/nri-apache、 integration/nri-mysql)。

inventory_source プロパティを使用すると、インベントリ データのデフォルトの分類をオーバーライドできます。

例：

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

上記の例では、 nri-nginx インベントリがあれば、それが New Relic UI の integration/nri-nginx ソースの下に表示されます。 nri-apache 在庫は config/apacheの下に表示されます。

labels は、統合のために追加のメタデータを提供できるようにするキーと値のマップです。エージェントは、これらのラベルを使用して、特定の統合インスタンスから受信するメトリクス、イベント、およびインベントリを装飾します。

例：

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

上の例では、エージェントは、 nri-apache インスタンスからのすべてのメトリクスとイベントを次のフィールドで装飾します。

• label.env： production
• label.role： load_balancer

また、統合インベントリに以下の項目が追加されています。

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

timeout 値で指定された時刻までに統合がメトリック (または後述のハートビート メッセージ) を返さなかった場合、エージェントは統合プロセスを強制終了し、対応する intervalの後に再起動します。受け入れられる形式は、整数の直後に (スペースなしで) 時間単位が続くものです (ミリ秒はms 、秒は s 、分は m 、時間は h )。

ゼロ (または負の) timeout 値が指定された場合、統合はタイムアウト期限切れによって強制終了されることなく永久に実行できます。

長時間実行される統合 (実行を継続し、メトリクス/イベント/インベントリを定期的に返す統合) の場合、統合がメトリクス/イベント/インベントリ ペイロードを送信するたびに、タイムアウト期限が再開されます。つまり、長時間実行される統合では、 timeoutより短い間隔で有効な JSON ペイロードを返す必要があります。

空の JSON ({}) を返すと、タイムアウトを再開する ハートビート メッセージとして解釈され、レポートする情報がない場合でも、長時間実行される統合が強制終了されるのを防ぎます。

デフォルトは 120sで、許容される最小値は 100msです。 100ms より小さい値は自動的に 100msに設定されます。

例：

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 コマンドの作業ディレクトリを設定します。空または指定されていない場合、エージェントはインフラストラクチャ エージェントの現在のディレクトリでコマンドを実行します。

デフォルトは、インフラストラクチャ エージェントのルート ディレクトリです。

例：

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

以下のパスは、Linuxベースの統合のためのデフォルトの場所です。カスタムの場所を使用している場合は、パスを調整する必要があります。

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

以下のパスは、Windowsベースの統合のためのデフォルトの場所です。カスタムの場所を使用している場合は、パスを調整する必要があります。

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'