에이전트에 소켓 정보 보내기

에이전트가 소켓 속성 그룹을 하나 이상 포함할 때, 에이전트는 소켓을 열고 클라이언트의 데이터를 인식합니다.

에이전트에 소켓 데이터를 보내는 애플리케이션은 에이전트에 정의된 포트에 연결합니다. 이 포트는 에이전트 구성 특성에 설정된 값이거나 TCP/IP에 의해 자동으로 할당된 임시 포트입니다. 소켓 포트 및 구성에 대한 자세한 정보는 소켓 구성의 내용을 참조하십시오.

수신된 데이터는 구조화된 XML 형식을 따라야 합니다. 소켓 데이터 소스를 사용하여 다음과 같은 XML 정보 플로우가 가능합니다.
  • 샘플링된 속성 그룹에 대한 하나 이상의 데이터 행을 에이전트에 보냅니다.
  • 이벤트를 작성하는 속성 그룹에 대한 데이터 행을 에이전트에 보냅니다.
  • 데이터 대신 오류 코드를 에이전트에 보냅니다.
  • 태스크 접두어 등록을 에이전트에 보냅니다.
  • 에이전트에서 태스크 요청을 받습니다.
  • 태스크 응답을 에이전트에 보냅니다.

데이터 보내기

속성 그룹은 샘플링된 데이터 또는 이벤트 데이터를 수신하도록 정의됩니다. 속성 그룹을 작성할 때 데이터 수신 여부를 표시하는 옵션을 지정합니다.
  • 단일 데이터 행 작성
  • 둘 이상의 데이터 행 작성
  • 이벤트 작성

단일 데이터 행 작성 또는 둘 이상의 데이터 행을 작성할 수 있음을 선택하는 경우, 샘플링된 속성 그룹입니다. 이벤트 작성을 선택하는 경우, 속성 그룹은 행을 받을 때마다 모니터링 환경에 이벤트를 보냅니다.

Tivoli® Enterprise Portal 또는 IBM® Cloud Application Performance Management 콘솔에서 샘플링된 데이터를 볼 때, 최근 수집된 행 세트가 표시됩니다. 이벤트 속성 그룹에 대해 표시된 데이터는 에이전트가 유지보수하는 로컬 캐시 내용입니다. 이벤트 데이터의 경우, 에이전트가 새 항목을 캐시에 추가하며, 해당 크기에 도달하면 가장 오래된 항목이 삭제됩니다. 샘플링된 데이터의 경우, 에이전트는 사용자가 데이터를 보낼 때마다 캐시의 내용을 바꿉니다.

이벤트 작성 또는 단일 데이터 행 작성을 선택하는 경우, 각 메시지에서 해당 속성 그룹에 대한 하나의 데이터 행만 에이전트에 보내야 합니다. 원하는 수의 이벤트를 보낼 수 있지만, 하나의 메시지에서 하나의 이벤트를 보낼 수 있습니다.

일반적으로 샘플링된 데이터는 요청 시 에이전트에 의해 수집되지만, 소켓 클라이언트는 자체 스케줄에 따라 업데이트된 샘플을 제공합니다. 사용자는 샘플링된 속성 그룹(단일 행 또는 다중 행)을 필요할 때마다 업데이트할 수 있습니다. Tivoli Monitoring 또는 IBM Cloud Application Performance Management에서 데이터를 요청할 때, 에이전트는 최신 데이터를 제공합니다.

Tivoli Enterprise Portal 또는 IBM Cloud Application Performance Management 콘솔에서 소켓 속성 그룹에 대해 누락된 데이터 행이 있는 경우, 로그 파일에서 오류를 확인하십시오. 또한 속성 그룹의 데이터가 예상한 데이터가 아닌 경우, 로그 파일에서 오류를 확인하십시오. 소켓 데이터 소스는 가능한 입력이 무엇이든 처리하려고 합니다. 예를 들어, 클라이언트가 올바른 형식의 세 개 행과 올바르지 않은 하나의 행(예: 잘못된 XML)을 보내면 다음이 표시됩니다.
  • 속성 그룹의 세 개 데이터 행
  • 에이전트의 로그 파일에 잘못된 행에 대한 오류가 로그됨
  • 올바른 행이 리턴되었으면, 성능 오브젝트 상태에 NO_ERROR 상태가 표시됨
