REST API

Overview

SWISnap exposes REST API that allows managing and monitoring:

tasks
plugins
metrics

This document describes its usage. Check SWISnap configuration for more details on available configuration options.

This document refers to V3 version of REST API. Versions V1 and V2 are still available, but are deprecated.

REST API methods list

Tasks

Get summary information about tasks

GET http://127.0.0.1:21413/v3/tasks

Users can request summary information about all loaded tasks (v1 and v2). Output information contains among others:

task id
href - reference to details information about a single task
task state

Example usage:

curl http://127.0.0.1:21413/v3/tasks

Example output:

[
  {
    "creation_timestamp": 1590059578,
    "deadline": "55s",
    "hit_count": 1,
    "href": "/v3/tasks/5908f536-091c-493e-9a39-b088480c6b1c",
    "id": "5908f536-091c-493e-9a39-b088480c6b1c",
    "last_run_timestamp": 1590059579,
    "master_id": "_30385a3a-7bcd-4f7b-8ac7-5036c10de9bd",
    "name": "5908f536-00-C:\\ProgramData\\SolarWinds\\Snap\\tasks-autoload.d\\task-processes.yaml",
    "task_state": "Running"
  },
  {
    "creation_timestamp": 1590059578,
    "deadline": "55s",
    "hit_count": 1,
    "href": "/v3/tasks/35bf2746-0e49-472e-97db-115c4ccb3b59",
    "id": "35bf2746-0e49-472e-97db-115c4ccb3b59",
    "last_run_timestamp": 1590059580,
    "name": "35bf2746-00-C:\\ProgramData\\SolarWinds\\Snap\\tasks.d\\task-logs.yaml",
    "task_state": "Running"
  },
  {
    "creation_timestamp": 1590059578,
    "deadline": "55s",
    "hit_count": 1,
    "href": "/v3/tasks/55e4a62c-5947-4e2b-9cd4-dd9ce76fff73",
    "id": "55e4a62c-5947-4e2b-9cd4-dd9ce76fff73",
    "last_run_timestamp": 1590059580,
    "master_id": "_9911deb7-2ac3-468f-8ab6-cc66c154dd7c",
    "name": "55e4a62c-00-C:\\ProgramData\\SolarWinds\\Snap\\tasks-autoload.d\\task-aosystem.yaml",
    "task_state": "Running"
  }
]

Get detailed information about a given task

GET http://127.0.0.1:21413/v3/tasks/:id

Users can obtain detailed information about any task. Output information contains among others:

summary information,
list of plugins used by task,
configuration options used to load a given task,
requested metrics (filters)
statistics (ie. total_metrics, collect_requests_succeeded),
recent actions history,
etc.

Example usage:

curl http://127.0.0.1:21413/v3/task/

Example output:

