On-demand Diagnostics API and from AGENT Checks

It isn’t always obvious what’s going on when a check fails and additional information about what our probes are seeing can be helpful for troubleshooting. The NodePing diagnostic tools allow you to run several utilities to get information about what our probes are seeing. Now we’ve brought that functionality to our AGENT checks as well as a new API endpoint.

Diagnostics from AGENTs

You can now connect your AGENT checks to our diagnostics servers to run our most useful tools: mtr, ping, traceroute, and dig. Use the instructions in the AGENT software to run the diagnostic client on your AGENT. Your AGENTs will appear in the ‘location’ dropdown of the Diagnostic Tools in NodePing.

Diagnostics API

On-demand diagnostics can now be requested via our REST API. Your integrations can request NodePing diagnostics from any of our probes as well as from your AGENTs with a simple HTTP request. Please see the diagnostics API documentation for details.

If you don’t have a NodePing account, you can sign up for a free, 15-day trial and experience the fast and accurate service NodePing provides.

Using NodePing’s API with Python

Over the years, NodePing has offered an API to manage most aspects of your monitoring. Today, we are introducing our new Python 2/3 library to interface with this API. Instead of reinventing the wheel in your code to interact with our API, drop this library into your project and with a few lines you can easily manage your checks and various other aspects of your account. With the Python library at your disposal, you can:

  • List, create, update, and delete checks
  • Manage contacts
  • Manage contact groups
  • Manage schedules
  • Get check results and uptime
  • Get notification information
  • Get probe information

This means that the Python library has feature parity with our API. You can get the code from our GitHub repository or install it from Pypi via pip. There is also some documentation written to help you by providing snippets of what your code might look like when querying the API with Python.

In this post, we will share a brief introduction to getting started with using the Python library and how it can be used to manage your account. You can use your installer of choice, but in this introduction I will use pip to install the library:


pip install nodeping-api

 

You may have to specify Python2 or 3 for your pip version, depending on your system. To start using the library, you will need to provide your API token as a variable, and an optional subaccount ID to start managing your checks.

 

From here, you can do things such as list failing checks:


#!/usr/bin/env python
# -*- coding: utf-8 -*-

""" Demo for Python library
"""

from pprint import pprint
from nodeping_api import get_checks

def main():
    """ Main function
    """

    token = 'my-secret-token'

    query = get_checks.GetChecks(token)
    checks = query.failing_checks()

    pprint(checks)

if __name__ == '__main__':
    main()

 

This example will collect all your failing checks and return them to be used in a dictionary format. The output might look something like this:

{'2019052211307H0IX-KCGJCX1X': {'_id': '2019052211307H0IX-KCGJCX1X',
    'created': 1563471438952,
    'customer_id': '2019052211307H0IX',
    'dep': False,
    'enable': 'active',
    'firstdown': 1563471472497,
    'homeloc': False,
    'interval': 3,
    'label': 'Test Check',
    'modified': 1563471438952,
    'notifications': [],
    'parameters': {'follow': False,
        'ipv6': False,
        'sens': 2,
        'target': 'https://notreal.nodeping.com/',
        'threshold': 5},
    'public': False,
    'queue': 'utcoCpoUJx',
    'runlocations': False,
    'state': 0,
    'status': 'assigned',
    'type': 'HTTP',
    'uuid': 've8s9sgj-j588-4li3-9ytp-1kho9wtutriy'}}

 

You can also create checks. For example, here is a basic idea of creating an HTTP check:

#!/usr/bin/env python
# -*- coding: utf-8 -*-

""" Demo for Python library
"""

from pprint import pprint
from nodeping_api import create_check

def main():
    """ Main function
    """

    token = 'my-secret-token'

    target = 'https://nodeping.com'
    enabled = True
    public = False
    interval = 1
    runlocations = 'nam'

    created = create_check.http_check(
        token,
        target,
        label="Check NodePing",
        enabled=enabled,
        public=public,
        interval=interval,
        runlocations=runlocations
    )

    pprint(created)

if __name__ == '__main__':
    main()

 

Along with the output when the check is created. Note that it is in a dictionary format, but pretty printed so it’s easier to read here:

{'_id': '2019052211307H0IX-WEOR7GAH',
 'change': 1563474539024,
 'created': 1563474539024,
 'customer_id': '2019052211307H0IX',
 'dep': False,
 'enable': 'active',
 'homeloc': False,
 'interval': 1,
 'label': 'Check NodePing',
 'modified': 1563474539024,
 'parameters': {'follow': False,
                'ipv6': False,
                'sens': 2,
                'target': 'https://nodeping.com/',
                'threshold': 5},
 'runlocations': ['nam'],
 'public': False,
 'status': 'modified',
 'type': 'HTTP',
 'uuid': '1fog8q51-zdhv-4vmb-832r-tsun0o9unt3f'}

 

