2019年12月、 Infrastructure agent version 1.8.0 は、(2つの別々のファイルではなく)1つの設定ファイルを利用し、その他の改善を行うこの新しい設定形式のサポートを開始しました。このドキュメントでは、この新しいフォーマットの動作について説明します。
古い レガシー設定フォーマット も、現在のInfrastructureエージェントでサポートされています。
設定の概要については、 Config overview をご覧ください。
構成構造 ホスト上の統合の設定YAMLには、 integrations
トップレベルのセクションがあり、各エントリが統合とその設定を表すYAML配列を含んでいなければなりません。
各統合エントリでは、 name
プロパティのみが必須です。その他のプロパティはオプションです。
ここでは、2つの統合をフィーチャーした構成例をご紹介します。ビルトインの Docker統合 は設定が不要で、 MySQL統合 です。
integrations:
# New Relic integration that does not require any configuration
- name: nri-docker
# New Relic integration that gets its configuration from the environment
- name: nri-mysql
env:
PORT: 3306
USERNAME: newrelic
PASSWORD: 123456789 # to hide this field, read the secrets management documentation
# Any free-form integration executed via a user-provided command
- name: my-own-integration
exec: python /opt/integrations/my-script.py --host=127.0.0.1
設定用のYAMLファイルは必要なだけ用意でき、統合インスタンスをグループ化することができます。
ヒント フォーマットの問題を避けるために、使用前にYAML設定ファイルを linting することをお勧めします。
各設定用YAMLファイルには、 discovery
and variables
トップレベルのセクションも含めることができます。
重要 この設定形式では、エージェントの再起動は必要ありません。保存すると、変更はすぐに検出され、実行されます。つまり、途中の設定変更を保存すると、統合機能が停止する可能性があります。
設定プロパティの一覧 これは、統合を構成するために使用される一般的なプロパティのリストです。これらのプロパティの使用方法や値の例などの詳細については、表の後にあるドキュメントを参照してください。
コンフィグ
説明
name
統合の名前。これは、すべてのホスト上の統合に共通する唯一の必須設定プロパティです。 exec
フィールドが設定されていない場合は、統合の実行ファイルの名前にもなります。
cli_args
名前
が統合実行ファイルを提供するために使用される場合のコマンドライン引数のオプションリスト エージェントバージョン以降で利用可能 1.13.0 .
エグゼクティヴ
統合実行ファイルのフルパスと引数です。単一行の文字列または文字列の配列になります。指定しない場合、 exec
フィールドのデフォルトは、 name
フィールドになります。
envelope
インテグレーションに渡す環境変数を含むYAMLマップ。 キー
は環境変数名、 値
は変数値です。
コンフィグ
外部ファイルとして書き込まれるコンフィグレーションと、 CONFIG_PATH
環境変数または ${config.path} でインテグレーションに渡されるパス。
変数のプレースホルダーです。
config_template_path
CONFIG_PATH
環境変数または ${config.path} でパスが統合に渡される任意の外部ファイル。
変数のプレースホルダーです。その使い方によって、ディスカバリーとシークレット・バインディングを任意の外部設定に適用することができます。
integration_user
統合を実行するユーザーの名前。
インターバル
統合を連続して実行する間の時間。数字の後に時間単位(s
, m
or h
)を、スペースを入れずに入力する必要があります。
インベントリソース
インベントリソースのカテゴリーとタームをオーバーライドできます。
labels
統合によって報告されたデータ(メトリクス、イベント、インベントリ)を装飾するラベルを持つマップ。
タイムアウト
数字の後に時間単位(ms
, s
, m
or h
)を指定します。この時間内に反応しなかった統合は殺され、再起動されます。
作業用ディレクトリ
統合バイナリの作業ディレクトリ。
ときに
統合は、その節の評価が真である場合にのみ実行されます。
条件は 以下に定義されています 。
このドキュメントの残りの部分では、機能ごとにグループ化されたconfigプロパティについて説明します。
実行するインテグレーションの選択どの統合が実行されるかを選択するために、 name
と exec
という2つのプロパティがあります。
すべてのホスト上の統合において唯一必須のプロパティは、 name
です。このドキュメントで指定されている残りのプロパティはオプションです。
例:
exec: /usr/local/bin/my-integration --metrics --inventory
name
必須の name
プロパティは、2つの方法で機能します。
exec
プロパティが設定されている場合 : name
プロパティは、統合インスタンスの識別子を提供するだけです。この識別子は、ログメッセージで使用され、 integration/<name>
という形式で、デフォルトの inventory category/source を提供するために使用されます(例: integration/nri-redis
)。このインベントリパスは、 inventory_source
設定オプションでオーバーライドできます。
exec
プロパティが設定されていない場合 : エージェントは 名前
値を持つ実行ファイルを以下のいずれかのフォルダで探します(実行します)。
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
上記のフォルダにこの名前の実行ファイルがない場合、エージェントはエラーを記録し、統合は実行されません。
重要 Windows では、名前に .exe
という拡張子を付けないでください。エージェントがこれを行います(例えば、 name: nri-mysql
の場合、上記のフォルダの中から nri-mysql.exe
を探します)。
エグゼクティヴ
exec
オプションのプロパティでは、実行する統合のパス、コマンド、コマンドライン引数を指定します。パス・フォルダや引数のいずれにもスペースがない場合は、1行の文字列で記述することができます。
exec: /usr/bin/python /opt/integrations/my-script.py --host=127.0.0.1
パス/引数の中に、1つの要素の一部であるスペースがある場合、YAMLの配列表記を使用することができます。
- C:\Program Files\My Integration\integration.exe
デフォルトの作業ディレクトリは、エージェント構成のルート・ディレクトリです。これは、 working_dir
プロパティでオーバーライドできます。
cli_args
cli_args
オプションのプロパティは、統合に渡されるべきコマンドライン引数を指定します。これは、 名前
を使用する際に、統合名の識別子のみを提供するので便利です( exec
とは互換性がありません)。
cli_args: [ -interval 10s ]
通常のYAMLの複数行リスト形式も使用できます。
ときに
when
プロパティは、評価されたすべての条件が成功したときにのみ統合を実行することができます。
利用できる条件は
env_exists
: 環境変数が存在し、値が一致している。
file_exists
: 与えられたファイルパスが存在する。
feature
: Provided feature-flag が有効です。
例:
file_exists: /var/run/sshd.pid
統合実行ファイルに設定を渡す多くの場合、統合実行ファイルは、適切に動作するために設定を受け取る必要があります(例えば、監視対象システムのホスト名とポート、ユーザー認証情報など)。
Infrastructureエージェントでは、3つの方法で統合コマンドを設定することができます(組み合わせることも可能です)。
例:
exec: /opt/path/bin/script --host 127.0.0.1 --port 8081
STATUS_URL: http://10.0.0.3/server-status?auto
envelope
env
プロパティでは、実行ファイルに渡される環境変数を設定することができます。これは、必要な変数を含むキー・バリュー・マップです。
重要 New Relic では、1.8.0 以降のすべてのインフラストラクチャエージェントバージョンとの互換性のために、以下の例のように env
キーを大文字で渡すことを推奨しています。 エージェントバージョン 1.20.0 以上を使用している場合は、エージェントが自動的に 大文字にするため、小文字を使用することができます。 .
例:
COLLECTION_LIST: '["postgres"]'
COLLECT_DB_LOCK_METRICS: false
設定ファイルで明示的に指定するのではなく、ホストの環境から設定を受け取るようにしたい場合は、インフラストラクチャ・エージェントで必要な変数を設定する必要があります passthrough_environment
global configuration property
コンフィグ
ここでは、インテグレーションに設定情報を渡すさまざまな方法について説明します。
設定ファイルを直接渡す
統合コマンドの中には、外部ファイルから設定を取得するものがあります。インテグレーションが設定ファイルを必要とする場合、そのパスをコマンドライン引数や環境変数として直接渡すことを妨げるものは何もありません。ここでは、 Flex 統合 の設定を使った例を示します。
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 オブジェクトまたは単なる複数行の文字列を含めることができます。
CONFIG_FILE: ${config.path}
file: /Users/hello/test.csv
- name: other-integration
exec: /opt/integration/integration -f ${config.path}
example.cfg.logger=/var/logs/integration.log
example.cfg.hostname=localhost
上記の例では、 nri-flex
の統合が実行されるたびに、エージェントは以下の内容の一時ファイルを作成します。
file: /Users/hello/test.csv
上記のYAMLは、 nri-flex
の統合のための設定例に過ぎません。エージェントはその内容を無視します。代わりに一時ファイルを作成し、 ${config.path}をそのパスに置き換えます。
変数のプレースホルダーをそのパスに置き換えます。統合の実行が完了すると、一時ファイルは削除されます。
また、エージェントは other-integration
の統合を実行する前に、別の一時ファイルを作成します。
example.cfg.logger=/var/logs/integration.log
example.cfg.hostid=localhost
-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
file: /Users/hello/test.csv
パスシークレットとディスカバリーを コンフィグ
セクションで行う
外部ファイルのフルパスをハードコードする代わりに、 config
セクションを使用する主な利点は、 ${variable} を挿入できることです。
プレースホルダーを挿入して、 自動発見機能 と 秘密管理 を適用することができます。
ここでは、その例を挙げて説明します。
url: http://my.vault.host/v1/newengine/data/secret
X-Vault-Token: my-vault-token
exec: /opt/foo/bin/monitor --config=${config.path}
foo.port=${discovery.port}
foo.user=${my_credentials.user}
foo.password=${my_credentials.password}
ヒント ( 変数
と 発見
セクションの詳細については、 発見 と 秘密管理 のドキュメントをご覧ください)。
上記の例は、以下の前提に基づいています。
Vault サービスがあり、 user
と password
フィールドで形成される JSON オブジェクトを取得することができます。service=foo
と表示された可変数のDockerコンテナがあるかもしれません。これらのコンテナは、エージェントホストから発見可能なパブリックIPとポートを介してアクセスできます。ユーザは、 foo-monitor
インテグレーションを構成して、共通のユーザとパスワードを共有している service=foo
ラベル付きコンテナをすべて監視しています。 foo-monitor
統合の各インスタンスでは、 /opt/foo/bin/monitor
実行ファイルを実行し、 config
セクション内のテキスト構成を --config=<path>
コマンドライン引数で渡す必要があります。 ワークフローの例として、Vaultの呼び出しが次のようなJSONを返すとします。
{"user":"monitorer","password":"5up3r53cr3t!"}
foo-monitor
の統合を実行した時点で、 service=foo
とラベル付けされた3つの実行中のコンテナがあります。
ip: 10.0.0.3
, port: 8080
ip: 10.0.0.3
, port: 8081
ip: 10.0.0.3
, port: 8082
次に、エージェントは、 config
プロパティの内容をテンプレートとして使用し、 ${placeholders} を取得した変数と発見したアイテムで置き換えて、以下の3つの一時ファイルを作成します。
獲得した変数や発見したアイテムで置き換えます(ファイルのパスは単純化のために作成しています)。
最初のマッチ(/tmp/123_discovered
)。
foo.password=5up3r53cr3t!
2回目のマッチング(/tmp/456_discovered
)。
foo.password=5up3r53cr3t!
第三試合 (/tmp/789_discovered
)
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
統合実行ファイルに渡す設定ファイルの中で秘密管理と発見を使いたいが、個別のファイルとして残しておきたい場合は、 config_template_path:<path>
オプションを使うことができます。これは、 config
セクションとまったく同じように動作します。
エージェントは、 秘密管理 と 発見 をファイルの内容に適用します。
エージェントは、 ${config.path}を介して統合に渡される異なる一時ファイルを作成します。
プレースホルダー(または CONFIG_PATH
環境変数)を介して統合に渡されます。
例:
CONFIG_FILE: ${config.path}
config_template_path: /etc/flex-configs/redis.yml
上記の例では、 redis.yml
外部ファイルは、 ${discovery.ip} のようなコンテナ発見変数のプレースホルダを含むことができます。
または ${discovery.port} 。
.
エージェントが統合を実行する方法を設定するこのセクションのプロパティは、Infrastructureエージェントが統合を実行して対話する方法、またはエージェントが統合のデータを装飾する方法を変更します。
integration_user
統合コマンドは、エージェントと同じユーザーとして実行されます(通常は、 root
または nri-agent
)。パーミッションの制限により、統合を別のユーザーとして実行する必要がある場合は、その名前を integration_user
プロパティで指定する必要があります。
例:
exec: python my-dbus-script.py
インターバル
interval
オプションは、積分を連続して実行する間の時間を設定します。整数値の直後に時間単位を指定します(s
(秒)、 m
(分)、 h
(時間))。
デフォルトは 30s
で、最小許容値は 15s
です。 15s
以下の値は、自動的に 15s
に設定されます。
例:
STATUS_URL: http://127.0.0.1/status
インベントリソース
すべてのインベントリアイテムは、 カテゴリ/ソース
タクソノミーの下でカタログ化されなければなりません。デフォルトでは、各統合インベントリは integration/
+ name
value として保存されます(例: integration/nri-apache
, integration/nri-mysql
)。
inventory_source
プロパティを使用すると、インベントリデータのデフォルトのタクソノミーを上書きすることができます。
例:
- /var/db/newrelic-infra/newrelic-integrations/bin/nri-apache
inventory_source: config/apache
上記の例では、 nri-nginx
のインベントリがあれば、New Relic UI の integration/nri-nginx
のソースの下に表示されます。 nri-apache
のインベントリは、 config/apache
の下に表示されます。
labels
ラベル
は、統合のために追加のメタデータを提供することができるキー・バリュー・マップです。エージェントは、これらのラベルを使用して、特定の統合インスタンスから受け取るメトリクス、イベント、およびインベントリを装飾します。
例:
inventory_source: config/apache
上記の例では、エージェントは、 nri-apache
インスタンスからのすべてのメトリクスとイベントを以下のフィールドで装飾します。
label.env
: production
label.role
: load_balancer
また、統合インベントリに以下の項目が追加されています。
config/apache/labels/env
: production
config/apache/labels/role
: load_balancer
タイムアウト
timeout
値で指定された時間前に統合がメトリック(または後述するハートビートメッセージ)を返さなかった場合、エージェントは統合プロセスを終了し、対応する 間隔
後に再起動します。形式としては、整数値の直後に(スペースを入れずに)時間単位(ms
(ミリ秒)、 s
(秒)、 m
(分)、 h
(時間))を指定します。
ゼロ(またはマイナス)の timeout
値が提供された場合、統合はタイムアウトの満了によって殺されることなく永遠に実行されます。
長時間稼働する統合(定期的にメトリクス/イベント/インベントリを返しながら稼働し続ける統合)では、統合がメトリクス/イベント/インベントリのペイロードを提出するたびに、タイムアウトの期限が再開されます。つまり、長時間稼働する統合機能は、 timeout
よりも短い間隔で、有効な JSON ペイロードを返さなければなりません。
空のJSON({}
)を返すと、 heart-beat メッセージがタイムアウトを再開すると解釈され、報告すべき情報がなくても、長時間実行されている統合が殺されるのを防ぐことができます。
デフォルトは 120s
で、最小許容値は 100ms
です。 100ms
以下の値は、自動的に 100ms
に設定されます。
例:
JMX_HOST: jmx-host.localnet
COLLECTION_FILES: "/etc/newrelic-infra/integrations.d/jvm-metrics.yml"
作業用ディレクトリ
working_dir
は、コマンドの作業ディレクトリを設定します。空または未指定の場合、エージェントはInfrastructureエージェントのカレントディレクトリでコマンドを実行します。
デフォルトは、インフラストラクチャーエージェントのルートディレクトリです。
例:
exec: /opt/integration/bin/integration
working_dir: /opt/integration/scratch-zone
古い統合設定の更新 2019年12月、 Infrastructure agent version 1.8.0 は、異なる設定フォーマットの使用を開始しました。詳しくは、 Config format differences をご覧ください。
これらのフォーマットの主な違いは、古い設定フォーマットでは2つの独立した設定ファイル( INTEGRATION_NAME-definition.yml
ファイルと INTEGRATION_NAME-config.yml
ファイル)を使用し、新しいバージョンでは1つの設定ファイルを使用することです。
ここでは、新しい設定機能によって追加された機能をご紹介します。
コマンドライン引数、環境変数、外部ファイルによる柔軟な設定が可能です。 異なる統合機能を同じファイルにまとめることができる。 ホットリロード:新しい統合を追加したり、その構成を変更したりする際に、エージェントを再起動する必要がありません。 タイムアウト:ユーザーが指定した時間までに統合が応答しなかった場合、統合プロセスは強制終了して再起動されます。 すべてのオンホスト統合に新しい設定形式が用意されているわけではありませんが、すべてのオンホスト統合の設定を新しい形式に更新することで、新機能を利用することができます。
以下のYAMLは、古い設定形式を使用したApache統合 の設定例を示しています。なお、この設定は新しいエージェントでも動作しますが、機能を最大限に活用するために統合を更新することをお勧めします。
integration_name: com.newrelic.apache
- name: apache-server-metrics
status_url: http://127.0.0.1/server-status?auto
- name: apache-server-inventory
古い統合設定を新しいフォーマットに更新するには、次のいずれかの方法を使用します。
アシスト方式 New Relic CLI を使って、以下のコマンドを実行すると、古い定義・設定ファイルが新しい設定形式に自動的に変換されます。
$ newrelic agent config migrateV3toV4 -d /path/definitionFile -c /path/configFile -o /path/outputFile
例:
Redis 以下のパスは、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
Microsoft SQL 以下のパスは、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'
マニュアル方式 統合ファイルを手動で変換する場合
インスタンス
トップレベルのセクションの名前を インテグレーション
に変更。integration_name
トップレベルのセクションを削除して、各統合エントリに追加します。統合の種類ごとに個別のファイルを用意する必要がなくなり、レガシー統合のエントリを他の統合と同じファイルにまとめることができます。ここでは、新バージョンのApache統合設定の例を紹介します。
STATUS_URL : http : //127.0.0.1/server - status ? auto
STATUS_URL : http : //127.0.0.1/server - status ? auto
inventory_source : config/apache
重要 古い構成形式はホットリロードをサポートしていないことに注意してください。そのため、古い統合構成を削除するには、Infrastructureエージェントを再起動する必要があります。そうしないと、古いインスタンスが新しいインスタンスと共存してしまいます。