Using the ServiceWatch Agent

Users can install the ServiceWatch Agent on Virtual Servers, GPU Servers, Bare Metal Servers, and other environments to collect custom metrics and logs.

ServiceWatch Agent

The agents that must be installed on the server to collect custom metrics and logs for ServiceWatch can be broadly divided into two types. Prometheus Exporter and Open Telemetry Collector.

Types of Prometheus Exporters

Use the following Exporters depending on the metrics you want to collect and the server’s OS.

Installation and Configuration Order

Install and configure the ServiceWatch Agent in the following order.

Pre-configuration for the ServiceWatch Agent

Network configuration is required for communication between the ServiceWatch Agent and ServiceWatch. ServiceWatch Agent supports two methods for sending collected data to ServiceWatch: using an Internet Gateway and using PrivateLink. Select and configure the method that best fits your environment.

How to Use an Internet Gateway

When sending data to ServiceWatch through an Internet Gateway, you must add Security Group and Firewall rules.

1. Add Security Group Rule

   • To send data collected by ServiceWatch from the ServiceWatch Agent installed on a Virtual Server or GPU Server, you must add the following rules to the Security Group.

     Direction	Type	Port	Target Address
     Outbound	Custom TCP	443	ServiceWatch OpenAPI Endpoint IP Address

     Table. Security Group rules for ServiceWatch Agent communication

2. Add a firewall rule

   • If you enable the firewall for the Internet Gateway of a VPC, you must add a firewall rule as shown below.

     Direction	Type	Port	Operation	Origin address	Destination address
     Outbound	TCP	443	Allow	The Private IP address assigned when creating a Virtual Server. You can view the Virtual Server Private IP address in View Virtual Server Details.	ServiceWatch OpenAPI Endpoint IP Address

     Table. Internet Gateway Firewall rules for ServiceWatch Agent communication

How to Use PrivateLink

With PrivateLink, you can send the data collected by the ServiceWatch Agent to the internal network of the Samsung Cloud Platform without going through the internet. Because the data uses only the internal network, it offers high security and does not require a public IP, NAT, or an Internet Gateway. Therefore, no Internet Gateway Firewall rules are added.

1. Create a PrivateLink Endpoint
   • Create a PrivateLink endpoint to connect to ServiceWatch in the VPC. * In Service Type, select Samsung Cloud Platform Provided Services, and then select ServiceWatch_GLOBAL1 from the PrivateLink Service list.
   • For details on the creation procedure, see VPC > Create a PrivateLink Endpoint.

2. Add Security Group Rule

   • To transmit data through a PrivateLink Endpoint from the ServiceWatch Agent, you must add the following rules to the Security Group.

     Target	Direction	Type	Port	Target Address
     Security Group for Virtual Server/GPU Server	Outbound	Custom TCP	443	IP address assigned to the PrivateLink Endpoint
     Security Group for PrivateLink Endpoint	Inbound	Custom TCP	443	IP address of the Virtual Server/GPU Server

     Table. Security Group rules for PrivateLink usage

3. hosts file configuration

   • Because the ServiceWatch Agent sends data to the ServiceWatch OpenAPI Endpoint domain, you must configure the hosts file on the server to resolve that domain to the PrivateLink Endpoint IP address.
   • The location of the hosts file varies by operating system.
     • Linux: /etc/hosts
     • Windows: C:\Windows\System32\drivers\etc\hosts
       • Tab 0

       Sample Code Download

       Copy Code

       Color mode

       # When the PrivateLink Endpoint IP is 192.168.0.3,
       192.168.0.3 servicewatch.kr-west1.e.samsungsdscloud.com

       # When the PrivateLink Endpoint IP is 192.168.0.3,
       192.168.0.3 servicewatch.kr-west1.e.samsungsdscloud.com

ServiceWatch OpenAPI Endpoint IP Address

The following are the endpoint IP addresses required for the ServiceWatch Agent to send data collected by ServiceWatch.

