ServiceWatch Agent 사용하기

사용자는 Virtual Server/GPU Server/Bare Metal Server 등에서 ServiceWatch Agent를 설치하여 사용자 정의 지표와 로그를 수집할 수 있습니다.

ServiceWatch Agent

서버에 ServiceWatch의 사용자 정의 지표 및 로그 수집을 위해 설치해야 하는 Agent는 크게 2가지로 나눌 수 있습니다. Prometheus Exporter와 Open Telemetry Collector 입니다.

ServiceWatch Agent를 위한 사전 환경 설정

ServiceWatch Agent와 ServiceWatch 간 통신을 위하여 Security Group과 Firewall 규칙을 추가해야 합니다.

1. Security Group 규칙 추가

   • Virtual Server/GPU Server에 설치된 ServiceWatch Agent에서 ServiceWatch로 수집된 데이터를 전송하기 위해 아래와 같이 Security Group에 규칙을 추가해야합니다.

     방향	유형	포트	대상 주소
     Outbound	사용자 지정 TCP	443	ServiceWatch OpenAPI Endpoint IP 주소

     표. ServiceWatch Agent 통신을 위한 Security Group 규칙

2. Firewall 규칙 추가

   • VPC의 Internet Gateway에 방화벽을 사용으로 설정한 경우 아래와 같이 Firewall 규칙을 추가해야 합니다.

     방향	유형	포트	동작	출발지 주소	목적지 주소
     Outbound	TCP	443	Allow	Virtual Server 생성 시, 할당된 Private IP 주소. Virtual Server Private IP 주소는 Virtual Server 상세 정보 확인하기에서 확인할 수 있습니다.	ServiceWatch OpenAPI Endpoint IP 주소

     표. ServiceWatch Agent 통신을 위한 Internet Gateway Firewall 규칙

ServiceWatch OpenAPI Endpoint IP 주소

ServiceWatch Agent가 ServiceWatch로 수집된 데이터를 전송하기 위해 필요한 Endpoint IP 주소는 다음과 같습니다.

ServiceWatch를 위한 Open Telemetry Collector 설정

서버에서 ServiceWatch 지표와 로그 수집을 위한 Open Telemetry Collector를 사용하기 위해 아래의 순서에 따라 설치합니다.

1. ServiceWatch를 위한 Agent 파일을 다운로드 받을 수 있는 URL로 부터 Agent 파일을 다운로드 받습니다.

wget [ServiceWatch Agent 파일 다운로드 URL]

wget [ServiceWatch Agent 파일 다운로드 URL]

2. ServiceWatch를 위한 Open Telemetry Collector Agent 파일은 아래와 같이 확인할 수 있습니다.
   • ServiceWatch를 위한 Agent 파일을 압축 해제합니다.
     Sample Code Download

     Copy Code

     배경색 변경

     unzip ServiceWatch_Agent.zip

     unzip ServiceWatch_Agent.zip

   • ServiceWatch Agent를 사용하는 환경이 Linux OS인 경우, 아래와 같이 실행 권한을 부여해야합니다.
     Sample Code Download

     Copy Code

     배경색 변경

     chmod +x agent/otelcontribcol_linux_amd64
     chmod +x agent/servicewatch-agent-manager-linux-amd64

     chmod +x agent/otelcontribcol_linux_amd64
     chmod +x agent/servicewatch-agent-manager-linux-amd64

     구분	상세 설명
     examples	예시 설정 파일 폴더. 각 폴더 안에 agent.json, log.json, metric.json 예시 파일이 존재함 os-metrics-min-examples: Node Exporter를 활용한 최소 지표 설정 예시 os-metrics-all-examples: Node Exporter를 활용한 memory/filesystem Collector 지표 설정 예시 gpu-metrics-min-examples: DCGM Exporter를 활용한 최소 지표 설정 예시 gpu-metrics-all-examples: DCGM Exporter를 활용한 주요 지표 설정 예시
     otelcontribcol_linux_amd64	ServiceWatch용 Open Telemetry Collector for Linux
     otelcontribcol_windows_amd64.exe	ServiceWatch용 Open Telemetry Collector for Windows
     servicewatch-agent-manager-linux-amd64	ServiceWatch Agent Manager for Linux
     servicewatch-agent-manager-windows-amd64.exe	ServiceWatch Agent Manager for Windows

     표. ServiceWatch를 위한 Agent 파일 구성

