The page has been translated by Gen AI.

Using ServiceWatch Agent

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

Note
Custom metric/log collection through ServiceWatch Agent is currently only available in Samsung Cloud Platform For Enterprise. It is planned to be provided in other offerings in the future.
Warning
Metric collection through ServiceWatch Agent is classified as custom metrics and incurs charges unlike metrics that are basically collected from each service, so be careful not to set up unnecessary metric collection. Make sure to set it up so that only metrics that need to be collected are collected.

ServiceWatch Agent

The agents that need to be installed on a server for custom metric and log collection of ServiceWatch can be largely divided into two types. Prometheus Exporter and Open Telemetry Collector.

CategoryDescription
Prometheus ExporterProvides metrics of a specific application or service in a format that Prometheus can scrape
  • For OS metric collection of the server, you can use Node Exporter for Linux servers and Windows Exporter for Windows servers depending on the OS type.
    • Target
      • Virtual Server
      • GPU Server
      • Bare Metal Server
      • Multi-node GPU Cluster > GPU Node
  • You can use DCGM (NVIDIA Data Center GPU Manager) Exporter for GPU metrics.
    • Target
      • GPU Server
      • Multi-node GPU Cluster > GPU Node
Open Telemetry CollectorActs as a centralized collector that collects telemetry data such as metrics and logs of distributed systems, processes them (filtering, sampling, etc.), and sends them to multiple backends (e.g., Prometheus, Jaeger, Elasticsearch, etc.)
  • Enables ServiceWatch to collect metric and log data by sending data to ServiceWatch Gateway.
  • This guide explains how to use the Open Telemetry Collector provided by ServiceWatch.
Table. Description of Prometheus Exporter and Open Telemetry Collector
Note

To link server log files to ServiceWatch through ServiceWatch Agent, you must first create a log group and log streams within the log group.

  • For more information about creating log groups and log streams, see Logs.

Pre-environment Configuration for ServiceWatch Agent

You must add Security Group and Firewall rules for communication between ServiceWatch Agent and ServiceWatch.

Note
Bare Metal Server does not support Security Group.

  1. Adding Security Group Rules

    • To send data collected from ServiceWatch Agent installed on Virtual Server/GPU Server to ServiceWatch, you must add rules to the Security Group as follows.
      DirectionTypePortDestination Address
      OutboundCustom TCP443ServiceWatch OpenAPI Endpoint IP Address
      Table. Security Group Rules for ServiceWatch Agent Communication

  2. Adding Firewall Rules

    • If firewall is enabled on the Internet Gateway of the VPC, you must add Firewall rules as follows.
      DirectionTypePortActionSource AddressDestination Address
      OutboundTCP443AllowPrivate IP address assigned when creating Virtual Server. Virtual Server Private IP address can be checked in Checking 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 ServiceWatch Agent to send collected data to ServiceWatch is as follows.

OfferingRegionURLIP Address
For Enterprisekr-west1https://servicewatch.kr-west1.e.samsungsdscloud.com112.107.105.24
For Enterprisekr-east1https://servicewatch.kr-east1.e.samsungsdscloud.com112.107.105.68
Table. ServiceWatch OpenAPI Endpoint Information

Configuring Open Telemetry Collector for ServiceWatch

To use Open Telemetry Collector for ServiceWatch metric and log collection on a server, install it in the following order.

  1. Download the Agent file from the URL where you can download the Agent file for ServiceWatch.

    Guide
    The file download link for ServiceWatch Agent installation will be provided through Samsung Cloud Platform Console announcements and Support Center > Contact Us.
    Color mode
    wget [ServiceWatch Agent File Download URL]
    wget [ServiceWatch Agent File Download URL]
    Code Block. ServiceWatch Agent Installation File Download Command

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

    • Extract the Agent file for ServiceWatch.
      Color mode
      unzip ServiceWatch_Agent.zip
      unzip ServiceWatch_Agent.zip
      Code Block. Extracting ServiceWatch Agent File
    • If the environment using 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. Granting Execution Permissions to ServiceWatch Agent File
      CategoryDescription
      examplesExample configuration file folder. Inside each folder, there are agent.json, log.json, metric.json example files
      • os-metrics-min-examples: Minimum metric setting example using Node Exporter
      • os-metrics-all-examples: Metric setting example using Node Exporter memory/filesystem Collector
      • gpu-metrics-min-examples: Minimum metric setting example using DCGM Exporter
      • gpu-metrics-all-examples: Key metric setting example using DCGM Exporter
      otelcontribcol_linux_amd64Open Telemetry Collector for Linux for ServiceWatch
      otelcontribcol_windows_amd64.exeOpen Telemetry Collector for Windows for ServiceWatch
      servicewatch-agent-manager-linux-amd64ServiceWatch Agent Manager for Linux
      servicewatch-agent-manager-windows-amd64.exeServiceWatch Agent Manager for Windows
      Table. ServiceWatch Agent File Configuration