Open Telemetry Collector Configuration for ServiceWatch

To use the Open Telemetry Collector on the server for collecting ServiceWatch metrics and logs, install it by following the steps below.

1. ### Download the Agent file

Download the Agent file from the ServiceWatch Agent file download URL.

wget [ServiceWatch Agent file download URL]

wget [ServiceWatch Agent file download URL]

2. ### Check the Agent file structure

You can verify the structure of the downloaded Agent file as follows.

• Extract the Agent file for ServiceWatch.
  • Tab 0

  Sample Code Download

  Copy Code

  Color mode

  unzip ServiceWatch_Agent.zip

  unzip ServiceWatch_Agent.zip

  • Tab 0

  Sample Code Download

  Copy Code

  Color mode

  README.md
  otelcontribcol_linux_amd64
  otelcontribcol_windows_amd64.exe
  servicewatch-agent-manager-linux-amd64
  servicewatch-agent-manager-windows-amd64.exe
  os-metrics-min-examples/
   ├─ agent.json
   ├─ metric.json
   └─ log.json
  os-metrics-all-examples/
  gpu-metrics-min-examples/
  gpu-metrics-all-examples/
  only-log-without-timestamp-examples/

  README.md
  otelcontribcol_linux_amd64
  otelcontribcol_windows_amd64.exe
  servicewatch-agent-manager-linux-amd64
  servicewatch-agent-manager-windows-amd64.exe
  os-metrics-min-examples/
   ├─ agent.json
   ├─ metric.json
   └─ log.json
  os-metrics-all-examples/
  gpu-metrics-min-examples/
  gpu-metrics-all-examples/
  only-log-without-timestamp-examples/

  Category	Detailed Description
  README.md	Guide to Using the Agent
  otelcontribcol_linux_amd64	Open Telemetry Collector for Linux for ServiceWatch
  otelcontribcol_windows_amd64.exe	Open Telemetry Collector for Windows for ServiceWatch
  servicewatch-agent-manager-linux-amd64	ServiceWatch Agent Manager for Linux
  servicewatch-agent-manager-windows-amd64.exe	ServiceWatch Agent Manager for Windows
  Example configuration file folder	Each folder contains an agent.json file and example metric.json, log.json files tailored to their respective purposes. os-metrics-min-examples: Example of minimal metric configuration using Node Exporter os-metrics-all-examples: Example of memory/filesystem Collector metric configuration using Node Exporter gpu-metrics-min-examples: Example of minimal metric configuration using DCGM Exporter gpu-metrics-all-examples: Example of key metric configuration using DCGM Exporter only-log-without-timestamp-examples: Example of configuration that collects logs only, without timestamp parsing

  Table. Agent file structure for ServiceWatch
• If the environment where the ServiceWatch Agent is used is a Linux OS, you must grant execution permissions as follows.
  • Tab 0

  Sample Code Download

  Copy Code

  Color mode

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

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

3. ### agent.json Configuration

Defines the agent configuration file (agent.json) for the ServiceWatch Agent Manager.

{
   "namespace": "swagent-windows",     # Custom namespace for custom metrics
   "accessKey": "testKey",             # IAM authentication key Access Key
   "accessSecret": "testSecret",       # IAM authentication key Secret Key
   "resourceId": "resourceID",         # Resource ID on the server's Samsung Cloud Platform
   "openApiEndpoint": "https://servicewatch.kr-west1.e.samsungsdscloud.com",    # ServiceWatch OpenAPI Endpoint by region/environment
   "telemetryPort": 8889               # Telemetry port for the ServiceWatch Agent (the default is port 8888; the example above specifies port 8889 because port 8888 is already in use)
}