3. ServiceWatch용 Open Telemetry Collector를 위해 ServiceWatch Agent Manager의 Agent 설정 파일을 정의합니다.

   구분	상세 설명
   namespace	사용자 정의 지표를 위한 사용자 정의 네임 스페이스 네임스페이스는 지표를 구분하고 그룹화하기 위한 논리적인 구분으로 사용자 정의 지표를 구분하기 위한 사용자 정의 지표로 지정 네임 스페이스는 영문, 숫자, 공백, 특수문자(_-/)를 포함하여 3~128자로 작성해야하며, 영문으로 시작해야 합니다.
   accessKey	IAM 인증키 Access Key
   accessSecret	IAM 인증키 Secret Key
   resourceId	서버의 Samsung Cloud Platform에서의 자원 ID 예시: Virtual Server의 자원 ID
   openApiEndpoint	리전/오퍼링별 ServiceWatch OpenAPI Endpoint 예시: https://servicewatch.region.offering.samsungsdscloud.com region과 offering 정보는 Samsung Cloud Platform Console 접속 URL에서 확인 가능
   telemetryPort	ServiceWatch Agent의 Telemetry Port 보통 8888 Port로 사용. 8888 Port가 사용 중인 경우 변경 필요

   표. agent.json 설정 파일 항목
   Sample Code Download

   Copy Code

   배경색 변경

   {
      "namespace": "swagent-windows",     # 사용자 정의 지표를 위한 사용자 정의 네임 스페이스
      "accessKey": "testKey",             # IAM 인증키 Access Key
      "accessSecret": "testSecret",       # IAM 인증키 Secret Key
      "resourceId": "resourceID",         # 서버의 Samsung Cloud Platform에서의 자원 ID
      "openApiEndpoint": "https://servicewatch.kr-west1.e.samsungsdscloud.com",    # 리전/환경별 ServiceWatch OpenAPI Endpoint
      "telemetryPort": 8889               # ServiceWatch Agent의 Telemetry Port (보통 8888 Port로 사용. 8888 Port가 사용 중인 경우 변경 필요)
   }

   {
      "namespace": "swagent-windows",     # 사용자 정의 지표를 위한 사용자 정의 네임 스페이스
      "accessKey": "testKey",             # IAM 인증키 Access Key
      "accessSecret": "testSecret",       # IAM 인증키 Secret Key
      "resourceId": "resourceID",         # 서버의 Samsung Cloud Platform에서의 자원 ID
      "openApiEndpoint": "https://servicewatch.kr-west1.e.samsungsdscloud.com",    # 리전/환경별 ServiceWatch OpenAPI Endpoint
      "telemetryPort": 8889               # ServiceWatch Agent의 Telemetry Port (보통 8888 Port로 사용. 8888 Port가 사용 중인 경우 변경 필요)
   }

