The page has been translated by Gen AI.

Using ServiceWatch Agent

Users can install the ServiceWatch Agent on Virtual Server/GPU Server/Bare Metal Server, etc., to collect custom metrics and logs.

Reference

Collecting custom metrics/logs via the ServiceWatch Agent is currently available only on Samsung Cloud Platform For Enterprise. It will be offered in other offerings in the future.

Caution

Metric collection through the ServiceWatch Agent is classified as custom metrics and, unlike the default metrics collected from each service, incurs charges, so you must be careful not to configure unnecessary metric collection. Ensure that only the metrics that need to be collected are collected.

ServiceWatch Agent

The agents that need to be installed on the server to collect custom metrics and logs for ServiceWatch can be divided into two main types. It is a Prometheus Exporter and Open Telemetry Collector.

Category	Detailed description
Prometheus Exporter	Provide metrics of a specific application or service in a format that Prometheus can scrape To collect OS metrics from servers, you can use Node Exporter for Linux servers and Windows Exporter for Windows servers, depending on the OS type. Refer to Virtual Server > ServiceWatch Agent for how to use Node Exporter and Windows Exporter. Target Virtual Server GPU Server Bare Metal Server Multi-node GPU Cluster > GPU Node You can use the DCGM (NVIDIA Data Center GPU Manager) Exporter for GPU metrics. Refer to GPU Server > ServiceWatch Agent for how to use the DCGM Exporter. Target GPU Server Multi-node GPU Cluster > GPU Node
Open Telemetry Collector	Acts as a centralized collector that gathers telemetry data such as metrics and logs from distributed systems, processes (filtering, sampling, etc.) it, and exports it to various backends (e.g., Prometheus, Jaeger, Elasticsearch, etc.) Exports data to the ServiceWatch Gateway so that ServiceWatch can collect metric and log data. This guide provides instructions on how to use the OpenTelemetry Collector provided by ServiceWatch.

Pre-configuration for ServiceWatch Agent

You need to add a Security Group and firewall rules to enable communication between the ServiceWatch Agent and ServiceWatch.

Reference

Bare Metal Server does not support Security Groups.

Add Security Group rule
- To transmit the data collected by ServiceWatch from the ServiceWatch Agent installed on Virtual Server/GPU Server to ServiceWatch, you need to add a rule to the Security Group as follows.
  Direction type Port Target address
  Outbound Custom TCP 443 ServiceWatch OpenAPI Endpoint IP Address
  Table. Security Group rules for ServiceWatch Agent communication

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

Add firewall rule

If you configure the VPC’s Internet Gateway to use a firewall, you must add firewall rules as shown below.

Direction	type	Port	Operation	Source address	Destination address
Outbound	TCP	443	Allow	When creating a Virtual Server, the assigned Private IP address. The Virtual Server Private IP address can be found in Check Virtual Server Details.	ServiceWatch OpenAPI Endpoint IP Address

Table. Internet Gateway firewall rules for ServiceWatch Agent communication

ServiceWatch OpenAPI Endpoint IP address

The Endpoint IP address required for the ServiceWatch Agent to send the data collected to ServiceWatch is as follows.

Offering	Region	URL	IP address
For Enterprise	kr-west1	https://servicewatch.kr-west1.e.samsungsdscloud.com	112.107.105.24
For Enterprise	kr-east1	https://servicewatch.kr-east1.e.samsungsdscloud.com	112.107.105.68

Table. ServiceWatch OpenAPI Endpoint Information

Open Telemetry Collector configuration for ServiceWatch

Install the OpenTelemetry Collector on the server following the steps below to collect ServiceWatch metrics and logs.

Download the Agent file from the URL that provides the Agent file for ServiceWatch.

information

The file download link for installing the Agent for ServiceWatch can be found in ServiceWatch’s Service Home > Start Widget.
Also, you can verify it using ServiceWatch’s ShowAgentDownloadLink API. For more information, see the ServiceWatch API Reference.

Color mode

wget [ServiceWatch Agent file download URL]

wget [ServiceWatch Agent file download URL]

Code block. Command to download the Agent installation file for ServiceWatch

The Open Telemetry Collector Agent file for ServiceWatch can be found as follows.

Extract the Agent file for ServiceWatch.
Color mode
unzip ServiceWatch_Agent.zip
unzip ServiceWatch_Agent.zip
Code block. Extract the Agent file for ServiceWatch

When using the ServiceWatch Agent on a Linux OS, you must grant execution permission as shown below.

Color mode

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

Code block. Grant execution permission to the Agent file for ServiceWatch

Category	Detailed description
examples	Example configuration file folder. Each folder contains `agent.json`, `log.json`, `metric.json` example files `os-metrics-min-examples`: Minimal metric configuration example using Node Exporter `os-metrics-all-examples`: Example of memory/filesystem Collector metric configuration using Node Exporter `gpu-metrics-min-examples`: Minimal metric configuration example using DCGM Exporter `gpu-metrics-all-examples`: Example of major metric configuration using DCGM Exporter
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

Table. Agent file configuration for ServiceWatch