이벤트 및 샘플링된 데이터의 경우, 데이터가 소켓 클라이언트에서 단일 XML 데이터 플로우로서 에이전트에 보내집니다. 소켓 클라이언트에서 보낸 데이터는 항상 줄 바꾸기 문자 '\n'으로 끝나야 합니다. 에이전트는 줄 바꾸기 문자가 보일 때까지 데이터를 읽은 후에 받은 내용의 처리를 시도합니다. 처리 불가능한 수신 데이터는 버려집니다. 다음은 이름이 abc로 지정된 속성 그룹에 대한 데이터의 두 개 행을 에이전트에 보내는 방법의 샘플입니다.
<socketData><attrGroup name="abc"><in><a v="1"/><a v="no"/><a v="5"/></in><in> \
<a v="3"/><a v="yes"/><a v="5"/></in></attrGroup></socketData>\n
이 샘플은 각 행이 세 개의 속성을 포함하는 데이터의 두 개 행을 에이전트에 보냅니다. 속성의 순서가 중요하며, 속성 그룹에 정의된 순서를 따라야 합니다. 이에 대한 유일한 예외는 파생된 속성은 속성 그룹에 있는 위치와 상관없이 건너뛰어야 한다는 것입니다.

속성 그룹이 하위 노드에서 정의된 경우, 데이터를 에이전트에 보낼 때 하위 노드 인스턴스 ID를 식별해야 합니다. 하위 노드 인스턴스 ID는 socketData 요소의 하위 노드 속성을 사용하여 식별됩니다. 클라이언트가 인스턴스 ID 또는 구성 특성을 조회할 수 없으므로 소켓 클라이언트에서 사용할 하위 노드 인스턴스 ID를 구성하기 위한 규칙이 채택되어야 합니다. 구성되지 않은 하위 노드에 보낸 데이터는 무시됩니다.

다음은 샘플입니다. 
<socketData subnode="app1"><attrGroup name="abc"><in><a v="1"/><a v="no"/><a v="5"/>
</in><in> \<a v="3"/><a v="yes"/><a v="5"/></in></attrGroup></socketData>\n
이 샘플에서는, 인스턴스 ID가 "app1"인 하위 노드로 데이터가 보내집니다. "app1"은 관리 대상 시스템 이름이 아니라, 하위 노드 인스턴스가 구성될 때 지정되는 인스턴스 ID입니다.
다음의 XML 요소가 소켓 데이터를 구성합니다.
socketData
루트 요소. 하위 노드 인스턴스 ID를 지정하는 subnode라는 선택적 속성을 가집니다.
attrGroup
이 요소는 소켓 데이터의 대상 속성 그룹을 식별합니다. name 속성이 필수이며, 속성 그룹 이름을 지정하는 데 사용됩니다.
in
이 요소는 새 데이터 행을 식별하는 데 필요합니다. 데이터 행의 모든 속성 값이 동일한 in 요소의 하위여야 합니다.
a
a 요소는 속성 값을 식별합니다. v 속성이 필수이며, 속성 값을 지정하는 데 사용됩니다.

데이터 대신 오류 보내기

소켓 데이터를 게시하는 애플리케이션이 속성 그룹에 필요한 데이터를 수집하지 못하는 경우도 있습니다. 이 경우 에이전트에 데이터를 보내는 대신 오류 코드가 리턴될 수 있습니다. 오류 코드는 모니터링 환경에 문제에 대해 알리는 방법을 제공합니다. 예제 오류는 다음과 같습니다. 
<socketData><attrGroup name="abc"/><error rc="1000"/></attrGroup></socketData>\n
오류 코드는 에이전트에서 모든 소켓 속성 그룹에 공통인 목록에 정의해야 합니다. 에이전트가 오류 코드를 받으면, 정의된 오류 메시지가 에이전트 로그 파일에 로그됩니다. 또한 성능 오브젝트 상태 이름의 속성 그룹에는 오류 코드 유형으로 업데이트되는 오류 코드 속성이 있습니다. 오류 코드 유형은 사용자가 보낸 오류 코드에 대해 정의됩니다.
이전 예제의 경우, 에이전트에서 오류 코드 값 1000을 정의해야 합니다. 다음 샘플 오류 코드 정의를 참조하십시오.
표 1. 샘플 오류 코드
오류 코드 값 오류 코드 유형 메시지
1000 APP_NOT_RUNNING 애플리케이션이 실행 중이 아님
오류 코드가 보내지면, 다음과 유사한 메시지가 에이전트 로그 파일에 로그됩니다.
(4D7FA153.0000-5:customproviderserver.cpp,1799,"processRC") 클라이언트로부터 오류 코드 1000을 받았습니다. \메시지: K1C0001E 애플리케이션이 실행 중이 아님

Tivoli Enterprise Portal에서 성능 오브젝트 상태 조회를 선택하는 경우, 해당 테이블의 abc 속성 그룹에 대한 오류 코드 컬럼에 APP_NOT_RUNNING 값이 표시됩니다.

