Skip to content

Getting Started

Jump to bottom
lordmilko edited this page Jul 24, 2024 · 47 revisions

Contents

Before you can use PrtgAPI, you must first install it. Please see Installation for instructions on how to do this and verify your installation is working.

C#

Connecting

All interactions performed by PrtgAPI are accessed via the PrtgClient class. To create a PrtgClient, specify the server, username and password you wish to connect to PRTG with. All types in PrtgAPI can be found under the PrtgAPI namespace.

var client = new PrtgClient("prtg.mycoolsite.com", "username", "password");

If a protocol is not specified, PrtgAPI assumes HTTPS. If your server does not support HTTPS, you must manually specify http://

var client = new PrtgClient("http://prtg.mycoolsite.com", "username", "password");

When constructed with a password, the PrtgClient will immediately attempt to resolve your PassHash - an alternate authentication token used by PRTG. Once your PassHash has been retrieved, your password is discarded. If you receive an exception upon trying to establish your PrtgClient, please see Troubleshooting for a list of common errors.

If you wish to use your PassHash instead of your password, you can instruct the PrtgClient constructor to treat the password field as a PassHash by specifying the AuthMode parameter.

var client = new PrtgClient("prtg.example.com", "username", "123456", AuthMode.PassHash);

PrtgAPI provides a number of request types that can be used when interfacing with PRTG. For more information, see Requests.

Session Management

Depending on the performance of your PRTG install, PRTG may time out while handling a request, causing your program to throw an exception. You can tell PrtgAPI to automatically retry timed out requests by specifying the RetryCount and RetryDelay properties of your PrtgClient.

client.RetryCount = 1;
client.RetryDelay = 3;

PrtgAPI uses a backoff algorithm, wherein each successive attempt will wait an increasing multiple of the specified RetryDelay before trying again. As such, generally speaking it is recommended to use a small RetryDelay, and simply specify a large RetryCount; if you specify a RetryDelay of 20 seconds, after 3 retries you might find it's now actually waiting a minute between each successive attempt!

You can be notified whenever a request is retried by hooking into the RetryRequest event handler

client.RetryRequest += (sender, args) => {
    Console.WriteLine($"{args.Exception.Message}. Retries remaining: {args.RetriesRemaining}");
};

As the PRTG API is stateless, there is no need to dispose of your client after you have finished using it.

To begin retrieving data from PRTG, please see Sensors

PowerShell

Connecting

To connect to a PRTG Server, call the Connect-PrtgServer cmdlet.

Connect-PrtgServer prtg.mycoolsite.com

You will be prompted to enter your credentials. If you wish to use PrtgAPI in a script you can use the New-Credential cmdlet to create a PSCredential for you

Connect-PrtgServer prtg.mycoolsite.com (New-Credential username password)

Note that if a protocol is not specified, PrtgAPI assumes HTTPS. If your server does not support HTTPS, you must manually specify http://

Connect-PrtgServer http://prtg.mycoolsite.com

If you receive an exception upon trying to connect to your PRTG server, please see Troubleshooting for a list of common errors.

If you wish to connect using your PassHash instead of your password, you can specify the -PassHash parameter

Connect-PrtgServer prtg.mycoolsite.com (New-Credential username 1234567890) -PassHash

Once connected to a PRTG Server, you can optionally store your credentials for future use

Session Management

To view your current client, invoke the Get-PrtgClient cmdlet

C:\> Get-PrtgClient

Server     : prtg.mycoolsite.com
Username   : username
PassHash   : 1234567890
RetryCount : 1
RetryDelay : 3
LogLevel   : Trace, Request

Properties defined on your PrtgClient can be modified after your session has been established by accessing your PrtgClient directly, or in a more PowerShell friendly manner via the Set-PrtgClient cmdlet

Set-PrtgClient -LogLevel All -RetryCount 3

By default, if a connection times out (such as because PRTG is currently under high load), PrtgAPI will wait 3 seconds before making an additional attempt. The RetryCount and RetryDelay can also be specified when initializing your PrtgClient, or can also be modified afterwards

Connect-PrtgServer prtg.example.com -RetryCount 2
(Get-PrtgClient).RetryDelay = 5

PrtgAPI uses a backoff algorithm, wherein each successive attempt will wait an increasing multiple of the specified RetryDelay before trying again. As such, generally speaking it is recommended to use a small RetryDelay, and simply specify a large RetryCount; if you specify a RetryDelay of 20 seconds, after 3 retries you might find it's now actually waiting a minute between each successive attempt!

Whenever PrtgAPI retries a request, a message will be sent to the PowerShell warning stream.

By using Get-PrtgClient in conjunction with Connect-PrtgServer, it is possible to allow your script to only re-connect when a session is not active.

if(!(Get-PrtgClient))
{
    Connect-PrtgServer prtg.mycoolsite.com
}

To disconnect from a PRTG Server (clear your PrtgClient) call the Disconnect-PrtgServer cmdlet. Note that PrtgAPI is stateless; as such, disconnecting is usually unnecessary.

If you attempt to call Connect-PrtgServer when already connected to a PRTG Server, you will get an error. To override this behavior (and connect to a potentially different PRTG Server) invoke Connect-PrtgServer with the -Force parameter.

Connect-PrtgServer prtg.mycoolersite.com -Force

To begin retrieving data from PRTG, see Sensors

See Also

Project Overview

User Guide

Utilities

Clone this wiki locally