[
  {
    "creation_timestamp": 1590059578,
    "deadline": "55s",
    "hit_count": 28,
    "href": "/v3/tasks/5908f536-091c-493e-9a39-b088480c6b1c",
    "id": "5908f536-091c-493e-9a39-b088480c6b1c",
    "last_run_timestamp": 1590061199,
    "master_id": "_30385a3a-7bcd-4f7b-8ac7-5036c10de9bd",
    "name": "5908f536-00-C:\\ProgramData\\SolarWinds\\Snap\\tasks-autoload.d\\task-processes.yaml",
    "plugins_used": [
      {
        "configuration": {
          "_v1_config_": {
            "snap_version": "3.0.0.4584"
          }
        },
        "counters": {
          "avg_metrics_per_collect": 1042,
          "avg_warnings_per_collect": 0,
          "collect_requests": 28,
          "collect_requests_failed": 0,
          "collect_requests_succeeded": 28,
          "collect_success_rate": 1,
          "total_metrics": 29176
        },
        "filters": [
          "/processes/[process_name]/cpu",
          "/processes/[process_name]/memory",
          "/processes/[process_name]/count",
          "/processes/[process_name]/uptime"
        ],
          "history": {
            "collect": {
              "recent_errors": [],
              "recent_events": [
                {
                  "err": "<nil>",
                  "locked_time": "2020-05-21T13:39:59.8766827+02:00",
                  "locking_time": "2020-05-21T13:39:59.8766827+02:00",
                  "status": "succeeded",
                  "unlocked_time": "2020-05-21T13:40:04.0210139+02:00"
                }
              ]
            },
                ...
          },
          "href": "/v3/plugins/collector/processes/local/11.0.0",
          "key": "collector/processes/local/11.0.0",
          "last_measurement": {
            "duration": 4144331200,
            "processed_metrics": 1104,
            "timestamp": "2020-05-21T13:39:59.8766827+02:00"
          },
          "loaded": "2020-05-21T13:12:59.8556533+02:00",
          "name": "processes",
          "processing_times": {
            "average": 5080215542,
            "maximum": 30751119300,
            "total": 142246035200
          },
          "type": "collector",
          "version": "11.0.0"
        },
        {
          "configuration": {
            "_v1_config_": {
              "snap_version": "3.0.0.4584"
            },
            "endpoint": {
              "token": "SOLARWINDS_TOKEN"
            },
            "options": {
              "ec2": null
            }
          },
          "counters": {
            "avg_metrics_per_collect": 1042,
            "avg_warnings_per_collect": 0,
            "collect_requests": 28,
            "collect_requests_failed": 0,
            "collect_requests_succeeded": 28,
            "collect_success_rate": 1,
            "total_metrics": 29176
          },
          "history": {
            "publish": {
              "recent_errors": [],
              "recent_events": [
                {
                  "err": "<nil>",
                  "locked_time": "2020-05-21T13:40:04.0219903+02:00",
                  "locking_time": "2020-05-21T13:40:04.0219903+02:00",
                  "status": "succeeded",
                  "unlocked_time": "2020-05-21T13:40:04.7873316+02:00"
                }
              ]
            }
            ...
        },
        "href": "/v3/plugins/publisher/publisher-processes/local/48.0.0",
        "key": "publisher/publisher-processes/local/48.0.0",
        "last_measurement": {
          "duration": 765341300,
          "processed_metrics": 1104,
          "timestamp": "2020-05-21T13:40:04.0219903+02:00"
        },
        "loaded": "2020-05-21T13:12:59.8576053+02:00",
        "name": "publisher-processes",
        "processing_times": {
          "average": 1022340853,
          "maximum": 2019545000,
          "total": 28625543900
        },
        "type": "publisher",
        "version": "48.0.0"
      }
    ],
    "schedule": {
      "interval": "1m0s",
      "type": "windowed"
    },
    "task_state": "Running"
  }
]

Peeking collected metrics

GET http://127.0.0.1:21413/v3/tasks/:id/watch

Users can watch metrics collected under a given task in real-time. The output is an infinite stream of JSON objects. Each stream part contains information about a single metric, among others:

metric value (data)
metric name (namespace)
list of tags
time of collection (timestamp)

Example usage:

curl http://127.0.0.1:21413/v3/tasks/55e4a62c-5947-4e2b-9cd4-dd9ce76fff73/watch

Example output:

{
  "data": 114269267456,
  "namespace": "/system/io/C:/bytes/read",
  "source_task_id": "55e4a62c-5947-4e2b-9cd4-dd9ce76fff73",
  "tags": {
    "collector_plugin": "aosystem",
    "collector_plugin_file": "snap-plugin-collector-aosystem.exe",
    "disk": "C:"
  },
  "timestamp": "2020-05-21T13:29:00.0103349+02:00"
}
{
  "data": 57643884032,
  "namespace": "/system/io/C:/bytes/write",
  "source_task_id": "55e4a62c-5947-4e2b-9cd4-dd9ce76fff73",
  "tags": {
    "collector_plugin": "aosystem",
    "collector_plugin_file": "snap-plugin-collector-aosystem.exe",
    "disk": "C:"
  },
  "timestamp": "2020-05-21T13:29:00.0103349+02:00"
}
{
  "data": 321325,
  "namespace": "/system/io/C:/io_time",
  "source_task_id": "55e4a62c-5947-4e2b-9cd4-dd9ce76fff73",
  "tags": {
    "collector_plugin": "aosystem",
    "collector_plugin_file": "snap-plugin-collector-aosystem.exe",
    "disk": "C:"
  },
  "timestamp": "2020-05-21T13:29:00.0103349+02:00"
}
{
  "data": 5644,
  "namespace": "/system/io/C:/time/read",
  "source_task_id": "55e4a62c-5947-4e2b-9cd4-dd9ce76fff73",
  "tags": {
    "collector_plugin": "aosystem",
    "collector_plugin_file": "snap-plugin-collector-aosystem.exe",
    "disk": "C:"
  },
  "timestamp": "2020-05-21T13:29:00.0103349+02:00"
}
{
  "data": 2716,
  "namespace": "/system/io/C:/time/write",
  "source_task_id": "55e4a62c-5947-4e2b-9cd4-dd9ce76fff73",
  "tags": {
    "collector_plugin": "aosystem",
    "collector_plugin_file": "snap-plugin-collector-aosystem.exe",
    "disk": "C:"
  },
  "timestamp": "2020-05-21T13:29:00.0103349+02:00"
}
...

Start/stop task

PUT http://127.0.0.1:21413/v3/tasks/:id