{
   "namespace": "swagent-windows",     # Custom namespace for custom metrics
   "accessKey": "testKey",             # IAM authentication key Access Key
   "accessSecret": "testSecret",       # IAM authentication key Secret Key
   "resourceId": "resourceID",         # Resource ID on the server's Samsung Cloud Platform
   "openApiEndpoint": "https://servicewatch.kr-west1.e.samsungsdscloud.com",    # ServiceWatch OpenAPI Endpoint by region/environment
   "telemetryPort": 8889               # Telemetry port for the ServiceWatch Agent (the default is port 8888; the example above specifies port 8889 because port 8888 is already in use)
}

4. ### metric.json Configuration

Defines the metric configuration file (metric.json) for collecting metrics with ServiceWatch.

• To collect metrics through an agent, configure metric.json.

  Category	Detailed Description
  prometheus > scrape_configs > targets	For server endpoints that are targets for metric collection, install the Prometheus Exporter on the same server and configure the endpoint accordingly. Example: localhost:9100
  prometheus > scrape_configs > jobName	Set the Job Name. Typically, set this to the type of Prometheus Exporter used for metric collection. Example: node-exporter
  metricMetas > metricName	Set the name of the metric to collect. The metric name must be 3 to 128 characters long, start with an English letter, and can include letters, numbers, and special characters (_). Example: node_cpu_seconds_total
  metricMetas > dimensions	Set the labels to visualize in the Console from among the labels provided by the Collector to identify the source of the Exporter’s metric data. When visualizing collected metrics in the Console, they are displayed in combinations based on the dimension settings. Configure the setting to match the actual label names collected by the Exporter, including case sensitivity. Example: For metrics from the Memory Collector of the Node Exporter, which do not provide special labels, set the dimension to resource_id. Example: For metrics from the Filesystem Collector of the Node Exporter, you can set the dimension to mountpoint, which indicates the path where the filesystem is mounted on the system.
  metricMetas > unit	You can set the unit for a metric. Example: Bytes, Count, etc.
  metricMetas > aggregationMethod	How to aggregate by the specified dimensions Example: Select from SUM, MAX, MIN, COUNT
  metricMetas > descriptionKo	Korean description of the metrics being collected
  metricMetas > descriptionEn	English description of the metrics being collected

  Table. metric.json configuration file items

You can check the label names collected by the Exporter by querying the Exporter’s metrics endpoint.

curl http://localhost:9100/metrics | grep node_filesystem_size_bytes

curl http://localhost:9100/metrics | grep node_filesystem_size_bytes

{
   "prometheus": {
      "scrape_configs": {
         "targets": [
            "localhost:9100" # Endpoint of the Prometheus Exporter installed on the server
         ],
         "jobName": "node-exporter" # Typically set to the name of the installed Exporter
      }
   },
   "metricMetas": [
      {
         "metricName": "node_memory_MemTotal_bytes",    # Set the metric name to be linked with ServiceWatch among the metrics collected from the Prometheus Exporter
         "dimensions": [
            [
               "resource_id"        # Sets the label to be visualized in the Console among the Collector labels provided to identify the source of the metric data from Node Exporter
                                    # If no specific label is provided for the relevant Memory-related metrics, set it to resource_id.
            ]
         ],
         "unit": "Bytes",           # Unit of the collected metric data
         "aggregationMethod": "SUM",    # Aggregation method
         "Total physical memory size of the server",    # Korean description of the metric
         "node memory total bytes"
      },
      {
         "metricName": "node_filesystem_size_bytes",    # Set the metric name to be linked with ServiceWatch among the metrics collected from the Prometheus Exporter
         "dimensions": [
            [
               "mountpoint"        # Sets the label to visualize in the Console among the Collector labels provided to identify the source of the Node Exporter metric data
                                   # Set the dimension to the mount point, which indicates the path where the filesystem for the relevant Filesystem metrics is mounted on the system.
            ]
         ],
         "unit": "Bytes",
         "aggregationMethod": "SUM",
         "node filesystem size bytes"
         "node filesystem size bytes"
      },
      {
         "metricName": "node_memory_MemAvailable_bytes",
         "dimensions": [
            [
               "resource_id"
            ]
         ],
         "unit": "Bytes",
         "aggregationMethod": "SUM",
         "node memory available bytes"
         "node memory available bytes"
      },
      {
         "metricName": "node_filesystem_avail_bytes",
         "dimensions": [
            [
               "mountpoint"
            ]
         ],
         "unit": "Bytes",
         "aggregationMethod": "SUM",
         "node filesystem available bytes",
         "node filesystem available bytes"
      }
   ]
}

