WhaTap Telegraf Agent Guide

제목 : WhaTap Telegraf Agent Guide
작성자 : WhaTap Support
이메일 : support@whatap.io
날짜 : 2020-10-28
버전 : 1.0.2

설명 : 본 문서는 WhaTap Telegraf 에이전트에 대해 설명합니다.

1. 개요

Telegraf 에서 수집하는 매트릭스를 와탭 수집서버로 전달할 수 있습니다.
수집된 데이터는 whatap의 프로젝트 내부에서 확인 가능합니다.

1.1. Telegraf 내 whatap output plugin을 이용

Telegraf 에 포함된 whatap plugin 을 사용합니다.

Telegraf 오픈 소스 내에 whatap plugin 의 리뷰가 진행 중입니다.
정식 배포 전에는 whatap plugin을 포함하는 Telegraf를 교체해서 사용합니다.

1.2. whatap-telegraf 에이전트 설치

whatap-telegraf 에이전트를 설치하여 Telegraf 매트릭스 데이터를 중계합니다.

기존에 설치된 Telegraf의 socket_writer output plugin을 활성화하여 whatap-telegraf(Local TCP) 에이전트로 데이터를 전달합니다.
whatap-telegraf 에이전트는 Telegraf 에서 전달 받은 데이터를 수집서버로 중계합니다.

2. Telegraf

Telegraf는 데이터베이스, 시스템 및 IoT 센서에서 메트릭 및 이벤트를 수집하고 전송하기위한 플러그인 중심 서버 에이전트입니다. Telegraf는 Go로 작성되었으며 외부 종속성없이 단일 바이너리로 컴파일되며 최소한의 메모리 공간 만 필요합니다.

2.1. 모든 종류의 데이터 수집 및 전송

데이터베이스 : MongoDB, MySQL, Redis 등의 데이터 소스에 연결하여 메트릭을 수집하고 보냅니다. 시스템 : 현대적인 클라우드 플랫폼, 컨테이너 및 오케 스트레이터 스택에서 메트릭을 수집합니다. IoT 센서 : IoT 센서 및 장치에서 중요한 상태 저장 데이터 (압력 수준, 온도 수준 등)를 수집합니다.

2.2. plugin

Telegraf는 메트릭을 수집, 처리, 집계 및 작성하는 플러그인 중심 에이전트입니다. 입력, 출력, 애그리 게이터 및 프로세서를 포함한 4 가지 범주의 플러그인을 지원합니다.

2.2.1. SNMP

SNMP input plugin을 사용하여 SNMP 성능 데이터를 실시간으로 수집 및 챠트 표시 가능합니다. 수집된 데이터는 telegraf_snmp, telegraf_interface 카테고리로 검색하실 수 있습니다.

Linux Shell
cat >/etc/telegraf/telegraf.d/snmp_device.conf <<EOL
[[inputs.snmp]]
  ## Agent addresses to retrieve values from.
  ##   format:  agents = ["<scheme://><hostname>:<port>"]
  ##   scheme:  optional, either udp, udp4, udp6, tcp, tcp4, tcp6.
  ##            default is udp
  ##   port:    optional
  ##   example: agents = ["udp://127.0.0.1:161"]
  ##            agents = ["tcp://127.0.0.1:161"]
  ##            agents = ["udp4://v4only-snmp-agent"]

  agents = ["udp://1.1.1.1:161"]

  ## Timeout for each request.
  # timeout = "5s"

  ## SNMP version; can be 1, 2, or 3.
   version = 2

  ## SNMP community string.
   community = "xxxx@xxxxx"

  ## Agent host tag
  # agent_host_tag = "agent_host"

  ## Number of retries to attempt.
  # retries = 3

  ## The GETBULK max-repetitions parameter.
  # max_repetitions = 10

  ## SNMPv3 authentication and encryption options.
  ##
  ## Security Name.
  # sec_name = "myuser"
  ## Authentication protocol; one of "MD5", "SHA", "SHA224", "SHA256", "SHA384", "SHA512" or "".
  # auth_protocol = "MD5"
  ## Authentication password.
  # auth_password = "pass"
  ## Security Level; one of "noAuthNoPriv", "authNoPriv", or "authPriv".
  # sec_level = "authNoPriv"
  ## Context Name.
  # context_name = ""
  ## Privacy protocol used for encrypted messages; one of "DES", "AES", "AES192", "AES192C", "AES256", "AES256C", or "".
  ### Protocols "AES192", "AES192", "AES256", and "AES256C" require the underlying net-snmp tools
  ### to be compiled with --enable-blumenthal-aes (http://www.net-snmp.org/docs/INSTALL.html)
  # priv_protocol = ""
  ## Privacy password used for encrypted messages.
  # priv_password = ""

  ## Add fields and tables defining the variables you wish to collect.  This
  ## example collects the system uptime and interface variables.  Reference the
  ## full plugin documentation for configuration details.
  [[inputs.snmp.field]]
    oid = "RFC1213-MIB::sysUpTime.0"
    name = "uptime"

  [[inputs.snmp.field]]
    oid = "RFC1213-MIB::sysName.0"
    name = "source"
    is_tag = true

  [[inputs.snmp.table]]
    oid = "IF-MIB::ifXTable"
    name = "interface"
    inherit_tags = ["source"]

  [[inputs.snmp.table.field]]
    oid = "IF-MIB::ifDescr"
    name = "ifDescr"
    is_tag = true

  [[aggregators.derivative]]
    period = "60s"
    max_roll_over = 1

    fieldpass = ["*Octets", "*Pkts"]
    drop_original = false

  [aggregators.derivative.tags]
    aggr = "derivative"

