Documentation forAppOptics

REST API

Overview

SWISnap exposes REST API that allows managing and monitoring:

  • tasks
  • plugins
  • metrics

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

This document refers to V3 version of REST API. The old versions V1 and V2 are still available, but not recommended to use.

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:

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

Example output:

Copy
[
  {
    "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:

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

Example output:

Copy
[
  {
    "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:

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

Example output:

Copy
{
  "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 stops task and it’s possible to start it later

Example usage:

Copy
## 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:

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

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

Example output:

Copy
[
  {
    "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. Please 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:

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

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

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

Example output:

Copy
[
  {
    "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"
  },
  ...
]

When the APM Integrated Experience is enabled, AppOptics shares a common navigation and settings with the other integrated experiences' products. How you navigate AppOptics and access its features may vary from these instructions. For more information, go to the APM Integrated Experience documentation.

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.