4. ServiceWatch용 지표 수집을 위한 Metric 설정 파일을 정의합니다.

   • Agent를 통해 지표 수집하고자 하는 경우 metric.json을 설정합니다.

     구분	상세 설명
     prometheus > scrape_configs > targets	지표 수집 대상의 Endpoint 서버의 경우 같은 서버에 Prometheus Exporter 설치하므로 해당 endpoint로 설정 예시: localhost:9100
     prometheus > scrape_configs > jobName	Job Name 설정. 보통 지표 수집 시 사용하는 Prometheus Exporter 종류로 설정 예시: node-exporter
     metricMetas > metricName	수집하고자 하는 지표 이름 설정. 지표명은 영문, 숫자, 특수문자(_)를 포함하여 3~128자로 작성해야하며, 영문으로 시작해야 합니다. 예시: node_cpu_seconds_total
     metricMetas > dimensions	Exporter의 지표 데이터의 출처를 식별하기 위해 제공하는 Collector의 레이블 중 Console에 시각화하여 보여주기 위한 레이블을 설정. 수집한 지표를 Console에 시각화하여 보여줄 때, 차원(dimensions) 설정에 따라 조합하여 표시. 예시: Node Exporter의 Memory Collector의 지표와 같이 특별한 레이블을 제공하지 않는 경우에는 resource_id로 설정 예시: Node Exporter의 Filesystem Collector 지표는 파일시스템이 시스템상에 마운트된 경로를 나타내는 mountpoint로 차원(dimensions) 설정할 수 있음
     metricMetas > unit	지표의 단위 설정 가능 예시: Bytes, Count 등
     metricMetas > aggregationMethod	지정한 차원(dimensions) 기준으로 집계하는 방법 예시: SUM, MAX, MIN, COUNT 중 선택
     metricMetas > descriptionKo	수집하는 지표에 대한 국문 설명
     metricMetas > descriptionEn	수집하는 지표에 대한 영문 설명

     표. metric.json 설정 파일 항목
     Sample Code Download

     Copy Code

     배경색 변경

     {
        "prometheus": {
           "scrape_configs": {
              "targets": [
                 "localhost:9100" # 서버 내 설치한 Prometheus Exporter의 Endpoint
              ],
              "jobName": "node-exporter" # 보통 설치한 Exporter의 이름으로 설정
           }
        },
        "metricMetas": [
           {
              "metricName": "node_memory_MemTotal_bytes",    # Prometheus Exporter로부터 수집되는 지표 중 ServiceWatch로 연계하고자 하는 지표명 설정
              "dimensions": [
                 [
                    "resource_id"        # Node Exporter의 지표 데이터의 출처를 식별하기 위해 제공하는 Collector의 레이블 중 Console에 시각화하여 보여주기 위한 레이블을 설정
                                         # 해당 Memory 관련 지표와 같이 특별한 레이블을 제공하지 않는 경우에는 resource_id로 설정
                 ]
              ],
              "unit": "Bytes",           # 수집 지표 데이터의 단위
              "aggregationMethod": "SUM",    # 집계 방법
              "descriptionKo": "서버의 총 물리적 메모리 크기",    # 지표의 국문 설명
              "descriptionEn": "node memory total bytes"      # 지표의 영문 설명
           },
           {
              "metricName": "node_filesystem_size_bytes",    # Prometheus Exporter로부터 수집되는 지표 중 ServiceWatch로 연계하고자 하는 지표명 설정
              "dimensions": [
                 [
                    "mountpoint"        # Node Exporter의 지표 데이터의 출처를 식별하기 위해 제공하는 Collector의 레이블 중 Console에 시각화하여 보여주기 위한 레이블을 설정
                                        # 해당 Filesystem 관련 지표의 파일시스템이 시스템상에 마운트된 경로를 나타내는 mountpoint로 차원(dimensions) 설정
                 ]
              ],
              "unit": "Bytes",
              "aggregationMethod": "SUM",
              "descriptionKo": "node filesystem size bytes",
              "descriptionEn": "node filesystem size bytes"
           },
           {
              "metricName": "node_memory_MemAvailable_bytes",
              "dimensions": [
                 [
                    "resource_id"
                 ]
              ],
              "unit": "Bytes",
              "aggregationMethod": "SUM",
              "descriptionKo": "node memory available bytes",
              "descriptionEn": "node memory available bytes"
           },
           {
              "metricName": "node_filesystem_avail_bytes",
              "dimensions": [
                 [
                    "mountpoint"
                 ]
              ],
              "unit": "Bytes",
              "aggregationMethod": "SUM",
              "descriptionKo": "node filesystem available bytes",
              "descriptionEn": "node filesystem available bytes"
           }
        ]
     }

     {
        "prometheus": {
           "scrape_configs": {
              "targets": [
                 "localhost:9100" # 서버 내 설치한 Prometheus Exporter의 Endpoint
              ],
              "jobName": "node-exporter" # 보통 설치한 Exporter의 이름으로 설정
           }
        },
        "metricMetas": [
           {
              "metricName": "node_memory_MemTotal_bytes",    # Prometheus Exporter로부터 수집되는 지표 중 ServiceWatch로 연계하고자 하는 지표명 설정
              "dimensions": [
                 [
                    "resource_id"        # Node Exporter의 지표 데이터의 출처를 식별하기 위해 제공하는 Collector의 레이블 중 Console에 시각화하여 보여주기 위한 레이블을 설정
                                         # 해당 Memory 관련 지표와 같이 특별한 레이블을 제공하지 않는 경우에는 resource_id로 설정
                 ]
              ],
              "unit": "Bytes",           # 수집 지표 데이터의 단위
              "aggregationMethod": "SUM",    # 집계 방법
              "descriptionKo": "서버의 총 물리적 메모리 크기",    # 지표의 국문 설명
              "descriptionEn": "node memory total bytes"      # 지표의 영문 설명
           },
           {
              "metricName": "node_filesystem_size_bytes",    # Prometheus Exporter로부터 수집되는 지표 중 ServiceWatch로 연계하고자 하는 지표명 설정
              "dimensions": [
                 [
                    "mountpoint"        # Node Exporter의 지표 데이터의 출처를 식별하기 위해 제공하는 Collector의 레이블 중 Console에 시각화하여 보여주기 위한 레이블을 설정
                                        # 해당 Filesystem 관련 지표의 파일시스템이 시스템상에 마운트된 경로를 나타내는 mountpoint로 차원(dimensions) 설정
                 ]
              ],
              "unit": "Bytes",
              "aggregationMethod": "SUM",
              "descriptionKo": "node filesystem size bytes",
              "descriptionEn": "node filesystem size bytes"
           },
           {
              "metricName": "node_memory_MemAvailable_bytes",
              "dimensions": [
                 [
                    "resource_id"
                 ]
              ],
              "unit": "Bytes",
              "aggregationMethod": "SUM",
              "descriptionKo": "node memory available bytes",
              "descriptionEn": "node memory available bytes"
           },
           {
              "metricName": "node_filesystem_avail_bytes",
              "dimensions": [
                 [
                    "mountpoint"
                 ]
              ],
              "unit": "Bytes",
              "aggregationMethod": "SUM",
              "descriptionKo": "node filesystem available bytes",
              "descriptionEn": "node filesystem available bytes"
           }
        ]
     }

   • 자원명 표기를 위해서는 아래와 같이 commonLabels에 resource_name을 설정하고, metricMetas.dimensions에도 resource_name을 설정하면 ServiceWatch에서 지표 조회할 때 자원명을 함께 확인할 수 있습니다.
     Sample Code Download

     Copy Code

     배경색 변경

     ...
        "commonLabels": {
           "resource_name": "ResourceName" # User Console에서 확인 가능한 자원명
        },
        "metricMetas": [
           {
              "metricName": "metric_name", 
              "dimensions": [
                 [
                    "resource_id",
                    "resource_name"        # commonLabels에서 설정한 resource_name을 각 metric의 dimensions에 추가
     
                 ]
              ],
              "unit": "Bytes",
              "aggregationMethod": "SUM",
              "descriptionKo": "metric_name 설명",
              "descriptionEn": "metric_name description"
           },
        ...
        ]
     ...

     ...
        "commonLabels": {
           "resource_name": "ResourceName" # User Console에서 확인 가능한 자원명
        },
        "metricMetas": [
           {
              "metricName": "metric_name", 
              "dimensions": [
                 [
                    "resource_id",
                    "resource_name"        # commonLabels에서 설정한 resource_name을 각 metric의 dimensions에 추가
     
                 ]
              ],
              "unit": "Bytes",
              "aggregationMethod": "SUM",
              "descriptionKo": "metric_name 설명",
              "descriptionEn": "metric_name description"
           },
        ...
        ]
     ...