Users can request starting/stopping a given task. For new tasks (v2) requesting to stop is equal to removing the task (it won't be possible to start it again). For legacy tasks (v1) stop will only stop the task; it is possible to start it later and if you want the task removed, it has to be requested as a separate command.

Example usage:

## v2
curl -X PUT http://127.0.0.1:21413/v3/tasks/5908f536-091c-493e-9a39-b088480c6b1c?action=stop

## v1
curl -X PUT http://127.0.0.1:21413/v3/tasks/35bf2746-0e49-472e-97db-115c4ccb3b59?action=stop
curl -X PUT http://127.0.0.1:21413/v3/tasks/35bf2746-0e49-472e-97db-115c4ccb3b59?action=start

Delete task

DELETE http://127.0.0.1:21413/v3/tasks/:id

Users can request to delete a given task. After this operation, the task won't be listed anymore by GET http://127.0.0.1:21413/v3/tasks request.

For removing a legacy (v1) task, it is needed to stop it first.

Example usage:

curl -X DELETE http://127.0.0.1:21413/v3/tasks/35bf2746-0e49-472e-97db-115c4ccb3b59

Plugins

Get information about running plugins

GET http://127.0.0.1:21413/v3/plugins

Users can request a list of running plugins. List contains plugins of both versions: v1 and v2. Moreover, there are single binaries that can be executed in two instances (in v1 and v2 compatibility mode), eg. publisher-appoptics.

Example usage:

curl http://127.0.0.1:21413/v3/plugins/

Example output:

[
  {
    "href": "/v3/plugins/collector/aosystem/58.0.0",
    "last_hit_timestamp": "2020-05-21T14:14:00.0003124+02:00",
    "loaded_timestamp": "2020-05-21T13:57:50.1262301+02:00",
    "name": "aosystem",
    "runtime": "local",
    "signed": false,
    "status": "running",
    "task_version": "PluginsV2",
    "type": "collector",
    "version": "58.0.0"
  },
  {
    "href": "/v3/plugins/publisher/publisher-appoptics/48.0.0",
    "last_hit_timestamp": "2020-05-21T14:14:01.7398349+02:00",
    "loaded_timestamp": "2020-05-21T13:57:50.7189664+02:00",
    "name": "publisher-appoptics",
    "runtime": "local",
    "signed": false,
    "status": "running",
    "task_version": "PluginsV2",
    "type": "publisher",
    "version": "48.0.0"
  },
  {
    "href": "/v3/plugins/collector/logs/15.0.0",
    "last_hit_timestamp": "2020-05-21T14:14:00.0237093+02:00",
    "loaded_timestamp": "2020-05-21T13:57:50.2492066+02:00",
    "name": "logs",
    "pprof_port": "0",
    "signed": false,
    "status": "running",
    "task_version": "PluginsV1",
    "type": "collector",
    "version": "15.0.0"
  },
  {
    "href": "/v3/plugins/publisher/publisher-appoptics/48.0.0",
    "last_hit_timestamp": "2020-05-21T14:14:00.684609+02:00",
    "loaded_timestamp": "2020-05-21T13:57:50.716047+02:00",
    "name": "publisher-appoptics",
    "pprof_port": "0",
    "signed": false,
    "status": "running",
    "task_version": "PluginsV1",
    "type": "publisher",
    "version": "48.0.0"
  },
]

Loading plugin

POST http://127.0.0.1:21413/v3/plugins

The plugin v1 or v2 can be loaded manually. It can be helpful when the plugin has been prepared by customer or there is no plugin in the package. Be aware that after loading v1 plugin it will be visible on the plugin list no matter if the task has been started or not. For v2 the plugin will be visible on the plugin list after the task is started. The localization for uploaded plugin binaries is:

/opt/SolarWinds/Snap/bin/uploaded on Linux
C:\ProgramFiles\SolarWinds\Snap\bin\uploaded on Windows

It can be loaded in the following ways:

binary file local to snap

Example usage:

curl -d "plugin_data=/opt/SolarWinds/Snap/bin/snap-plugin-collector-logs" http://127.0.0.1:21413/v3/plugins

binary file local to the REST caller (the only one will be sent as binary payload)

Example usage:

curl -F "plugin_data=@/opt/SolarWinds/Snap/bin/snap-plugin-collector-logs" http://127.0.0.1:21413/v3/plugins

remote plugin instance (aka standalone plugin)

Example usage:

curl -d "plugin_uri=http://example.com/opt/SolarWinds/Snap/bin/snap-plugin-collector-logs" http://127.0.0.1:21413/v3/plugins

Metrics

Get metrics list registered by legacy (v1) plugins

GET http://127.0.0.1:21413/v3/metrics

Users can request a list of all metrics available in the SWISnap catalog. Due to the changes in architecture, new plugins are not registering their metrics list in SWISnap and thereby won't be listed in the output.

Example usage:

curl http://127.0.0.1:21413/v3/metrics

Example output:

[
  {
    "dynamic": false,
    "href": "http://127.0.0.1:21413/v3/metrics?ns=%2Flogs%2Fattempts_total&ver=15.0.0",
    "last_advertised_timestamp": 1590062269,
    "namespace": "/logs/attempts_total",
    "policy": [
      {
        "default": "tls",
        "name": "api_protocol",
        "required": false,
        "type": "string"
      },
      ...
    ],
    "version": "15.0.0"
  },
  {
    "dynamic": false,
    "href": "http://127.0.0.1:21413/v3/metrics?ns=%2Flogs%2Fbytes_failed&ver=15.0.0",
    "last_advertised_timestamp": 1590062269,
    "namespace": "/logs/bytes_failed",
    "policy": [
      {
        "name": "hostname",
        "required": false,
        "type": "string"
      },
      ...
    ],
    "version": "15.0.0"
  },
  ...
]

Navigation Notice: When the APM Integrated Experience is enabled, AppOptics shares a common navigation and enhanced feature set with other integrated experience products. How you navigate AppOptics and access its features may vary from these instructions.

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.

Search SolarWinds Support

REST API

Overview

REST API methods list

Tasks

Get summary information about tasks

Get detailed information about a given task

Peeking collected metrics

Start/stop task

Delete task

Plugins

Get information about running plugins

Loading plugin

Metrics

Get metrics list registered by legacy (v1) plugins