{
   "prometheus": {
      "scrape_configs": {
         "targets": [
            "localhost:9100" # Endpoint of the Prometheus Exporter installed on the server
         ],
         "jobName": "node-exporter" # Typically set to the name of the installed Exporter
      }
   },
   "metricMetas": [
      {
         "metricName": "node_memory_MemTotal_bytes",    # Set the metric name to be linked with ServiceWatch among the metrics collected from the Prometheus Exporter
         "dimensions": [
            [
               "resource_id"        # Sets the label to be visualized in the Console among the Collector labels provided to identify the source of the metric data from Node Exporter
                                    # If no specific label is provided for the relevant Memory-related metrics, set it to resource_id.
            ]
         ],
         "unit": "Bytes",           # Unit of the collected metric data
         "aggregationMethod": "SUM",    # Aggregation method
         "Total physical memory size of the server",    # Korean description of the metric
         "node memory total bytes"
      },
      {
         "metricName": "node_filesystem_size_bytes",    # Set the metric name to be linked with ServiceWatch among the metrics collected from the Prometheus Exporter
         "dimensions": [
            [
               "mountpoint"        # Sets the label to visualize in the Console among the Collector labels provided to identify the source of the Node Exporter metric data
                                   # Set the dimension to the mount point, which indicates the path where the filesystem for the relevant Filesystem metrics is mounted on the system.
            ]
         ],
         "unit": "Bytes",
         "aggregationMethod": "SUM",
         "node filesystem size bytes"
         "node filesystem size bytes"
      },
      {
         "metricName": "node_memory_MemAvailable_bytes",
         "dimensions": [
            [
               "resource_id"
            ]
         ],
         "unit": "Bytes",
         "aggregationMethod": "SUM",
         "node memory available bytes"
         "node memory available bytes"
      },
      {
         "metricName": "node_filesystem_avail_bytes",
         "dimensions": [
            [
               "mountpoint"
            ]
         ],
         "unit": "Bytes",
         "aggregationMethod": "SUM",
         "node filesystem available bytes",
         "node filesystem available bytes"
      }
   ]
}

• To display resource names, set resource_name in commonLabels and metricMetas.dimensions as shown below. This allows you to view resource names alongside metrics when querying metrics in ServiceWatch.
  • Tab 0

  Sample Code Download

  Copy Code

  Color mode

  ...
     "commonLabels": {
        "resource_name": "ResourceName" # Resource name that can be verified in the User Console
     },
     "metricMetas": [
        {
           "metricName": "metric_name",
           "dimensions": [
              [
                 "resource_id",
                 "resource_name"        # Adds the resource_name configured in commonLabels to the dimensions of each metric
  
              ]
           ],
           "unit": "Bytes",
           "aggregationMethod": "SUM",
           "descriptionKo": "metric_name description",
           "metric_name description"
        },
     ...
     ]
  ...

  ...
     "commonLabels": {
        "resource_name": "ResourceName" # Resource name that can be verified in the User Console
     },
     "metricMetas": [
        {
           "metricName": "metric_name",
           "dimensions": [
              [
                 "resource_id",
                 "resource_name"        # Adds the resource_name configured in commonLabels to the dimensions of each metric
  
              ]
           ],
           "unit": "Bytes",
           "aggregationMethod": "SUM",
           "descriptionKo": "metric_name description",
           "metric_name description"
        },
     ...
     ]
  ...