5. ServiceWatch용 로그 수집을 위한 Log 설정 파일을 정의합니다.

   • 로그 수집을 하고자 하는 경우 log.json 설정을 해야합니다.

     구분	상세 설명
     fileLog > include	수집할 로그 파일 위치
     fileLog > operators	수집할 로그 메시지를 파싱하기 위해 정의
     fileLog > operators > regex	로그 메시지 형식을 정규식으로 표현
     fileLog > operators > timestamp	ServiceWatch로 전송될 로그 메시지의 Time Stamp의 형식
     logMetas > log_group_value	ServiceWatch로 로그 전송을 위해 생성한 로그 그룹 이름
     logMetas > log_stream_value	ServiceWatch 로그 그룹내 로그 스트림 이름

     표. log.json 설정 파일 항목
     Sample Code Download

     Copy Code

     배경색 변경

     {
        "fileLog": {
           "include": [
              "/var/log/syslog",        # ServiceWatch로 수집할 로그 파일
              "/var/log/auth.log"
           ],
           "operators": {
              "regex": "^(?P<timestamp>\\S+)\\s+(?P<hostname>\\S+)\\s+(?P<process>[^:]+):\\s+(?P<message>.*)$",    # 로그 파일 형식을 정규식으로 표현
              "timestamp": {            # 로그 메시지의 Time Stamp 형식 설정정
                 "layout_type": "gotime",
                 "layout": "2006-01-02T15:04:05.000000Z07:00"
              }
           }
        },
        "logMetas": {
           "log_group_value": "custom-log-group",    # 사전에 생성한 ServiceWatch의 로그 그룹명
           "log_stream_value": "custom-log-stream"   # 사전에 생성한 SerivceWatch 로그 그룹 내의 로그 스트림명
        }
     }

     {
        "fileLog": {
           "include": [
              "/var/log/syslog",        # ServiceWatch로 수집할 로그 파일
              "/var/log/auth.log"
           ],
           "operators": {
              "regex": "^(?P<timestamp>\\S+)\\s+(?P<hostname>\\S+)\\s+(?P<process>[^:]+):\\s+(?P<message>.*)$",    # 로그 파일 형식을 정규식으로 표현
              "timestamp": {            # 로그 메시지의 Time Stamp 형식 설정정
                 "layout_type": "gotime",
                 "layout": "2006-01-02T15:04:05.000000Z07:00"
              }
           }
        },
        "logMetas": {
           "log_group_value": "custom-log-group",    # 사전에 생성한 ServiceWatch의 로그 그룹명
           "log_stream_value": "custom-log-stream"   # 사전에 생성한 SerivceWatch 로그 그룹 내의 로그 스트림명
        }
     }