Reference

ServiceWatch Agent Manager is a tool that integrates with ServiceWatch to assist in configuring the OpenTelemetry Collector for efficiently transmitting custom metrics and logs. Through this, various custom metrics and log data can be delivered to ServiceWatch.

Define the Agent configuration file in ServiceWatch Agent Manager for the ServiceWatch Open Telemetry Collector.

Category	Detailed description
namespace	Custom namespace for custom metrics A namespace is a logical separation used to distinguish and group metrics, designated as a custom metric for separating custom metrics A namespace must be 3 to 128 characters long, may include letters, numbers, spaces, and special characters (`-`_`/`), and must start with a letter.
accessKey	IAM authentication key Access Key
accessSecret	IAM authentication key Secret Key
resourceId	Resource ID of the server on Samsung Cloud Platform Example: Resource ID of a Virtual Server
openApiEndpoint	ServiceWatch OpenAPI endpoint per region/offering Example: https://servicewatch.`region`.`offering`.samsungsdscloud.com `region` and `offering` information can be found in the Samsung Cloud Platform Console access URL
telemetryPort	ServiceWatch Agent’s Telemetry Port is typically used on port 8888. If port 8888 is in use, it needs to be changed

Table. agent.json configuration file entries

Color mode

{
   "namespace": "swagent-windows",     # Custom namespace for user-defined 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",    # Region/Environment-specific ServiceWatch OpenAPI Endpoint
   "telemetryPort": 8889               # ServiceWatch Agent's Telemetry Port (usually uses port 8888. If port 8888 is in use, change it)
}

{
   "namespace": "swagent-windows",     # Custom namespace for user-defined 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",    # Region/Environment-specific ServiceWatch OpenAPI Endpoint
   "telemetryPort": 8889               # ServiceWatch Agent's Telemetry Port (usually uses port 8888. If port 8888 is in use, change it)
}

Code block. Example of agent.json configuration

Defines the metric configuration file for collecting metrics for ServiceWatch.

If you want to collect metrics through the Agent, set up metric.json.

Category	Detailed description
prometheus > scrape_configs > targets	Endpoint of the metric collection target For servers, because the Prometheus Exporter is installed on the same machine, set it to that endpoint Example: localhost:9100
prometheus > scrape_configs > jobName	Set the Job Name. Usually set it to the type of Prometheus Exporter used for metric collection Example: node-exporter
metricMetas > metricName	Set the name of the metric to be collected. The metric name must be 3 to 128 characters long, include letters, numbers, and special characters (`_`), and start with a letter. Example: node_cpu_seconds_total
metricMetas > dimensions	Set the label of the Collector, among those provided to identify the source of the Exporter’s metric data, for visualization in the Console. When visualizing the collected metrics in the Console, combine them according to the dimensions setting. Example: For metrics like the Memory Collector of Node Exporter that do not provide a special label, set it to resource_id. Example: The Filesystem Collector metrics of Node Exporter can have the mountpoint, which represents the path where the filesystem is mounted on the system, set as a dimension.
metricMetas > unit	Metric unit can be set Example: Bytes, Count, etc.
metricMetas > aggregationMethod	Method to aggregate based on specified dimensions(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 entries

Color mode

{
   "prometheus": {
      "scrape_configs": {
         "targets": [
            "localhost:9100" # Endpoint of the Prometheus Exporter installed on the server
         ],
         "jobName": "node-exporter" # Usually 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"        # Set the label used for visualizing in the Console among the Collector's labels provided to identify the source of Node Exporter's metric data
                                    # If no specific label is provided, such as for the Memory-related metric, set it to **resource_id**.
            ]
         ],
         "unit": "Bytes",           # unit of the collected metric data
         "aggregationMethod": "SUM",    # aggregation method
         "descriptionKo": "Total physical memory size of the server",    # Korean description of the metric
         "descriptionEn": "node memory total bytes"      # English description of the metric
      },
      {
         "metricName": "node_filesystem_size_bytes",    # Set the metric name to be linked with ServiceWatch among the metrics collected from the Prometheus Exporter
         "dimensions": [
            [
               "mountpoint"        # Set the label for visualizing in the Console among the Collector labels provided to identify the source of Node Exporter's metric data.
                                   # Set the dimension (dimensions) of the Filesystem-related metric to the mountpoint, which indicates the path where the filesystem is mounted on the system.
            ]
         ],
         "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" # Endpoint of the Prometheus Exporter installed on the server
         ],
         "jobName": "node-exporter" # Usually 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"        # Set the label used for visualizing in the Console among the Collector's labels provided to identify the source of Node Exporter's metric data
                                    # If no specific label is provided, such as for the Memory-related metric, set it to **resource_id**.
            ]
         ],
         "unit": "Bytes",           # unit of the collected metric data
         "aggregationMethod": "SUM",    # aggregation method
         "descriptionKo": "Total physical memory size of the server",    # Korean description of the metric
         "descriptionEn": "node memory total bytes"      # English description of the metric
      },
      {
         "metricName": "node_filesystem_size_bytes",    # Set the metric name to be linked with ServiceWatch among the metrics collected from the Prometheus Exporter
         "dimensions": [
            [
               "mountpoint"        # Set the label for visualizing in the Console among the Collector labels provided to identify the source of Node Exporter's metric data.
                                   # Set the dimension (dimensions) of the Filesystem-related metric to the mountpoint, which indicates the path where the filesystem is mounted on the system.
            ]
         ],
         "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"
      }
   ]
}