오류를 샘플링된 속성 그룹에 보내면 해당 속성 그룹에 대해 이전에 받은 데이터를 지웁니다. 데이터를 속성 그룹에 보내면 성능 오브젝트 상태 속성 그룹에 오류 코드가 더 이상 표시되지 않습니다. 해당 테이블에서 오류 코드를 지우도록 오류 코드 0을 보낼 수도 있습니다.

이벤트를 작성하는 속성 그룹에 오류를 보내면 이전에 보낸 이벤트의 캐시를 지우지 않습니다.

조치 수행 요청 처리

소켓 클라이언트는 조치 명령이 특정 접두어와 일치할 때 에이전트에서 조치 수행 요청을 받도록 등록할 수 있습니다. 일치하지 않는 조치는 에이전트에서 처리합니다. 접두어는 에이전트가 처리하도록 예상되는 조치와 충돌하지 않아야 하므로, 에이전트 제품 코드를 접두어로 사용하십시오. Agent Builder에 제공되는 조치 수행은 조치 수행이 사용하는 데이터 소스의 이름을 땁니다. 예를 들어, JMX_INVOKE 조치 수행은 JMX 데이터 소스에 대해 작업합니다. 또 다른 예는 SSH 스크립트 데이터 제공자를 사용하는 SSHEXEC 조치 수행입니다. 이러한 조치에서는 제품 코드를 사용하지 않으므로, 제품 코드는 조치 수행 접두어로 사용하기에 안전한 접두어입니다.

소켓 클라이언트는 장기 실행 중이며 소켓을 열어 놓아야 합니다. 접두어에 대한 등록 요청을 보내고 소켓으로부터의 요청을 인식해야 합니다. 에이전트는 플로우되는 데이터가 없어도 장기 실행 클라이언트 소켓의 제한시간 초과를 발생시키지 않습니다. 다음은 샘플 등록 요청입니다. 
<taskPrefix value="K42"/>\n
이 샘플에서는 "K42"로 시작하는 조치 수행 명령이 에이전트에 의해 수신되어 등록을 시작한 소켓 클라이언트로 전달됩니다. 다음은 소켓 클라이언트가 받을 수 있는 샘플 조치 수행 요청을 보여줍니다. 
<taskRequest id="1"><task command="K42 refresh" user="sysadmin"/></taskRequest>\n
id는 에이전트가 클라이언트로 보내는 요청을 추적하는 데 사용하는 고유 ID입니다. 소켓 클라이언트가 태스크에 응답할 때, taskResponse 요소의 id 속성에서 이 ID를 제공해야 합니다.
소켓 클라이언트가 조치를 처리하고 응답을 보내야 합니다. 샘플 응답은 다음과 같습니다. 
 <taskResponse id="1" rc="1"/>\n

조치가 성공적으로 완료되면, rc 속성값 0이 리턴됩니다. rc 값은 정수여야 하며, 0 이외의 모든 값은 실패로 간주됩니다. 태스크 리턴 코드 값은 에이전트 로그 파일에 로그되고, 에이전트에 포함되는 조치 수행 상태 조회에 표시됩니다. 조치 실행 이후 Tivoli Enterprise Portal에서 표시되는 대화 상자에는 리턴 코드가 표시되지 않습니다. 해당 대화 상자는 조치 수행 명령이 성공 또는 실패를 리턴했는지 여부를 표시합니다. 실패가 발생한 경우 실제 리턴 코드를 판별하려면 에이전트 로그 또는 조치 수행 상태 조회를 봐야 합니다.

에이전트와 함께 사용되는 소켓 클라이언트에서 지원되는 조치를 문서화하고, 작성하고, 가져오는 것은 에이전트 개발자의 책임입니다. 사용자가 지원되지 않는 조치를 소켓 클라이언트에 보내는 경우, 클라이언트가 이러한 시나리오를 적절한 방법으로 처리하도록 개발되어야 합니다. 사용자가 등록된 접두어로 시작하는 추가 조치를 정의하는 경우, 클라이언트로 전달됩니다. 해당 시나리오를 적절한 방법으로 처리하도록 클라이언트를 개발해야 합니다.

에이전트가 소켓 클라이언트의 응답을 기다리는 시간을 제어하는 제한시간이 있습니다. 이 설정은 에이전트에서 정의되는 CDP_DP_ACTION_TIMEOUT이라는 환경 변수이며, 기본값은 20초입니다.

참고: 소켓 데이터 소스 속성 그룹에 대해 정의된 오류 코드 메시지는 조치 수행에 사용되지 않습니다. 동일한 리턴 코드 값을 리턴할 수 있습니다. 그러나 에이전트가 정의된 메시지를 로그하거나 성능 오브젝트 상태 속성 그룹의 Error Code 필드에 영향을 주지는 않습니다.