[[processors.starlark]]
  source = '''
def apply(metric):
    for (k, v) in metric.fields.items():
        if k.endswith('Octets_rate'):
            metric.fields[k] *= 8

    return metric

'''

EOL
service telegraf restart
SNMP Dashboard

TelegrafTrafficDashboard telegraf_interface 카테고리로 인터페이스 트래픽 대시보드를 구성할 수 있습니다.

Linux Shell
#사용 필드
#인바운드 트래픽
ifHCInOctets_rate
#아웃바운드 트래픽
ifHCOutOctets_rate
#인바운드 패킷
ifHCInUcastPkts_rate
#아웃바운드 패킷
ifHCOutUcastPkts_rate

2.2.2. SNMP Trap

SNMP Trap input plugin을 사용하여 SNMP Trap 이벤트를 실시간으로 수집 및 이메일, 문자메세지 및 메신저로 전파 가능합니다. 수집된 데이터는 telegraf_snmp_trap 카테고리로 검색하실 수 있습니다.

Linux Shell
#mib 파일 설치
apt install snmp-mibs-downloader
cat >/etc/telegraf/telegraf.d/snmp_trap.conf <<EOL
[[inputs.snmp_trap]]
  service_address = "udp://:162"
  path = ["/usr/share/snmp/mibs"]
EOL
service telegraf restart
SNMP Trap 매트릭스 알림
링크 다운 알림

LinkDownAlert 아래 json 파일을 매트릭스 알림에서 import하면 링크 다운 발생시 알림을 받으실 수 있습니다.

Linux Shell
[
  {
    "id": "z6lrn6v24sobl4",
    "category": "telegraf_snmp_trap",
    "rule": "sysUpTimeInstance > 0",
    "select": "name == 'linkUp' || name == 'linkDown'",
    "silentSec": 0,
    "eventTitle": "SNMP TRAP LINK EVENT",
    "eventMessage": "SNMP TRAP HOST ${host} LINK: ${ifDescr}(${ifAlias}) NAME:${name}",
    "repeatCount": 1,
    "repeatDuration": 5000,
    "relatedCategory": "[telegraf_interface]",
    "enabled": true,
    "eventLevelText": "Warning",
    "relatedPcode": [],
    "stateful": false
  }
]

3. whatap plugin

Telegraf의 whatap output plugin(tcp)을 통해 Telegraf에서 수집되는 매트릭스 정보를 와탭 수집서버로 전송합니다.

3.1. Telegraf 설치

Telegraf 오픈 소스에 whatap plugin을 추가하기 위해 리뷰가 진행 중입니다.
정식 배포 전에는 아래 다운로드 설치 및 컴파일 설치로 Telegraf를 설치합니다.

3.1.1. 다운로드 설치