You can also get your uptime from a certain time interval. In this example, you can find what your uptime is since July, 2019

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from nodeping_api import results
from pprint import pprint


def main():
    """
    """

    token = 'my-secret-token'
    check_id = 'my-check-id'

    # Get uptime since July, 2019
    uptime_results = results.get_uptime(token, check_id, start="2019-07")

    pprint(uptime_results)


if __name__ == '__main__':
    main()

 

This will give you an output that looks something like this:
{'2019-07': {'down': 2154131, 'enabled': 2678400000, 'uptime': 99.92},
'2019-08': {'down': 88733, 'enabled': 753256766, 'uptime': 99.988},
'total': {'down': 2242864, 'enabled': 3431656766, 'uptime': 99.935}}

This is only a snippet of what the library can do, and the documentation is detailed to get you started on your journey. Give it a try and see how you can improve your uptime monitoring in your Python projects. This code is free and available to download. We encourage pull requests for new features so if you make changes or have requests, feel free to share.

If you aren’t using NodePing yet, you can sign up for a free, 15-day trial and test out monitoring your services today and take advantage of our API in your own Python projects.

The NodePing API and PowerShell

At NodePing we interact with our own API quite a bit from the command line.  Most of that is from bash on Linux, because that’s where we live most of our lives.  But the API works well from just about any scripting environment.  Since our documentation examples all use curl with bash syntax, it seemed like it might be a good idea to also write up some examples of using other tools.  Here, as the first installment of that effort, is a handful of examples of using PowerShell with the NodePing API.

Full disclosure: PowerShell is not an environment we spend a lot of time working with.  There are likely ways to do some of this better.  We’ve tested the example calls in this post.  Hopefully it is enough to get you started if you work with PowerShell.

Basic GET Calls

Basic calls are quite simple to make using Invoke-RestMethod.  If you have the check ID, getting a check is quite easy:

Invoke-RestMethod ‘https://api.nodeping.com/api/1/checks/201205050153W2Q4C-OJ2HSIRF?token=[token]’

This returns a JSON object, which PowerShell handles easily.

_id : 201205050153W2Q4C-0J2HSIRF
description : This is the description, if the check has one.
public : False
customer_id : 201205050153W2Q4C
queue : nyI8JSL23W
interval : 1
created : 1427513104608
pro : nodeping.com
modified : 1510332098196
parameters : @{target=https://example.com/; follow=False; threshold=5; sens=2; invert=False; verify=false}
firstdown : 0
label : Keep me
runlocations : False
enable : active
uuid : bd3eha9o-z2m5-4qg2-9k8b-jqq0kiituyxz
state : 1
status : assigned
notifications : {}
type : HTTP
acctdisable : False
suspacct : False
dep : False

Note that “parameters” is another hash.  You can refer to the fields in the check as properties of the returned object, including properties that are hashes themselves.  So, for example, this will give you the check check threshold, which is part of “parameters”.

$check = Invoke-RestMethod ‘https://api.nodeping.com/api/1/checks/201205050153W2Q4C-0J2HSIRF?token=[token]’ ;
$check.parameters.threshold;

API Authentication

PowerShell doesn’t easily support basic authentication.  Since the NodePing API supports passing the token as a parameter, the easiest approach is to include it in the query string, as I did in the example above.  In most cases I prefer to pass it in the Body, as I’ll show in examples below.  If you’re working with a script its usually easiest to set a $token variable and use that throughout your script.  If you’re just sending a URL as I did in the simple GET calls above, actually putting in the query string works fine.

If you’re using the API in scripts that make several calls to the API, you might want a more reusable way to pass the token that keeps it out of your Body.  You can do this by manually building the headers.  That requires base64 encoding the credentials and then setting that using the -Headers argument. That looks something like this:

$hash = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $token,"")))

Then set the -Header argument to @{Authorization=(“Basic {0}” -f $hash)}

Or, if you are doing this several times, you will probably want to set this to a variable you can reuse.

Some sites suggest that you create a credential object using ConvertTo-SecureString and Management.Automation.PSCredential, and pass that using the -Credential argument.  However, this won’t work with the NodePing API, since the -Credential option waits for the challenge to send the authorization header.  The API is stateless, and expects the header on each request.