ServiceWatch를 위한 Open Telemetry Collector 실행

ServiceWatch Agent 실행 (for Linux)

1. ServiceWatch Agent를 실행합니다.

   • agent.json, metric.json, log.json 파일 위치와 servicewatch-agent-manager-linux-amd64,otelcontribcol_linux_amd64 파일의 위치를 확인하여 ServiceWatch Agent를 시작합니다.
     Sample Code Download

     Copy Code

     배경색 변경

     ./agent/servicewatch-agent-manager-linux-amd64 -action run -dir ./agent/examples/os-metrics-min-examples -collector ./agent/otelcontribcol_linux_amd64

     ./agent/servicewatch-agent-manager-linux-amd64 -action run -dir ./agent/examples/os-metrics-min-examples -collector ./agent/otelcontribcol_linux_amd64

   • 지표만 수집하고자 하는 경우, log.json 파일을 다른 파일명으로 변경하거나 agent.json, metric.json과 같은 디렉토리에 있지 않도록 옮기고, 아래와 같이 실행해주세요.
     Sample Code Download

     Copy Code

     배경색 변경

     ./agent/servicewatch-agent-manager-linux-amd64 -action run -dir ./agent/examples/os-metrics-min-examples -collector ./agent/otelcontribcol_linux_amd64

     ./agent/servicewatch-agent-manager-linux-amd64 -action run -dir ./agent/examples/os-metrics-min-examples -collector ./agent/otelcontribcol_linux_amd64

   • 로그만 수집하고자 하는 경우, metric.json 파일을 다른 파일명으로 변경하거나 agent.json, log.json과 같은 디렉토리에 있지 않도록 옮기고, 아래와 같이 실행해주세요.
     Sample Code Download

     Copy Code

     배경색 변경

     ./agent/servicewatch-agent-manager-linux-amd64 -action run -dir ./agent/examples/os-metrics-min-examples -collector ./agent/otelcontribcol_linux_amd64

     ./agent/servicewatch-agent-manager-linux-amd64 -action run -dir ./agent/examples/os-metrics-min-examples -collector ./agent/otelcontribcol_linux_amd64

2. ServiceWatch Agent를 중지합니다.

   Sample Code Download

   Copy Code

   배경색 변경

   ./agent/servicewatch-agent-manager-linux-amd64 -action stop -dir ./agent/examples/os-metrics-min-examples

   ./agent/servicewatch-agent-manager-linux-amd64 -action stop -dir ./agent/examples/os-metrics-min-examples

ServiceWatch Agent 실행 (for Windows)

1. ServiceWatch Agent를 실행합니다.

   Sample Code Download

   Copy Code

   배경색 변경

   servicewatch-agent-manager-windows-amd64.exe -action run -dir ./examples -collector otelcontribcol_windows_amd64.exe

   servicewatch-agent-manager-windows-amd64.exe -action run -dir ./examples -collector otelcontribcol_windows_amd64.exe

2. ServiceWatch Agent를 중지합니다.

   Sample Code Download

   Copy Code

   배경색 변경

   servicewatch-agent-manager-windows-amd64.exe -action stop -dir ./examples

   servicewatch-agent-manager-windows-amd64.exe -action stop -dir ./examples