호스트 내 통합: 표준 구성 형식

필수 name 속성은 다음 두 가지 방식으로 작동할 수 있습니다.

• If the exec property is set: name 속성은 통합 인스턴스에 대한 식별자만 제공합니다. 이 식별자는 로그 메시지에 사용되며 integration/<name> 형식(예: integration/nri-redis)으로 기본 인벤토리 카테고리/소스를 제공합니다. 이 인벤토리 경로는 inventory_source 설정 옵션으로 재정의될 수 있습니다.

• If the exec property is not set: 에이전트는 다음 폴더 중 하나에서 name 값을 가진 실행 파일을 찾고 실행합니다.

  • 리눅스:

    • /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

나머지 통합 구성과 함께 구성 파일을 유지하려는 경우 유효한 YAML 객체 또는 여러 줄 문자열만 포함할 수 있는 통합 항목의 config 섹션을 사용할 수 있습니다.

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 서비스가 있습니다.
• 검색 가능한 공개 IP 및 포트를 통해 에이전트 호스트에서 액세스할 수 있는 service=foo 레이블이 지정된 다양한 Docker 컨테이너가 있을 수 있습니다.
• 사용자는 공통 사용자와 비밀번호를 공유하는 모든 service=foo 레이블이 지정된 컨테이너를 모니터링하도록 foo-monitor 통합을 구성했습니다. foo-monitor 통합의 각 인스턴스는 --config=<path> 명령줄 인수를 통해 config 섹션 내부의 텍스트 구성을 전달하고 /opt/foo/bin/monitor 실행 파일을 실행해야 합니다.

워크플로의 예로 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 속성의 내용을 템플릿으로 사용하여 다음 세 개의 임시 파일을 생성하지만 ${placeholders} 은 획득한 변수와 검색된 항목으로 대체합니다(파일 경로는 단순화를 위해 만들어졌습니다).

• 첫 번째 일치( /tmp/123_discovered ):

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

  카피

• 두 번째 일치( /tmp/456_discovered ):

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

  카피

• 세 번째 경기( /tmp/789_discovered )

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

  카피

config 변수 자리 표시자가 바뀌고 임시 파일이 생성된 후 /opt/foo/bin/monitor 실행 파일이 세 번(일치하는 컨테이너당 한 번) 실행되어 ${config.path} 명령줄 자리 표시자를 각각에 해당하는 임시 파일로 바꿉니다. 발견된 구성:

• 첫 경기: /opt/foo/bin/monitor --config=/tmp/123_discovered
• 두 번째 경기: /opt/foo/bin/monitor --config=/tmp/456_discovered
• 세 번째 경기: /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 인벤토리가 있는 경우 integration/nri-nginx 소스 아래의 New Relic UI에서 볼 수 있습니다. 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 ).

0(또는 음수) 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'