5. ### log.json Configuration

Defines the log configuration file (log.json) for collecting logs with ServiceWatch.

• To collect logs, you must configure log.json.

  Category	Detailed Description
  fileLog > include	Location of the log files to collect
  fileLog > operators	Defined to parse the log messages to be collected
  fileLog > operators > regex	Express the log message format as a regular expression
  fileLog > operators > timestamp	The format of the Time Stamp for log messages sent to ServiceWatch
  logMetas > log_group_value	The log group name created for log transmission using ServiceWatch
  logMetas > log_stream_value	Log stream name within the ServiceWatch log group

  Table. log.json configuration file entries
  • Tab 0

  Sample Code Download

  Copy Code

  Color mode

  {
     "fileLog": {
        "include": [
           "/var/log/syslog",        # Log file to be collected by ServiceWatch
           "/var/log/auth.log"
        ],
        "operators": {
           "regex": "^(?P<timestamp>\\S+)\\s+(?P<hostname>\\S+)\\s+(?P<process>[^:]+):\\s+(?P<message>.*)$",    # Expresses the log file format using a regular expression
           "timestamp": {            # Set the Time Stamp format for log messages
              "layout_type": "gotime",
              "layout": "2006-01-02T15:04:05.000000Z07:00"
           }
        }
     },
     "logMetas": {
        "log_group_value": "custom-log-group",    # The log group name of the ServiceWatch created in advance
        "log_stream_value": "custom-log-stream"   # The name of the log stream within the pre-created ServiceWatch log group
     }
  }

  {
     "fileLog": {
        "include": [
           "/var/log/syslog",        # Log file to be collected by ServiceWatch
           "/var/log/auth.log"
        ],
        "operators": {
           "regex": "^(?P<timestamp>\\S+)\\s+(?P<hostname>\\S+)\\s+(?P<process>[^:]+):\\s+(?P<message>.*)$",    # Expresses the log file format using a regular expression
           "timestamp": {            # Set the Time Stamp format for log messages
              "layout_type": "gotime",
              "layout": "2006-01-02T15:04:05.000000Z07:00"
           }
        }
     },
     "logMetas": {
        "log_group_value": "custom-log-group",    # The log group name of the ServiceWatch created in advance
        "log_stream_value": "custom-log-stream"   # The name of the log stream within the pre-created ServiceWatch log group
     }
  }

Running the Open Telemetry Collector for ServiceWatch

Run the ServiceWatch Agent (for Linux)

1. Run the ServiceWatch Agent.

   • Check the file locations of agent.json, metric.json, and log.json, as well as the locations of the servicewatch-agent-manager-linux-amd64 and otelcontribcol_linux_amd64 files, to start the ServiceWatch Agent.
   • The execution command is the same regardless of the collection target. The collection target is determined by the configuration file structure in the directory specified by -dir.

     Collection Targets	Configuring the settings file directory
     Collect both metrics and logs	agent.json, metric.json, log.json
     Collect metrics only	agent.json, metric.json log.json to a different filename or move them to a different directory
     Collect logs only	agent.json, log.json metric.json to a different filename or move them to a different directory

     Table. Collection targets based on configuration file structure
     • Tab 0

     Sample Code Download

     Copy Code

     Color mode

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

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

2. Stops the ServiceWatch Agent.

   • Tab 0

   Sample Code Download

   Copy Code

   Color mode

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

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

Run the ServiceWatch Agent (for Windows)

1. Run the ServiceWatch Agent.

   • The collection target is determined by the configuration file structure of the directory specified in -dir. * For details, see Collection Targets Based on Configuration File Structure.
     • Tab 0

     Sample Code Download

     Copy Code

     Color mode

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

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

2. Stop the ServiceWatch Agent.

   • Tab 0

   Sample Code Download

   Copy Code

   Color mode

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

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