Telegraf release 버전을 기준으로 whatap plugin을 추가하여 미리 생성한 설치파일입니다.

Telegraf가 이미 설치된 경우에는 실행파일만 교체하여 whatap plugin을 활성화할 수 있습니다.

3.1.2. 컴파일 설치

사전 준비 사항
  • Golang SDK 구성.

  • go dep 설치

  • 소스파일
    Telegraf release 버전에 whatap plugin을 포함한 소스파일입니다.

${GOPATH}/src/github.com/influxdata/telegraf/ 디렉토리 밑에 압축을 해제합니다.

설치 절차

${GOPATH}/src/github.com/influxdata/telegraf 이하 Makefile로 빌드를 진행합니다.

  1. 의존성 설치를 진행합니다. 의존성 설치는 go dep을 사용하기 때문에 go dep이 먼저 설치되어야 합니다.

    # make deps
  2. 실행파일을 빌드합니다.
    ${GOPATH}/bin 디렉토리에 실행파일(telegraf)이 생성됩니다.

    # make go-install

설치 패키지가 필요하다면 make package 명령어로 생성할 수 있습니다. 크로스 컴파일을 진행하여 운영체제 별로 패키지 파일을 생성합니다.

# make package
상세한 빌드의 설명은 Telegraf github 내용을 참고해 주세요
https://github.com/influxdata/telegraf

3.2. 설정

Telegraf의 config 파일(telegraf.conf)에 아래 outputs.whatap 설정을 활성화합니다.

whatap plugin이 포함된 config 파일은 아래와 같이 생성할 수 있습니다.

# telegraf --sample-config > telegraf.conf

3.2.1. whatap 프로젝트 정보

http://whatap.io 에서 프로젝트의 정보를 설정합니다. 연결할 프로젝트의 에이전트 설치 안내에서 확인 가능합니다.

  • 프로젝트 라이선스 키 : 프로젝트를 식별하는 라이선스 키 입니다.

  • 프로젝트 코드: 프로젝트를 식별하는 숫자형 코드 입니다.

  • 수집서버 정보 (아이피, 포트) : 수집정보를 전달할 와탭 수집서버의 아이피와 포트 입니다.

