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, and other platforms to collect custom metrics and logs.

Reference

Custom metric/log collection via the ServiceWatch Agent is currently available only on Samsung Cloud Platform For Enterprise. It will also be available in other offerings in the future.

Caution

Collecting metrics through the ServiceWatch Agent is classified as custom metrics, and unlike the default metrics collected from each service, it incurs charges, so you must be careful not to configure unnecessary metric collection. Make sure to configure it so 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 ServiceWatch’s custom metrics and logs can be divided into two main types. 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 it (filtering, sampling, etc.), 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 Open Telemetry Collector provided by ServiceWatch.

Pre-configuration for ServiceWatch Agent

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

Reference

Bare Metal Server does not support Security Group.

Add Security Group rule
- To transmit the data collected by ServiceWatch from the ServiceWatch Agent installed on a Virtual Server/GPU Server to ServiceWatch, you need to add a rule to the Security Group as shown below.
  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 need to add a firewall rule as shown below.

Direction	type	Port	Operation	Origin 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 checked in Virtual Server 상세 정보 확인하기.	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 according to the steps below to use the Open Telemetry Collector on the server for collecting ServiceWatch metrics and logs.

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

Notice

The file download link for installing the Agent for ServiceWatch can be found in ServiceWatch’s Service Home > Start Widget.
It can also be verified via ServiceWatch’s ShowAgentDownloadLink API. For more details, 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

If the environment using the ServiceWatch Agent is Linux OS, you must grant execution permissions as follows.

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 example files `agent.json`, `log.json`, `metric.json` `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 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 works with ServiceWatch as a tool that assists in configuring the Open Telemetry Collector to efficiently transmit custom metrics and logs. Through this, you can deliver various custom metrics and log data to ServiceWatch.

Define the Agent configuration file of 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 to differentiate custom metrics The namespace must be 3 to 128 characters long, consisting of 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 on the server’s Samsung Cloud Platform Example: Resource ID of a Virtual Server
openApiEndpoint	ServiceWatch OpenAPI Endpoint by 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	Telemetry Port of ServiceWatch Agent usually uses port 8888. If port 8888 is in use, it needs to be changed

Table. agent.json configuration file entries

Color mode

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

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

Code block. agent.json configuration example

Define a Metric configuration file for collecting metrics for ServiceWatch.

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

Category	Detailed description
prometheus > scrape_configs > targets	Endpoint of the metric collection target In the case of a server, since the Prometheus Exporter is installed on the same server, set it to that endpoint Example: localhost:9100
prometheus > scrape_configs > jobName	Set the Job Name. Usually set 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, consisting of letters, numbers, and special characters (`_`), and must start with a letter. Example: node_cpu_seconds_total
metricMetas > dimensions	Set the label among the Collector’s labels provided to identify the source of the Exporter’s metric data for visualization in the Console. When visualizing the collected metrics in the Console, they are displayed in combinations according to the dimensions setting. Example: When there is no special label provided, as with the metrics of Node Exporter’s Memory Collector, set it to resource_id. Example: The metrics of Node Exporter’s Filesystem Collector can have the dimension set to mountpoint, which represents the path where the filesystem is mounted on the system.
metricMetas > unit	Ability to set the unit of the metric Example: Bytes, Count, etc
metricMetas > aggregationMethod	Method to aggregate based on the specified dimensions Example: select among SUM, MAX, MIN, COUNT
metricMetas > descriptionKo	Korean description of the collected metrics
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 on the Console among the Collector's labels that identify the source of Node Exporter's metric data
                                    # Set to resource_id when no special label is provided, such as for Memory-related metrics
            ]
         ],
         "unit": "Bytes",           # unit of 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 used for visualizing in the Console among the Collector's labels provided to identify the source of Node Exporter's metric data
                                   # Set the dimension (dimensions) to the mountpoint, which represents 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 on the Console among the Collector's labels that identify the source of Node Exporter's metric data
                                    # Set to resource_id when no special label is provided, such as for Memory-related metrics
            ]
         ],
         "unit": "Bytes",           # unit of 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 used for visualizing in the Console among the Collector's labels provided to identify the source of Node Exporter's metric data
                                   # Set the dimension (dimensions) to the mountpoint, which represents 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 view the resource name together when querying metrics.

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

Define a Log configuration file for collecting logs for ServiceWatch.

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

Category	Detailed description
fileLog > include	Log file location to collect
fileLog > operators	Define parsing of 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	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 the log file format as 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 the log file format as 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 the 로그.

Running Open Telemetry Collector for ServiceWatch

How to Run ServiceWatch Agent

[SerivceWatch 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`	`agent.json`, `metric.json`, `log.json` such as ServiceWatch Agent configuration file locations
`-collector`	Open Telemetry Collector executable location

Table. log.json configuration file entries

ServiceWatch Agent execution (for Linux)

Reference

Assuming the agent.json, metric.json, and log.json files are in 현재위치/agent/examples/os-metrics-min-examples, and the otelcontribcol_linux_amd64 file is in 현재위치/agent, run as follows.

Run the ServiceWatch Agent.

Check the locations of the agent.json, metric.json, and log.json files, as well as the 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 only metrics

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

ServiceWatch Agent execution (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