Code block. metric.json configuration example

To display the resource name, set resource_name in commonLabels as shown below, and also set resource_name in metricMetas.dimensions; then ServiceWatch can retrieve the metric along with the resource name.

Color mode

   "commonLabels": {
      "resource_name": "ResourceName" # Resource name visible in the User Console
   },
   "metricMetas": [
      {
         "metricName": "metric_name"
         "dimensions": [
            [
               "resource_id"
               "resource_name"        # Add the resource_name set in commonLabels to the dimensions of each metric

            ]
         ],
         "unit": "Bytes"
         "aggregationMethod": "SUM"
         "descriptionKo": "metric_name description"
         "descriptionEn": "metric_name description"
      },
   ...
   ]

   "commonLabels": {
      "resource_name": "ResourceName" # Resource name visible in the User Console
   },
   "metricMetas": [
      {
         "metricName": "metric_name"
         "dimensions": [
            [
               "resource_id"
               "resource_name"        # Add the resource_name set in commonLabels to the dimensions of each metric

            ]
         ],
         "unit": "Bytes"
         "aggregationMethod": "SUM"
         "descriptionKo": "metric_name description"
         "descriptionEn": "metric_name description"
      },
   ...
   ]

Code block. metric.json - Resource name setting

Defines the log configuration file for collecting logs for ServiceWatch.

If you want to collect logs, you must configure log.json.

Category	Detailed description
fileLog > include	Location of log files to collect
fileLog > operators	Definition for parsing 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 of log messages to be sent to ServiceWatch
logMetas > log_group_value	Log group name created for sending logs to ServiceWatch
logMetas > log_stream_value	Log stream name in ServiceWatch log group

Table. log.json configuration file entries

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>.*)$",    # Represent log file format with a regular expression
         "timestamp": {            # Set the format of the log message's Time Stamp
            "layout_type": "gotime"
            "layout": "2006-01-02T15:04:05.000000Z07:00"
         }
      }
   },
   "logMetas": {
      "log_group_value": "custom-log-group",    # Log group name of ServiceWatch created in advance
      "log_stream_value": "custom-log-stream"   # Log stream name 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>.*)$",    # Represent log file format with a regular expression
         "timestamp": {            # Set the format of the log message's Time Stamp
            "layout_type": "gotime"
            "layout": "2006-01-02T15:04:05.000000Z07:00"
         }
      }
   },
   "logMetas": {
      "log_group_value": "custom-log-group",    # Log group name of ServiceWatch created in advance
      "log_stream_value": "custom-log-stream"   # Log stream name within the pre‑created ServiceWatch log group
   }
}

Code block. log.json configuration example

Reference

To link a server’s log files to ServiceWatch via the ServiceWatch Agent, you must first create a log group and a log stream within that log group.

For detailed information on creating log groups and log streams, refer to Log.

Running Open Telemetry Collector for ServiceWatch

How to Run ServiceWatch Agent

[ServiceWatch Agent executable] -action [run|stop] - dir [configuration file location] -collector [Open Telemetry Collector executable location]

Execution options	Detailed description
`-action`	Action setting (run or stop)
`-dir`	the location of ServiceWatch Agent configuration files such as `agent.json`, `metric.json`, `log.json`
`-collector`	Open Telemetry Collector executable file location

Table. log.json configuration file entries

ServiceWatch Agent execution (for Linux)

Reference

agent.json, metric.json, log.json files are in current location/agent/examples/os-metrics-min-examples, and the otelcontribcol_linux_amd64 file is in current location/agent. Execute as shown below.

Run the ServiceWatch Agent.

Check the locations of agent.json, metric.json, log.json files and the locations of servicewatch-agent-manager-linux-amd64, otelcontribcol_linux_amd64 files, and start the ServiceWatch Agent.

Color mode

./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

Code block. ServiceWatch Agent start - collect all metrics/logs

If you only want to collect metrics, rename the log.json file to a different name or move it so that it is not in the same directory as agent.json, metric.json, and then run as shown below.

Color mode

./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

Code block. ServiceWatch Agent start - collect metrics only

If you only want to collect logs, rename the metric.json file to a different name or move it so that it is not in the same directory as agent.json, log.json, and run as shown below.

Color mode

./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

Code block. ServiceWatch Agent start - collect logs only

Stop the ServiceWatch Agent.

Color mode

./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

code block. Stop ServiceWatch Agent

Running ServiceWatch Agent (for Windows)

Run the ServiceWatch Agent.

Color mode

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

code block. Start ServiceWatch Agent

Stop the ServiceWatch Agent.

Color mode

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

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

code block. Stop ServiceWatch Agent

Event

ServiceWatch Event Reference