Put and Post Calls

We recommend that you use JSON to set fields for our API in most environments.  However, PowerShell does not automatically handle sending the body as JSON.  For POST calls, this isn’t a big deal, and you can just POST the body as it is and Invoke-RestMethod sends the data as if it were a form.  PUT and DELETE calls don’t work that way.  For those, you have to convert to JSON, or include all of your parameters in a query string.

Creating a check looks like this:

Invoke-RestMethod 'https://api.nodeping.com/api/1/checks' -Method Post -Body @{ 
    label='test label' 
    type="HTTP"
    target="http://example.com"
    token=$token 
}

This call will return an object with the new check.  You can add any of the other fields listed in our documentation.

Updating a check is almost the same.  This can all be done on one line, but we’ll split it out here to make it easier to see.

$data = @{ label='a new label'; type="HTTP"; interval=5; token=$token } | ConvertTo-Json
Invoke-RestMethod 'https://api.nodeping.com/api/1/checks/201205050153W2Q4C-0J2HSIRF' -Method Put -Body $data

Note that since we’re updating a check, we need to include the check ID.  As with the Post call, the Put call returns the updated check object.

Working with Lists of Checks

Working with a list of checks is slightly trickier.  The call returns a JSON object with a list of checks using the ID as the key.  For PowerShell, this is a hash table of hashes.  So to list checks, you would do something like this:

Invoke-RestMethod 'https://api.nodeping.com/api/1/checks' -Body @{ token=$token } | %{ $_.PSOBJECT.Properties.value }

This is actually fairly handy, because you can fairly easily list a specific field from the response.  For example, this lists all of the targets from all of the checks on this account:

Invoke-RestMethod 'https://api.nodeping.com/api/1/checks' -Body @{ token=$token } | %{ $_.PSOBJECT.Properties.value.parameters.target }

You could do all sorts of things at this point.  For example, here’s a list of all checks that include “nodeping” somewhere in the check’s target:

Invoke-RestMethod 'https://api.nodeping.com/api/1/checks' -Method Get -Body @{ token=$token } | %{ foreach($value in $_.PSOBJECT.Properties.value){ if($value.parameters.target -like "*nodeping*"){ $value } } }

This is practical as a way to find a check with a specific target up to a few thousand checks.

Getting Results

Applying the same principles should let you do just about anything with the NodePing API.  Applying the same pattern to a results call, for example:

Invoke-RestMethod 'https://api.nodeping.com/api/1/results/201205050153W2Q4C-0J2HSIRF' -Method Get -Body @{ token=$token; limit=2; clean=1 }

Note that you’ll want to always include the “clean” parameter for results.  The unclean response takes more parsing.

The options available for results calls are documented here:
https://nodeping.com/docs-api-results.html

Profit!

That’s the basics of using PowerShell to interact with the NodePing API.  With the API you can add checks, remove checks, get your results and uptime, manage contacts and notifications, and add and manage subaccounts.  Our customers use the API both for programmed integrations, and from the command line using quick scripts like the ones I demonstrated here to make quick changes to several (or lots) of checks at once.

If you’re doing interesting things with PowerShell and the NodePing API, we’d like to hear about it!  Please email support and let us know.  That’s also a great place to ask us questions.  We’re happy to help people interact with our service.

Minor API enhancements added today

We have a couple of updates to our API.

You can obtain the current status of your checks using /api/1/results/current. This returns a list of checks that currently have an “event,” which means that the check is currently disabled or is listed as “down.” The information returned will include a timestamp when the event started. Checks not listed in the results for this call are currently “up.”

We’re also adding a couple of convenience tweaks. When you are getting a list of checks, you can add a “current” parameter in order to have any current events added to the check information. This basically mixes the information from the “current” call mentioned above in with the list of checks.

Additionally, when you are getting a single check, you can add a “lastresult” parameter to the request and get the most recent result for that check along with the check information.

All three of these changes are included in our API Reference documenation. Hopefully these minor enhancements will be of help. Feedback is welcome here or at support@nodeping.com.

New Uptime Reporting

Recently we have been working on some of our reports. As a part of that process, we are releasing a new uptime report. The report allows you to see uptime statistics for an individual monitor grouped by days or months. This allows you to get accurate reporting for any check for any given month for which data is in our database.

You can set arbitrary date ranges for the report. This report is publicly available if you have public reporting turned on for the check. As with our other reports, it is available in a web page, as JSON, or CSV format. The report is described in more detail in our report documentation.

The same uptime data is also available through the API.

We will be adding additional views of this data in the near future.