뉴렐릭 피규어 에이전트 온-호스트 통합 은 실행 파일과 하나 이상의 설정 파일 등 두 개 이상의 파일로 구성됩니다. 실행 파일은 에이전트 에이전트가 사용하고 뉴렐릭으로 전송되는 JSON 데이터를 생성합니다. 우리는 JSON 객체를 SDK 통합 프로토콜이라고 부릅니다.
실행 파일 요구 사항
실행 파일은 명령줄 인터페이스에서 실행되는 모든 파일일 수 있습니다. 예를 들어:
- 쉘 스크립트
- 스크립팅 언어 스크립트
- 컴파일된 바이너리
실행 파일의 유일한 요구 사항은 이 문서의 사양 을 충족하는 JSON 데이터를 한 줄 형식으로 내보내는 것입니다.
권장사항: Go를 사용하여 통합을 생성하세요. 우리가 온호스트 통합과 통합 구축 도구를 만드는 데 사용하는 언어입니다. 그러나 어떤 언어로든 통합을 생성할 수 있습니다.
파일 배치
실행 파일은 다음 디렉토리에 있습니다.
Linux:
/var/db/newrelic-infra/custom-integrationsWindows:
C:\Program Files\New Relic\newrelic-infra\newrelic-integrations
통합 프로토콜 v4: JSON 출력 예시
다음 섹션에서는 새로운 JSON 스키마(통합 프로토콜 v4)에 대해 설명합니다. SDK v4는 이 새 프로토콜 버전만 지원합니다. 다음은 가장 중요한 변경 사항입니다.
- 최상위 수준의 새
integration개체입니다. entity및metrics개체가 수정되었습니다.
자세한 내용은 v3에서 v4로 마이그레이션 가이드 를 참조하세요.
{ "protocol_version":"4", # protocol version number "integration":{ # this data will be added to all metrics and events as attributes, # and also sent as inventory "name":"integration name", "version":"integration version" }, "data":[ # List of objects containing entities, metrics, events and inventory { "entity":{ # this object is optional. If it's not provided, then the Entity will get # the same entity ID as the agent that executes the integration. "name":"redis:192.168.100.200:1234", # unique entity name per customer account "type":"RedisInstance", # entity's category "displayName":"my redis instance", # human readable name "metadata":{} # can hold general metadata or tags. Both are key-value pairs that will # be also added as attributes to all metrics and events }, "metrics":[ # list of metrics using the dimensional metric format { "name":"redis.metric1", "type":"count", # gauge, count, summary, cumulative-count, rate or cumulative-rate "value":93, "attributes":{} # set of key-value pairs that define the dimensions of the metric } ], "inventory":{...}, # Inventory remains the same "events":[...] # Events remain the same } ]}통합 프로토콜 v3: JSON 출력 예시
JSON에는 다음이 포함됩니다.
- 기본 통합 데이터(이름, 버전)가 있는 헤더
- 데이터(메트릭, 인벤토리 및/또는 이벤트 데이터)를 보고하는 하나 이상의 엔터티 가 포함된 데이터 목록
이 다이어그램은 다음 구조를 보여줍니다.
다음은 JSON 출력의 예입니다(가독성을 위해 줄 바꿈으로 형식 지정됨). 정의 및 사양은 다음 예를 따릅니다.
{ "name": "my.company.integration", "protocol_version": "3", "integration_version": "x.y.z", "data": [ { "entity": { "name": "my_garage", "type": "building", "id_attributes": [ { "key": "environment", "value": "production" }, { "key": "node", "value": "master" } ] }, "metrics": [ { "temperature": 25.3, "humidity": 0.45, "displayName": "my_garage", "entityName": "building:my_garage", "event_type": "BuildingStatus" } ], "inventory": { "out_door": { "status": "open" } }, "events": [] }, { "entity": { "name": "my_family_car", "type": "car", "id_attributes": [ { "key": "environment", "value": "production" }, { "key": "node", "value": "master" } ] }, "metrics": [ { "speed": 95, "fuel": 768, "displayName": "my_family_car", "entityName": "car:my_family_car", "event_type": "VehicleStatus" } ], "inventory": { "motor": { "brand": "renault", "cc": 1800 } }, "events": [ { "category": "gear", "summary": "gear has been changed" } ], "add_hostname": true } ]}JSON: 일반 사양
다음은 JSON 출력에 대한 일반 사양입니다.
JSON: 헤더
다음은 호스트 통합 JSON 출력 의 첫 번째 부분의 예입니다.
"name":"com.myorg.nginx",
"protocol_version":"3",
"integration_version":"1.0.0",
"data": [ {entities}...]최소 페이로드는 헤더 필드만 있는 JSON 객체입니다. 권장사항: 수집할 데이터가 없으면 프로그램 반환 코드와 stderr 에 기록된 로그 메시지를 사용하세요.
JSON 헤더 필드 | 설명 |
|---|---|
| 필수의. 구성 파일의 권장 사항: 역방향 도메인 이름을 사용하여 고유한 통합 이름을 생성하세요. |
| 필수의. 통합 실행 파일이 사용 중인 에이전트와 통합 간의 교환 프로토콜 버전 번호입니다.
|
| 선택 과목. 통합 버전. 각 호스트에서 실행 중인 통합 버전을 추적하는 데 사용됩니다. 통합에는 둘 이상의 실행 파일이 있을 수 있습니다. 따라서 이것은 단순히 실행 파일의 버전이 아닙니다. |
| 데이터 보고에 필요합니다. 하나 이상의 엔터티에서 보고된 데이터 가 포함된 목록입니다. |
JSON: 엔티티
JSON 출력 의 data 목록 내부에는 하나 이상의 항목이 있습니다. 엔터티 입력 필드에는 다음이 포함됩니다.
엔터티 JSON 필드 | 설명 |
|---|---|
| 필수의. 엔터티 데이터 또는 속성. |
| 선택 과목. 항목 관련 측정항목 목록입니다. |
| 선택 과목. 엔티티 관련 인벤토리 항목. |
| 선택 과목. 엔터티 관련 이벤트 목록입니다. |
| 선택 과목. 부울. |
JSON 출력 의 data 목록 내부에는 하나 이상의 항목과 해당 데이터가 있습니다. entity 항목에는 두 개의 필드가 있습니다.
항목 데이터 JSON 필드 | 설명 |
|---|---|
| 필수의. 엔티티의 식별자/이름. 권장 사항: 역방향 도메인 이름을 사용하여 고유한 통합 이름을 생성하세요. |
| 필수의. 엔터티의 종류입니다. 인프라 에이전트는 |
| 선택 과목. 엔터티에 고유성을 제공하는 키-값 속성 목록입니다. 가독성을 높이고 추가 정보를 제공하며 엔티티 이름 고유성을 개선하기 위해 식별자 속성은 엔터티 이름이 고유 식별자로 작동하기에 충분하지 않거나 의미 있는 정보를 충분히 제공하지 않을 때 유용합니다. 예를 들어: |
엔티티 이름에 대한 루프백 주소 대체
인프라 에이전트 버전 1.2.25 이상 에서 프로토콜 v3은 에이전트 수준에서 엔터티 이름에 로컬 주소 대체를 추가하여 원격 엔터티 고유성을 개선합니다.
여러 원격 엔티티가 엔드포인트( ip 또는 hostname )를 기반으로 하는 이름을 갖고 이 이름에 루프백 주소 가 포함된 경우 두 가지 문제가 있습니다.
- 이 localhost 값은 추가 컨텍스트 없이는 귀중한 정보를 제공하지 않습니다.
name은(는) 로컬 주소로 이름이 지정된 다른 서비스와 충돌할 수 있습니다.
다음과 같은 경우에 발생합니다.
- 엔드포인트 이름은
localhost:port과 같습니다. - 포트는 주어진 서비스에 대해 동일한 경향이 있습니다. 예를 들어 MySQL의 경우 3306입니다.
들어오는 프로토콜 v3 데이터에서 인프라 에이전트는 엔터티 이름(및 키)의 루프백 주소를 다음 목록에서 사용 가능한 첫 번째 항목으로 바꿉니다.
- 해당하는 경우 에이전트가 검색한 클라우드 제공자 인스턴스 ID
- 표시 이름, display_name 에이전트 구성 옵션 을 통해 설정
- 에이전트가 검색한 호스트 이름
예를 들어, 프로토콜 v3를 사용한 통합이 이름이 localhost:3306 인 엔티티를 반환하고 에이전트가 베어 메탈에서 실행 중인 경우(클라우드 제공자 인스턴스 ID가 없음) display_name이 설정되지 않고 호스트 이름이 prod-mysql-01 , 에이전트는 localhost 를 대체하고 엔티티 이름 prod-mysql-01:3306 을 생성합니다.
인프라 에이전트는 v3 통합 프로토콜에 대한 루프백 주소 교체를 자동으로 활성화합니다. 에이전트 구성 플래그 replace_v2_loopback_entity_names 를 통해 v2에 대해 이를 활성화할 수도 있습니다. 이 경우 v2를 사용하는 에이전트에 의해 실행되는 모든 통합은 로컬 주소를 가질 때마다 이름이 바뀝니다.
JSON: 메트릭, 인벤토리 및 이벤트 데이터
데이터 값은 실행 파일 헤더를 따릅니다. 세 가지 데이터 유형 을 기록할 수 있습니다.
중요
New Relic 대시보드의 관점에서 인프라 메트릭과 이벤트는 모두 이벤트 데이터 로 분류됩니다.