Documentation forAppOptics

SWISnap Command Line

Overview

The swisnap is a CLI tool to manage the SolarWinds Snap Agent. It is based on the SWISnap REST API V3. Agent versions prior to version 3 were using REST API V1.

To learn more about REST API, please check the REST API documentation

Usage

The solarwinds-snap-agent package installs swisnap in /opt/SolarWinds/Snap/bin/swisnap on Linux and in C:\Program Files\SolarWinds\Snap\bin\swisnap.exe on Windows. General usage:

Copy
$ swisnap [global options] command [command options] [arguments...]

Global options

Copy
--url value, -u value   Sets the URL to use (default: "http://localhost:21413") [$SNAP_URL]
--insecure         Ignore certificate errors when Snap's API is running HTTPS [$SNAP_INSECURE]
--password, -p       Require password for REST API authentication [$SNAP_REST_PASSWORD]
--config value, -c value  Path to a config file [$SNAP_CONFIG_PATH, $SNAPCTL_CONFIG_PATH]
--timeout value, -t value Timeout to be set on HTTP request to the server (default: 10s)
--help, -h         show help
--version, -v       print the version

Commands

Copy
metric
plugin
task
help, h   Shows a list of commands or help for one command

Command Options

task

Copy
$ swisnap task command [command options] [arguments...]

 

Copy
create There are two ways to create a task.
       1) Use a task manifest with [--task-manifest]
       2) Provide a workflow manifest and schedule details.
       
* Note: Start and stop date/time are optional.

list   list
details details <task_id>
start  start <task_id>
stop   stop <task_id>
remove  remove <task_id>
watch  watch <task_id>

plugin

Copy
$ swisnap plugin command [command options] [arguments...]

 

Copy
load  load <plugin_path> [--plugin-asc=<plugin_asc_path>] [--plugin-cert=<plugin_cert_path>] [--plugin-key=<plugin_key_path>] [--plugin-ca-certs=<ca_cert_paths>]
unload unload <plugin_type> <plugin_name> <plugin_version>
list  list
config

metric

Copy
$ swisnap metric command [command options] [arguments...]

 

Copy
list list
get  get details on metric(s)

Example Usage

task

Listing tasks:

Copy
$ swisnap task list

 

Copy
+----------------------------------------+-----------+-------------+--------------+-----------+------------+------------+
|      TASK ID / PLUGIN                  |    TYPE   | LAST ACTION |   DURATION   | PROCESSED |   STATUS   | LAST ERROR |
+----------------------------------------+-----------+-------------+--------------+-----------+------------+------------+
| 8cd79cab-00-task-aosystem.yaml         |           |             |              |           |            |            |
|  8cd79cab-7b68-40ab-9957-4b2bcee24777  |           |             |              |           |            |            |
|   aosystem                             | collector | collect     | 4.018737ms   |      78   | ++++++++++ | N/A        |
|   publisher-appoptics                  | publisher | publish     | 2.314005666s |      78   | ++++++++++ | N/A        |
| d585a634-00-task-processes.yaml        |           |             |              |           |            |            |
|  d585a634-96ac-421b-9b56-14b7dadc4b6f  |           |             |              |           |            |            |
|   processes                            | collector | collect     | 3.030227059s |     132   | ++++++++++ | N/A        |
|   publisher-processes                  | publisher | publish     | 640.493525ms |     132   | ++++++++++ | N/A        |
+----------------------------------------+-----------+-------------+--------------+-----------+------------+------------+

Task details:

Copy
$ swisnap task details d585a634-96ac-421b-9b56-14b7dadc4b6f

 