Note
ServiceWatch Agent Manager is a tool that helps configure Open Telemetry Collector to efficiently send custom metrics and logs by integrating with ServiceWatch. Through this, you can send various custom metrics and log data to ServiceWatch.

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

    CategoryDescription
    namespaceCustom namespace for custom metrics
    • Namespace is a logical division used to classify and group metrics, and is specified as a custom metric to classify custom metrics
    • Namespace must be 3~128 characters including English, numbers, spaces, and special characters (_-/), and must start with English.
    accessKeyIAM authentication key Access Key
    accessSecretIAM authentication key Secret Key
    resourceIdResource ID of the server in Samsung Cloud Platform
    • Example: Resource ID of Virtual Server
    openApiEndpointServiceWatch OpenAPI Endpoint by region/offering
    • Example: https://servicewatch.region.offering.samsungsdscloud.com
    • region and offering information can be checked from Samsung Cloud Platform Console access URL
    telemetryPortTelemetry Port of ServiceWatch Agent
    • Usually uses 8888 Port. If 8888 Port is in use, it needs to be changed
    Table. agent.json Configuration File Items
    Color mode
    {
    "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 of the server in Samsung Cloud Platform
    "openApiEndpoint": "https://servicewatch.kr-west1.e.samsungsdscloud.com",    # ServiceWatch OpenAPI Endpoint by region/environment
    "telemetryPort": 8889               # Telemetry Port of ServiceWatch Agent (Usually uses 8888 Port. If 8888 Port is in use, it needs to be changed)
}
    {
    "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 of the server in Samsung Cloud Platform
    "openApiEndpoint": "https://servicewatch.kr-west1.e.samsungsdscloud.com",    # ServiceWatch OpenAPI Endpoint by region/environment
    "telemetryPort": 8889               # Telemetry Port of ServiceWatch Agent (Usually uses 8888 Port. If 8888 Port is in use, it needs to be changed)
}
    Code Block. agent.json Configuration Example

  2. Define the Metric configuration file for metric collection for ServiceWatch.

    • If you want to collect metrics through the Agent, configure metric.json.
      CategoryDescription
      prometheus > scrape_configs > targetsEndpoint of the metric collection target
      • In the case of a server, since Prometheus Exporter is installed on the same server, set it to that endpoint
      • Example: localhost:9100
      prometheus > scrape_configs > jobNameJob Name setting. Usually set to the Prometheus Exporter type used when collecting metrics
      • Example: node-exporter
      metricMetas > metricNameSet the name of the metric you want to collect. The metric name must be 3~128 characters including English, numbers, and special characters (_), and must start with English.
      • Example: node_cpu_seconds_total
      metricMetas > dimensionsSet the label to visualize and display in the Console among the Collector’s labels provided to identify the source of the Exporter’s metric data. When displaying the collected metric in the Console, it is displayed by combining according to the dimensions setting.
      • Example: In the case of metrics like the Memory Collector of Node Exporter that do not provide special labels, set it to resource_id
      • Example: Node Exporter Filesystem Collector metrics can set dimensions to mountpoint, which represents the path where the filesystem is mounted on the system
      metricMetas > unitCan set the unit of the metric
      • Example: Bytes, Count, etc.
      metricMetas > aggregationMethodMethod of aggregating based on the specified dimensions
      • Example: Select from SUM, MAX, MIN, COUNT
      metricMetas > descriptionKoKorean description of the metric being collected
      metricMetas > descriptionEnEnglish description of the metric being collected
      Table. metric.json Configuration File Items
      Color mode
      {
    "prometheus": {
       "scrape_configs": {
          "targets": [
             "localhost:9100" # Endpoint of Prometheus Exporter installed in 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 to ServiceWatch among metrics collected from Prometheus Exporter
          "dimensions": [
             [
                "resource_id"        # Set the label to visualize and display in the Console among the Collector's labels provided to identify the source of Node Exporter's metric data
                                     # In the case of metrics like Memory that do not provide special labels, set it to resource_id
             ]
          ],
          "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 to ServiceWatch among metrics collected from Prometheus Exporter
          "dimensions": [
             [
                "mountpoint"        # Set the label to visualize and display in the Console among the Collector's labels provided to identify the source of Node Exporter's metric data
                                    # Set dimensions to mountpoint, which represents the path where the filesystem is mounted on the system for Filesystem-related metrics
             ]
          ],
          "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 Prometheus Exporter installed in 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 to ServiceWatch among metrics collected from Prometheus Exporter
          "dimensions": [
             [
                "resource_id"        # Set the label to visualize and display in the Console among the Collector's labels provided to identify the source of Node Exporter's metric data
                                     # In the case of metrics like Memory that do not provide special labels, set it to resource_id
             ]
          ],
          "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 to ServiceWatch among metrics collected from Prometheus Exporter
          "dimensions": [
             [
                "mountpoint"        # Set the label to visualize and display in the Console among the Collector's labels provided to identify the source of Node Exporter's metric data
                                    # Set dimensions to mountpoint, which represents the path where the filesystem is mounted on the system for Filesystem-related metrics
             ]
          ],
          "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 follows and also set resource_name in metricMetas.dimensions, so you can check the resource name together when viewing metrics in ServiceWatch.
      Color mode
      ...
    "commonLabels": {
       "resource_name": "ResourceName" # Resource name that can be checked in User Console
    },
    "metricMetas": [
       {
          "metricName": "metric_name",
          "dimensions": [
             [
                "resource_id",
                "resource_name"        # Add the resource_name set in commonLabels to each metric's dimensions

             ]
          ],
          "unit": "Bytes",
          "aggregationMethod": "SUM",
          "descriptionKo": "metric_name description"
          "descriptionEn": "metric_name description"
       },
    ...
    ]
...
      ...
    "commonLabels": {
       "resource_name": "ResourceName" # Resource name that can be checked in User Console
    },
    "metricMetas": [
       {
          "metricName": "metric_name",
          "dimensions": [
             [
                "resource_id",
                "resource_name"        # Add the resource_name set in commonLabels to each metric's dimensions

             ]
          ],
          "unit": "Bytes",
          "aggregationMethod": "SUM",
          "descriptionKo": "metric_name description"
          "descriptionEn": "metric_name description"
       },
    ...
    ]
...
      Code Block. metric.json - Resource Name Setting

  3. Define the Log configuration file for log collection for ServiceWatch.

    • If you want to collect logs, you must configure log.json.
      CategoryDescription
      fileLog > includeLocation of log files to collect
      fileLog > operatorsDefined to parse log messages to collect
      fileLog > operators > regexExpress log message format as regular expression
      fileLog > operators > timestampFormat of Time Stamp of log message to be sent to ServiceWatch
      logMetas > log_group_valueLog group name created to send logs to ServiceWatch
      logMetas > log_stream_valueLog stream name in ServiceWatch log group
      Table. log.json Configuration File Items
      Color mode
      {
    "fileLog": {
       "include": [
          "/var/log/syslog",        # Log file to collect in ServiceWatch
          "/var/log/auth.log"
       ],
       "operators": {
          "regex": "^(?P<timestamp>\\S+)\\s+(?P<hostname>\\S+)\\s+(?P<process>[^:]+):\\s+(?P<message>.*)$",    # Express log file format as regular expression
          "timestamp": {            # Set Time Stamp format of log message
             "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 in ServiceWatch log group created in advance
    }
}
      {
    "fileLog": {
       "include": [
          "/var/log/syslog",        # Log file to collect in ServiceWatch
          "/var/log/auth.log"
       ],
       "operators": {
          "regex": "^(?P<timestamp>\\S+)\\s+(?P<hostname>\\S+)\\s+(?P<process>[^:]+):\\s+(?P<message>.*)$",    # Express log file format as regular expression
          "timestamp": {            # Set Time Stamp format of log message
             "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 in ServiceWatch log group created in advance
    }
}
      Code Block. log.json Configuration Example
      Note

      To link server log files to ServiceWatch through ServiceWatch Agent, you must first create a log group and log streams within the log group.

      • For more information about creating log groups and log streams, see Logs.

Running Open Telemetry Collector for ServiceWatch

ServiceWatch Agent Execution Method
[ServiceWatch Agent Executable] -action [run|stop] - dir [Configuration File Location] -collector [Open Telemetry Collector Executable Location]
Execution OptionDescription
-actionAction setting (run or stop)
-dirLocation of ServiceWatch Agent configuration files such as agent.json, metric.json, log.json
-collectorLocation of Open Telemetry Collector executable
Table. log.json Configuration File Items

Running ServiceWatch Agent (for Linux)

Note
Assuming that agent.json, metric.json, log.json files are in current_location/agent/examples/os-metrics-min-examples and otelcontribcol_linux_amd64 file is in current_location/agent, execute as follows.

  1. Run ServiceWatch Agent.

    • Check the location of agent.json, metric.json, log.json files and the location of servicewatch-agent-manager-linux-amd64, otelcontribcol_linux_amd64 files and start 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. Starting ServiceWatch Agent - Collecting Both Metrics and Logs
    • If you want to collect only metrics, rename the log.json file to a different file name or move it so it’s not in the same directory as agent.json, metric.json, and execute as follows.
      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. Starting ServiceWatch Agent - Collecting Only Metrics
    • If you want to collect only logs, rename the metric.json file to a different file name or move it so it’s not in the same directory as agent.json, log.json, and execute as follows.
      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. Starting ServiceWatch Agent - Collecting Only Logs

  2. Stop 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. Stopping ServiceWatch Agent

Running ServiceWatch Agent (for Windows)

  1. Run 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. Starting ServiceWatch Agent

  2. Stop 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. Stopping ServiceWatch Agent

Events
ServiceWatch Event Reference