3.2.2. config 설정(toml)

  • [[outputs.whatap]] 주석(#)을 삭제합니다.

  • license의 주석(#)을 삭제합니다. 프로젝트의 라이선스 키 정보를 입력합니다. (문자형으로 입력합니다.)

  • pcode의 주석(#)을 삭제합니다. 프로젝트 코드를 입력합니다. (숫자형으로 입력합니다.)

  • servers의 주석(#)을 삭제합니다. 수집서버 정보(아이피,포트) 를 설정합니다.
    프로토콜은 tcp만 지원합니다.문자 형식으로 "tcp://아이피:포트"를 등록합니다.
    배열 형식으로 등록합니다. 콤마(,)로 구분하여 배열 형식으로 등록합니다.

/etc/telegraf/telegraf.conf
# # Configuration for WhaTap
[[outputs.whatap]]
#   ## You can create a project on the WhaTap site(https://www.whatap.io)
#   ## to get license, project code and server IP information.
#
#   ## WhaTap license. Required
license = "x2tggtnopk2t9-xxxxxxxxxx-aaaaaaaaaa"
#
#   ## WhaTap project code. Required
pcode = 118
#
#   ## WhaTap server IP. Required
#   # Put multiple IPs with / as delimiters. e.g. "1.1.1.1/2.2.2.2"

servers = ["tcp://1.2.3.4:6600", "tcp://5.6.7.8:6600"]

#   ## Connection timeout.
#   # timeout = "60s"
Telegraf 를 재시작하면 변경된 설정이 적용됩니다.

4. whatap-telegraf Install

4.1. 에이전트 실행 및 모니터링 개요

Telegraf 수집 데이터를 와탭 수집서버로 전송하는 기능을 제공합니다.

4.1.1. 지원

운영체제
  • Linux Redhat 6.x x64 이상

  • Ubuntu 12.x x64 이상

  • FreeBSD 10.x x64 이상

Telegraf

socket_writer ouput plugin을 지원하는 버전만 가능합니다.

  • Telegraf 1.3 이상

4.1.2. 에이전트 설치 방식 개요

  • 와탭 저장소(Repository)를 설치합니다.

  • whatap-telegraf 리눅스 패키지를(yum, apt-get) 설치합니다.

  • 라이센스 및 와탭 서버 정보를 설정합니다.

  • Telegraf 의 socket_writer output plugin을 설정하여 데이터를 연동합니다.

4.1.3. 구성 파일

Telegraf 정보를 수집하기 위한 에이전트 파일로 구성됩니다.

telegraf 에이전트를 구성하는 각 파일의 역할은 다음과 같습니다.

파일명

설명

whatap_telegraf

서비스 실행파일, Telegraf에서 전달된 정보를 수집서버로 전송하는 프로그램입니다.

/etc/init.d/whatap-telegraf (FreeBSD /usr/local/etc/whatap_telegraf)

서비스 스크립트

whatap.conf

설정파일입니다. 수집서버의 주소와 서버의 프로젝트 라이센스 키가 입력되는 파일입니다.

whatap-telegraf-#.log

에이전트 로그 파일 입니다. (/usr/whata/telegraf/logs)

4.1.4. 에이전트 이름 식별

와탭은 모니터링 정보 수집 대상인 애플리케이션 서버 식별을 위한 정보로 기본적으로 애플리케이션 서버로부터 수집한 정보를 활용합니다. 기본적으로 활용하는 정보는 애플리케이션 서버 종류, 애플리케이션 서버의 IP, 서비스 포트를 조합하여 애플리케이션 서버를 고유 식별자로 사용하게 되며 필요에 따라 사용자가 지정한 명칭을 사용하거나 패턴을 변경하여 사용하는 것도 가능합니다. 이때에는 꼭 고유한 값이어야 합니다.

애플리케이션 서버로부터 추출한 정보를 활용하는 이유는 애플리케이션 서버 정지, 네트워크 단절 또는 에이전트 문제로 인한 수집 서버와 에이전트의 통신 단절 상태가 복구되었을 경우, 재 접속된 에이전트로부터 송신되는 정보가 기존 에이전트로부터 송신된 정보와의 연속성을 유지하기 위해서 입니다. 와탭이 애플리케이션 서버를 식별하기 위해 사용하는 기본 패턴은 다음과 같습니다.

기본 패턴에 대한 변경은 whatap.conf에서 설정에서 가능합니다.

object_name default: Telegraf-{hostname}-{ip2}-{ip3}-{docker}

설정

설명

Type

app_name, 기본 telegraf

Hostname

호스트네임

Ip#

Ip를 .으로 나누었을 때 #번째 자리(0부터)

Process

app_process_name

docker

도커 컨테이너 아이디

4.2. 에이전트 설치

4.2.1. 패키지 설치

RedHat/CentOS
패키지 저장소(Repository) 등록

와탭 저장소(Repository)를 등록합니다.

$ sudo rpm -Uvh http://repo.whatap.io/centos/5/noarch/whatap-repo-1.0-1.noarch.rpm
패키지 설치

아래 명령어를 통해 패키지를 설치합니다.

$ sudo yum install whatap-telegraf
설정 스크립트를 실행하여 서비스를 시작합니다.
echo "license=[발급받은 라이센스]" |sudo tee /usr/whatap/telegraf/whatap.conf
echo "whatap.server.host=[와탭 서버 주소]" |sudo tee -a /usr/whatap/telegraf/whatap.conf
sudo service whatap-telegraf restart
Debian/Ubuntu
패키지 저장소(Repository) 등록

와탭 저장소(Repository)를 등록합니다.

$ wget http://repo.whatap.io/debian/release.gpg -O -|sudo apt-key add -
$ wget http://repo.whatap.io/debian/whatap-repo_1.0_all.deb
$ sudo dpkg -i whatap-repo_1.0_all.deb
$ sudo apt-get update
패키지 설치
$ sudo apt-get install whatap-telegraf
설정 스크립트를 실행하여 서비스를 시작합니다.
echo "license=[발급받은 라이센스]" |sudo tee /usr/whatap/telegraf/whatap.conf
echo "whatap.server.host=[와탭 서버 주소]" |sudo tee -a /usr/whatap/telegraf/whatap.conf
sudo service whatap-telegraf restart
Amazon Linux
패키지 저장소(Repository) 등록

와탭 저장소(Repository)를 등록합니다.

$ sudo rpm --import http://repo.whatap.io/centos/release.gpg
$ echo "[whatap]" | sudo tee /etc/yum.repos.d/whatap.repo > /dev/null
$ echo "name=whatap packages for enterprise linux" | sudo tee -a /etc/yum.repos.d/whatap.repo > /dev/null
$ echo "baseurl=http://repo.whatap.io/centos/latest/\$basearch" | sudo tee -a /etc/yum.repos.d/whatap.repo > /dev/null
$ echo "enabled=1" | sudo tee -a /etc/yum.repos.d/whatap.repo > /dev/null
$ echo "gpgcheck=0" | sudo tee -a /etc/yum.repos.d/whatap.repo > /dev/null
패키지 설치
$ sudo yum install whatap-telegraf
설정 스크립트를 실행하여 서비스를 시작합니다.
echo "license=[발급받은 라이센스]" |sudo tee /usr/whatap/telegraf/whatap.conf
echo "whatap.server.host=[와탭 서버 주소]" |sudo tee -a /usr/whatap/telegraf/whatap.conf
sudo service whatap-telegraf restart
FreeBSD
패키지 설치
$ wget https://s3.ap-northeast-2.amazonaws.com/repo.whatap.io/freebsd/10/whatap-telegraf-0.0.4.txz
$ pkg install whatap-telegraf-0.0.4.txz
설정 스크립트를 실행하여 서비스를 시작합니다.
echo "license=[발급받은 라이센스]" | tee /usr/whatap/telegraf/whatap.conf
echo "whatap.server.host=[와탭 서버 주소]" | tee -a /usr/whatap/telegraf/whatap.conf
sudo service whatap_telegraf restart

4.2.2. Telegraf 연동

Telegraf 설정

Telegraf 에 socket_writer output plugin 설정을 하여 whatap-telegraf 로 수집된 정보를 전달합니다.

  • [[outputs.socket_writer]] 주석을 해제합니다.

  • address 항목에 tcp 연결을 설정합니다.

  • 데이터 유형은 json 형식으로 설정합니다.

# # Generic socket writer capable of handling multiple socket types.
 [[outputs.socket_writer]]

#   ## URL to connect to
    address = "tcp://127.0.0.1:6600"

#   # data_format = "influx"
    data_format = "json"

4.2.3. 실행

애플리케이션 재시작

설치가 완료된 후 whatap-telegraf 서비스를 재시작합니다.

whatap-telegraf 서비스 재시작

whatap-telegraf 서비스(Service)가 실행 중이지 않거나 오류가 발생한 경우 재시작합니다.

Redhat/CentOS
$ service whatap-telegraf restart
Debian/Ubuntu
$ sudo service whatap-telegraf restart
FreeBSD
$ service whatap_telegraf restart

4.2.4. 업데이트

패키지 업데이트는 기존 설정을 유지한 채로 업데이트합니다.

Redhat/CentOS

패키지 정보 갱신을 위해 캐시 정보를 삭제합니다.

$ yum clean all

whatap-telegraf 패키지를 업데이트 합니다.

$ yum update whatap-telegraf
NOTE

특정 버전을 설치하기 위해서는 설치 시 버전 정보를 명시해 줍니다.

$ sudo yum install whatap-infra-<version>
Debian/Ubuntu

패키지 정보 갱신을 위해 캐시 정보를 갱신합니다.

$ sudo apt-get update

whatap-telegraf 패키지를 업데이트 합니다.

$ sudo apt-get install --only-upgrade whatap-telegraf
NOTE

특정 버전을 설치하기 위해서는 설치 시 버전 정보를 명시해 줍니다.

$ sudo apt-get install whatap-infra=<version>
FreeBSD

패키지를 재설치합니다.

# wget https://s3.ap-northeast-2.amazonaws.com/repo.whatap.io/freebsd/10/whatap-telegraf-0.0.4.txz
# pkg install whatap-telegraf-0.0.4.txz
NOTE

특정 버전을 설치하기 위해서는 <version>의 위치에 특정 버전을 입력하여 재설치를 진행합니다.

# wget https://s3.ap-northeast-2.amazonaws.com/repo.whatap.io/freebsd/10/whatap-telegraf-<version>.txz
# pkg install whatap-telegraf-<version>.txz

4.2.5. 중지

일시 중지
whatap-telegraf 서비스(Service) 중지
Redhat/CentOS
$ sudo service whatap-telegraf stop
Debian/Ubuntu
$ sudo service whatap-telegraf stop
FreeBSD
$ service whatap_telegraf stop
에이전트 삭제

패키지(yum, apt-get) 삭제를 진행하고 필요에 따라서 /usr/whatap/telegraf 아래에 로그 파일 및 기타 파일을 삭제합니다.

패키지 삭제
Redhat/CentOS
$ sudo yum remove whatap-telegraf
Debian/Ubuntu
$ sudo apt-get purge whatap-telegraf
FreeBSD
$ pkg delete whatap-telegraf
/usr/whatap/telegraf 디렉토리 삭제

4.3. 설정

4.3.1. 에이전트 네이밍

object_name

Default : {type}-{hostname}-{ip2}-{ip3}-{docker}
Type : String
애플리케이션을 식별하는 에이전트 이름(ONAME)체계입니다. ONAME을 토대로 OID가 생성됩니다.

명칭

설명

{type}

app_name 에 설정된 값을 사용합니다. 기본값은 Telegraf 입니다.

{ip#}

IP를 나누었을 때 #번째 자리를 사용합니다.

{hostname}

서버 호스트명을 사용합니다.

{docker}

도커 컨테이너 아이디를 사용합니다.

app_name

Default : NONE
Type : String
애플리케이션을 식별하는 에이전트 이름(ONAME)체계에 사용되는 애플리케이션 명. object_name의 {type}에 해당하는 값이다.

whatap-telegraf 서비스 재시작 후 적용됩니다.

4.3.2. 에이전트 통신

license

Default : NONE
Type : String
에이전트 설치시 서버로부터 부여받은 라이센스를 지정합니다. 라이센스에는 에이전트가 속한 프로젝트와 보안 통신을 위한 암호키를 포함하고 있습니다.

whatap.server.host

Default : 127.0.0.1,127.0.0.1
Type : ip_address
에이전트가 수집한 데이터를 전송할 서버를 지정합니다. 수집서버 이중화로 2개 이상의 IP를 가진 경우 콤마(,)로 분리하여 지정할 수 있습니다. 지정된 IP 에는 수집서버 proxy 데몬이 리스닝 상태로 서비스 되어야 합니다.

whatap.server.port

Default : 6600
Type : tcp_port
수집서버 PORT 를 지정합니다. 포트는 하나만 지정할 수 있으므로 whatap_server_host 에 지정된 수집서버들은 동일 PORT 를 사용해야 합니다.

tcp_so_timeout

Default : 60000
Type : Millisecond
수집서버와 통신하는 TCP세션의 Socket Timeout 값을 지정합니다.

tcp_connection_timeout

Default : 5000
Type : Millisecond
수집서버와 통신하는 TCP세션의 Connection Timeout 값을 지정합니다.

net_send_max_bytes

Default : 5242880
Type : Byte
수집서버로 데이터를 전송할 때 한번에 전송되는 최대 크기를 지정합니다.

net_send_buffer_size

Default: 1024
Type: byte
데이터 전송을 하기 위해 가지고 있는 최대 바이트 크기입니다.

4.3.3. Telegraf

telegraf_tcp_port

Default: 6600
Type: tcp_port
Telegraf socker_writer output plugin이 연결할 TCP Port입니다.

whatap-telegraf 서비스 재시작 후 적용됩니다.
telegraf_delta_fields

Default: 1024
Type: string
누적 값을 가지는 필드의 증가값을 계산하여 별도의 필드를 추가합니다. name.fields 형식으로 지정하고, 여러 개는 콤마(,)로 구분합니다. e.g. nginx.accepts,nginx.requests nginx의 accepts, requests 값의 증가값을 acceptsDelta, requestsDelta 필드 이름으로 추가 전달합니다.

4.3.4. 로그

log_keep_days

Default : 7
Type : Day
로그파일 보관기간을 설정합니다

Unresolved directive in index.adoc - include::3_data.adoc[leveloffset=+1]