Copy
[
  {
    "id": "d585a634-96ac-421b-9b56-14b7dadc4b6f",
    "href": "/v3/tasks/d585a634-96ac-421b-9b56-14b7dadc4b6f",
    "name": "d585a634-00-task-processes.yaml",
    "deadline": "55s",
    "creation_timestamp": 1589927868,
    "last_run_timestamp": 1589992369,
    "hit_count": 1076,
    "task_state": "Running",
    "master_id": "_7166b636-5e28-44f3-ab9a-865f707ab6ef",
    "schedule": {
      "type": "windowed",
      "interval": "1m0s"
    },
    "plugins_used": [
      {
        "href": "/v3/plugins/collector/processes/local/11.0.0",
        "name": "processes",
        "type": "collector",
     ...

Watching task:

Copy
$ swisnap task watch d585a634-96ac-421b-9b56-14b7dadc4b6f

 

Copy
[2020-05-20T16:38:52.94159661Z] /processes/sshd/cpu = 0
[2020-05-20T16:38:52.941604856Z] /processes/sshd/memory = 0.307209312915802
[2020-05-20T16:38:52.941610392Z] /processes/sshd/count = 1
[2020-05-20T16:38:52.941615636Z] /processes/sshd/uptime = 6.9571936e+07
[2020-05-20T16:38:52.94162475Z] /processes/snap-plugin-publisher-appoptics/cpu = 0
[2020-05-20T16:38:52.941630978Z] /processes/snap-plugin-publisher-appoptics/memory = 2.2923760414123535
[2020-05-20T16:38:52.94163602Z] /processes/snap-plugin-publisher-appoptics/count = 1
[2020-05-20T16:38:52.941640921Z] /processes/snap-plugin-publisher-appoptics/uptime = 6.4861937e+07
[2020-05-20T16:38:52.941648967Z] /processes/systemd-journald/cpu = 0
[2020-05-20T16:38:52.94165458Z] /processes/systemd-journald/memory = 0.6409773826599121
[2020-05-20T16:38:52.941659775Z] /processes/systemd-journald/count = 1
[2020-05-20T16:38:52.941664641Z] /processes/systemd-journald/uptime = 3.6607938e+07
[2020-05-20T16:38:52.941671504Z] /processes/kthreadd/cpu = 0
...

Creating task:

Prepare a task manifest file in json or yaml format. As an example we will use task-aosystem-cpu.yaml, with following content:

Copy
version: 2
 
schedule:
  type: cron
  interval: "0 * * * * *"

plugins:
  - plugin_name: aosystem

  config:
    ## mount_points allows filtering mount points that will be monitored.
    ## The default behavior is to monitor only physical devices (ie. hard disks, USB, etc.).
    ## To enable monitoring of all devices, use ‘*'.
    # mount_points:
    #  - /dev
    #  - /run
    ## exclude_disks allows to define which mount points should not be monitored.
    ## Basic globbing patterns are supported.
    # exclude_disks:
    #  - /dev/loop*
    #  - /dev/sdb1

  metrics:
    - /system/cpu/guest
    - /system/cpu/idle
    - /system/cpu/interrupt
    - /system/cpu/iowait
    - /system/cpu/steal
    - /system/cpu/system
    - /system/cpu/user
    - /system/cpu/utilization
    - /system/cpu/per_cpu/[cpu]/guest
    - /system/cpu/per_cpu/[cpu]/idle
    - /system/cpu/per_cpu/[cpu]/interrupt
    - /system/cpu/per_cpu/[cpu]/iowait
    - /system/cpu/per_cpu/[cpu]/steal
    - /system/cpu/per_cpu/[cpu]/system
    - /system/cpu/per_cpu/[cpu]/user
    - /system/cpu/per_cpu/[cpu]/utilization

 

Copy
$ swisnap task create -t task-aosystem-cpu.yaml

 

Copy
Using task manifest to create task
Task created
ID: 257b2811-2b03-466a-afb2-306ae4975f43
Name: Task-257b2811-2b03-466a-afb2-306ae4975f43
State: Running

Stopping task:

Copy
$ swisnap task stop 257b2811-2b03-466a-afb2-306ae4975f43

 

Copy
Task stopped

Removing task:

Copy
$ swisnap task remove 257b2811-2b03-466a-afb2-306ae4975f43

 

Copy
Task removed

plugin

Listing plugins:

Copy
$ swisnap plugin list

 

Copy
NAME                    TYPE         API          VERSION    RUNTIME    SIGNED     STATUS      LOADED TIME
publisher-appoptics     publisher    PluginsV1    48.0.0                false      loaded      Tue, 19 May 2020 22:37:48 UTC
aosystem                collector    PluginsV2    58.0.0     local      false      running     Tue, 19 May 2020 22:37:48 UTC
processes               collector    PluginsV2    11.0.0     local      false      running     Tue, 19 May 2020 22:37:48 UTC
publisher-appoptics     publisher    PluginsV2    48.0.0     local      false      running     Tue, 19 May 2020 22:37:49 UTC
publisher-processes     publisher    PluginsV2    48.0.0     local      false      running     Tue, 19 May 2020 22:37:49 UTC

Loading plugin:

Copy
$ swisnap plugin load /opt/SolarWinds/Snap/bin/snap-plugin-collector-logs

 

Copy
[
  {
    "loaded_plugin": {
      "name": "logs",
      "version": "15.0.0",
      "type": "collector",
      "signed": false,
      "status": "loaded",
      "loaded_timestamp": 1589989454,
      "href": "http://localhost:21413/v1/plugins/collector/logs/15.0.0"
    },
    "plugin_api_version": "PluginsV1",
    "Err": null
  }
]

Unloading plugin:

Copy
$ swisnap plugin load unload collector logs 15.0.0

 

Copy
Plugin unloaded
Name: logs
Version: 15.0.0
Type: collector

metric

Metric commands are supported only for plugins implemented with plugin framework V1

Listing metrics:

Copy
$ swisnap metric list

 

Copy
NAMESPACE                    VERSIONS
/logs/attempts_total         15.0.0
/logs/bytes_failed           15.0.0
/logs/bytes_forwarded        15.0.0
/logs/bytes_succeeded        15.0.0
/logs/failed_attempts_total  15.0.0
/logs/lines_failed           15.0.0
/logs/lines_forwarded        15.0.0
/logs/lines_skipped          15.0.0
/logs/lines_succeeded        15.0.0
/logs/lines_total            15.0.0

Metric details:

Copy
$ swisnap metric get details --metric-namespace /logs/attempts_total

 

Copy
NAMESPACE                VERSION     UNIT  LAST ADVERTISED TIME             DESCRIPTION
/logs/attempts_total     15.0.0            Wed, 20 May 2020 16:18:43 UTC

  Rules for collecting /logs/attempts_total:
    NAME                      TYPE      DEFAULT   REQUIRED    MINIMUM     MAXIMUM
    write_timeout             string    30s       false
    exclude_patterns          string              false
    hostname                  string              false
    api_protocol              string    tls       false
    exclude_files             string              false
    windows_events            string              false
    papertrail_token          string              false
    api_port                  integer             false
    loggly_token              string              false
    connect_timeout           string    30s       false
    files                     string              false
    max_line_length           integer   1024      false
    new_file_check_interval   string    30s       false
    api_host                  string              false

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.