README
¶
checkly
checkly is a Go library for the Checkly website monitoring service. It allows you to create new checks, get data on existing checks, and delete checks.
While you can manage your Checkly checks entirely in Go code, using this library, you may prefer to use Terraform. In that case, you can use the Checkly Terraform provider (which in turn uses this library):
https://github.com/checkly/terraform-provider-checkly
Setting your API key
To use the client library with your Checkly account, you will need an API Key for the account. Go to the Account Settings: API Keys page and click 'Create API Key'.
Using the Go library
Import the library using:
import checkly "github.com/checkly/checkly-go-sdk"
Creating a client
Create a new Client object by calling checkly.NewClient() with your API key:
apiKey := "3a4405df05894f4580758b40e48e6e10"
client := checkly.NewClient(apiKey)
Or read the key from an environment variable:
client := checkly.NewClient(os.Getenv("CHECKLY_API_KEY"))
Creating a new check
Once you have a client, you can create a check. First, populate a Check struct with the parameters you want:
wantCheck := checkly.Check{
Name: "My API Check",
Type: checkly.TypeAPI,
Frequency: 5,
DegradedResponseTime: 5000,
MaxResponseTime: 15000,
Activated: true,
Muted: false,
ShouldFail: false,
DoubleCheck: false,
SSLCheck: true,
LocalSetupScript: "",
LocalTearDownScript: "",
Locations: []string{
"eu-west-1",
"ap-northeast-2",
},
Tags: []string{
"foo",
"bar",
},
AlertSettings: alertSettings,
UseGlobalAlertSettings: false,
Request: checkly.Request{
Method: http.MethodGet,
URL: "http://example.com",
Headers: []checkly.KeyValue{
{
Key: "X-Test",
Value: "foo",
},
},
QueryParameters: []checkly.KeyValue{
{
Key: "query",
Value: "foo",
},
},
Assertions: []checkly.Assertion{
{
Source: checkly.StatusCode,
Comparison: checkly.Equals,
Target: "200",
},
},
Body: "",
BodyType: "NONE",
},
}
Now you can pass it to client.Create() to create a check. This returns the newly-created Check object, or an error if there was a problem:
check, err := client.Create(wantCheck)
For browser checks, the options are slightly different:
wantCheck := checkly.Check{
Name: "My Browser Check",
Type: checkly.TypeBrowser,
Frequency: 5,
Activated: true,
Muted: false,
ShouldFail: false,
DoubleCheck: false,
SSLCheck: true,
Locations: []string{"eu-west-1"},
AlertSettings: alertSettings,
Script: `const assert = require("chai").assert;
const puppeteer = require("puppeteer");
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto("https://example.com");
const title = await page.title();
assert.equal(title, "Example Site");
await browser.close();`,
EnvironmentVariables: []checkly.EnvironmentVariable{
{
Key: "HELLO",
Value: "Hello world",
},
},
Request: checkly.Request{
Method: http.MethodGet,
URL: "http://example.com",
},
}
Retrieving a check
client.Get(ID) finds an existing check by ID and returns a Check struct containing its details:
check, err := client.Get("87dd7a8d-f6fd-46c0-b73c-b35712f56d72")
fmt.Println(check.Name)
// Output: My Awesome Check
Updating a check
client.Update(ID, check) updates an existing check with the specified details. For example, to change the name of a check:
ID := "87dd7a8d-f6fd-46c0-b73c-b35712f56d72"
check, err := client.Get(ID)
check.Name = "My updated check name"
updatedCheck, err = client.Update(ID, check)
Deleting a check
Use client.Delete(ID) to delete a check by ID.
err := client.Delete("73d29ea2-6540-4bb5-967e-e07fa2c9465e")
Creating a new check group
Checkly checks can be combined into a group, so that you can configure default values for all the checks within it:
var wantGroup = checkly.Group{
Name: "test",
Activated: true,
Muted: false,
Tags: []string{"auto"},
Locations: []string{"eu-west-1"},
Concurrency: 3,
APICheckDefaults: checkly.APICheckDefaults{
BaseURL: "example.com/api/test",
Headers: []checkly.KeyValue{
{
Key: "X-Test",
Value: "foo",
},
},
QueryParameters: []checkly.KeyValue{
{
Key: "query",
Value: "foo",
},
},
Assertions: []checkly.Assertion{
{
Source: checkly.StatusCode,
Comparison: checkly.Equals,
Target: "200",
},
},
BasicAuth: checkly.BasicAuth{
Username: "user",
Password: "pass",
},
},
EnvironmentVariables: []checkly.EnvironmentVariable{
{
Key: "ENVTEST",
Value: "Hello world",
},
},
DoubleCheck: true,
UseGlobalAlertSettings: false,
AlertSettings: checkly.AlertSettings{
EscalationType: checkly.RunBased,
RunBasedEscalation: checkly.RunBasedEscalation{
FailedRunThreshold: 1,
},
TimeBasedEscalation: checkly.TimeBasedEscalation{
MinutesFailingThreshold: 5,
},
Reminders: checkly.Reminders{
Amount: 0,
Interval: 5,
},
SSLCertificates: checkly.SSLCertificates{
Enabled: true,
AlertThreshold: 30,
},
},
AlertChannelSubscriptions: []checkly.Subscription{
{
Activated: true,
},
},
LocalSetupScript: "setup-test",
LocalTearDownScript: "teardown-test",
}
group, err := client.CreateGroup(wantGroup)
A complete example program
You can see an example program which creates a Checkly check in the examples/demo folder.
Debugging
If things aren't working as you expect, you can assign an io.Writer to client.Debug to receive debug output. If client.Debug is non-nil, then all API requests and responses will be dumped to the specified writer (for example, os.Stderr).
Regardless of the debug setting, if a request fails with HTTP status 400 Bad Request), the full response will be dumped (to standard error if no debug writer is set):
client.Debug = os.Stderr
Example request and response dump:
POST /v1/checks HTTP/1.1
Host: api-test.checklyhq.com
User-Agent: Go-http-client/1.1
Content-Length: 1078
Authorization: Bearer XXX
Content-Type: application/json
Accept-Encoding: gzip
{"id":"","name":"test","checkType":"API","frequency":10,"activated":true,
"muted":false,"shouldFail":false,"locations":["eu-west-1"],
"degradedResponseTime":15000,"maxResponseTime":30000,"script":"foo",
"environmentVariables":[{"key":"ENVTEST","value":"Hello world","locked":false}],
"doubleCheck":true,"tags":["foo","bar"],"sslCheck":true,
"localSetupScript":"setitup","localTearDownScript":"tearitdown","alertSettings":
{"escalationType":"RUN_BASED","runBasedEscalation":{"failedRunThreshold":1},
"timeBasedEscalation":{"minutesFailingThreshold":5},"reminders":{"interval":5},
"sslCertificates":{"enabled":false,"alertThreshold":30}},
"useGlobalAlertSettings":false,"request":{"method":"GET","url":"https://example.
com","followRedirects":false,"body":"","bodyType":"NONE","headers":[
{"key":"X-Test","value":"foo","locked":false}],"queryParameters":[
{"key":"query","value":"foo","locked":false}],"assertions":[
{"edit":false,"order":0,"arrayIndex":0,"arraySelector":0,
"source":"STATUS_CODE","property":"","comparison":"EQUALS",
"target":"200"}],"basicAuth":{"username":"","password":""}}}
HTTP/1.1 201 Created
Transfer-Encoding: chunked
Cache-Control: no-cache
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Date: Thu, 28 May 2020 11:18:31 GMT
Server: Cowboy
Vary: origin,accept-encoding
Via: 1.1 vegur
4ea
{"name":"test","checkType":"API","frequency":10,"activated":true,"muted":false,
"shouldFail":false,"locations":["eu-west-1"],"degradedResponseTime":15000,
"maxResponseTime":30000,"script":"foo","environmentVariables":[{"key":"ENVTEST",
"value":"Hello world","locked":false}],"doubleCheck":true,"tags":["foo","bar"],
"sslCheck":true,"localSetupScript":"setitup","localTearDownScript":"tearitdown",
"alertSettings":{"escalationType":"RUN_BASED","runBasedEscalation":
{"failedRunThreshold":1},"timeBasedEscalation":{"minutesFailingThreshold":5},
"reminders":{"interval":5,"amount":0},"sslCertificates":{"enabled":false,
"alertThreshold":30}},"useGlobalAlertSettings":false,"request":{"method":"GET",
"url":"https://example.com","followRedirects":false,"body":"","bodyType":"NONE",
"headers":[{"key":"X-Test","value":"foo","locked":false}],"queryParameters":[
{"key":"query","value":"foo","locked":false}],"assertions":[
{"source":"STATUS_CODE","property":"","comparison":"EQUALS","target":"200"}],
"basicAuth":{"username":"","password":""}},"setupSnippetId":null,
"tearDownSnippetId":null,"groupId":null,"groupOrder":null,
"alertChannelSubscriptions":[{"activated":true,"alertChannelId":35}],
"created_at":"2020-05-28T11:18:31.280Z",
"id":"29815146-8ab5-492d-a092-9912c1ab8333"}
0
Bugs and feature requests
If you find a bug in the checkly client or library, please open an issue. Similarly, if you'd like a feature added or improved, let me know via an issue.
Not all the functionality of the Checkly API is implemented yet.
Pull requests welcome!
Documentation
¶
Index ¶
- Constants
- type APICheckDefaults
- type AlertChannel
- type AlertSettings
- type Assertion
- type BasicAuth
- type Check
- type Client
- func (c *Client) Create(check Check) (Check, error)
- func (c *Client) CreateGroup(group Group) (Group, error)
- func (c *Client) Delete(ID string) error
- func (c *Client) DeleteGroup(ID int64) error
- func (c *Client) Get(ID string) (Check, error)
- func (c *Client) GetGroup(ID int64) (Group, error)
- func (c *Client) MakeAPICall(method string, URL string, data []byte) (statusCode int, response string, err error)
- func (c *Client) Update(ID string, check Check) (Check, error)
- func (c *Client) UpdateGroup(ID int64, group Group) (Group, error)
- type EnvironmentVariable
- type Group
- type KeyValue
- type Reminders
- type Request
- type RunBasedEscalation
- type SSLCertificates
- type Subscription
- type TimeBasedEscalation
Constants ¶
const Contains = "CONTAINS"
Contains asserts that the source contains a specified value.
const Equals = "EQUALS"
Equals asserts that the source and target are equal.
const GreaterThan = "GREATER_THAN"
GreaterThan asserts that the source is greater than the target.
const Headers = "HEADERS"
Headers identifies the HTTP headers as an assertion source.
const IsEmpty = "IS_EMPTY"
IsEmpty asserts that the source is empty.
const JSONBody = "JSON_BODY"
JSONBody identifies the JSON body data as an assertion source.
const LessThan = "LESS_THAN"
LessThan asserts that the source is less than the target.
const NotContains = "NOT_CONTAINS"
NotContains asserts that the source does not contain a specified value.
const NotEmpty = "NOT_EMPTY"
NotEmpty asserts that the source is not empty.
const NotEquals = "NOT_EQUALS"
NotEquals asserts that the source and target are not equal.
const ResponseTime = "RESPONSE_TIME"
ResponseTime identifies the response time as an assertion source.
const RunBased = "RUN_BASED"
RunBased identifies a run-based escalation type, for use with an AlertSettings.
const StatusCode = "STATUS_CODE"
StatusCode identifies the HTTP status code as an assertion source.
const TextBody = "TEXT_BODY"
TextBody identifies the response body text as an assertion source.
const TimeBased = "TIME_BASED"
TimeBased identifies a time-based escalation type, for use with an AlertSettings.
const TypeAPI = "API"
TypeAPI is used to identify an API check.
const TypeBrowser = "BROWSER"
TypeBrowser is used to identify a browser check.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APICheckDefaults ¶ added in v0.4.0
type APICheckDefaults struct {
BaseURL string `json:"url"`
Headers []KeyValue `json:"headers"`
QueryParameters []KeyValue `json:"queryParameters"`
Assertions []Assertion `json:"assertions"`
BasicAuth BasicAuth `json:"basicAuth,omitempty"`
}
APICheckDefaults represents the default settings for API checks within a given group.
type AlertChannel ¶
type AlertChannel struct {
ID string `json:"id"`
Type string `json:"type,omitempty"`
Config map[string]interface{} `json:"config,omitempty"`
CreatedAt time.Time `json:"created_at,omitempty"`
UpdatedAt time.Time `json:"updated_at,omitempty"`
}
AlertChannel represents an alert channel and its subscribed checks. The API defines this data as read-only.
type AlertSettings ¶
type AlertSettings struct {
EscalationType string `json:"escalationType,omitempty"`
RunBasedEscalation RunBasedEscalation `json:"runBasedEscalation,omitempty"`
TimeBasedEscalation TimeBasedEscalation `json:"timeBasedEscalation,omitempty"`
Reminders Reminders `json:"reminders,omitempty"`
SSLCertificates SSLCertificates `json:"sslCertificates,omitempty"`
}
AlertSettings represents an alert configuration.
type Assertion ¶
type Assertion struct {
Edit bool `json:"edit"`
Order int `json:"order"`
ArrayIndex int `json:"arrayIndex"`
ArraySelector int `json:"arraySelector"`
Source string `json:"source"`
Property string `json:"property"`
Comparison string `json:"comparison"`
Target string `json:"target"`
}
Assertion represents an assertion about an API response, which will be verified as part of the check.
type Check ¶
type Check struct {
ID string `json:"id"`
Name string `json:"name"`
Type string `json:"checkType"`
Frequency int `json:"frequency"`
Activated bool `json:"activated"`
Muted bool `json:"muted"`
ShouldFail bool `json:"shouldFail"`
Locations []string `json:"locations"`
DegradedResponseTime int `json:"degradedResponseTime"`
MaxResponseTime int `json:"maxResponseTime"`
Script string `json:"script,omitempty"`
EnvironmentVariables []EnvironmentVariable `json:"environmentVariables"`
DoubleCheck bool `json:"doubleCheck"`
Tags []string `json:"tags,omitempty"`
SSLCheck bool `json:"sslCheck"`
SetupSnippetID int64 `json:"setupSnippetId,omitempty"`
TearDownSnippetID int64 `json:"tearDownSnippetId,omitempty"`
LocalSetupScript string `json:"localSetupScript,omitempty"`
LocalTearDownScript string `json:"localTearDownScript,omitempty"`
AlertSettings AlertSettings `json:"alertSettings,omitempty"`
UseGlobalAlertSettings bool `json:"useGlobalAlertSettings"`
Request Request `json:"request"`
GroupID int64 `json:"groupId,omitempty"`
GroupOrder int `json:"groupOrder,omitempty"`
}
Check represents the parameters for an existing check.
type Client ¶
type Client struct {
URL string
HTTPClient *http.Client
Debug io.Writer
// contains filtered or unexported fields
}
Client represents a Checkly client. If the Debug field is set to an io.Writer (for example os.Stdout), then the client will dump API requests and responses to it. To use a non-default HTTP client (for example, for testing, or to set a timeout), assign to the HTTPClient field. To set a non-default URL (for example, for testing), assign to the URL field.
func (*Client) Create ¶
Create creates a new check with the specified details. It returns the newly-created check, or an error.
func (*Client) CreateGroup ¶ added in v0.4.0
CreateGroup creates a new check group with the specified details. It returns the newly-created group, or an error.
func (*Client) Delete ¶
Delete deletes the check with the specified ID. It returns a non-nil error if the request failed.
func (*Client) DeleteGroup ¶ added in v0.4.0
DeleteGroup deletes the check group with the specified ID. It returns a non-nil error if the request failed.
func (*Client) Get ¶
Get takes the ID of an existing check, and returns the check parameters, or an error.
func (*Client) GetGroup ¶ added in v0.4.0
GetGroup takes the ID of an existing check group, and returns the corresponding group, or an error.
func (*Client) MakeAPICall ¶
func (c *Client) MakeAPICall(method string, URL string, data []byte) (statusCode int, response string, err error)
MakeAPICall calls the Checkly API with the specified URL and data, and returns the HTTP status code and string data of the response.
type EnvironmentVariable ¶
type EnvironmentVariable struct {
Key string `json:"key"`
Value string `json:"value"`
Locked bool `json:"locked"`
}
EnvironmentVariable represents a key-value pair for setting environment values during check execution.
type Group ¶ added in v0.4.0
type Group struct {
ID int64 `json:"id,omitempty"`
Name string `json:"name"`
Activated bool `json:"activated"`
Muted bool `json:"muted"`
Tags []string `json:"tags,omitempty"`
Locations []string `json:"locations"`
Concurrency int `json:"concurrency"`
APICheckDefaults APICheckDefaults `json:"apiCheckDefaults"`
EnvironmentVariables []EnvironmentVariable `json:"environmentVariables"`
DoubleCheck bool `json:"doubleCheck"`
UseGlobalAlertSettings bool `json:"useGlobalAlertSettings"`
AlertSettings AlertSettings `json:"alertSettings,omitempty"`
AlertChannelSubscriptions []Subscription `json:"alertChannelSubscriptions,omitempty"`
SetupSnippetID int64 `json:"setupSnippetId,omitempty"`
TearDownSnippetID int64 `json:"tearDownSnippetId,omitempty"`
LocalSetupScript string `json:"localSetupScript,omitempty"`
LocalTearDownScript string `json:"localTearDownScript,omitempty"`
}
Group represents a check group.
type KeyValue ¶
type KeyValue struct {
Key string `json:"key"`
Value string `json:"value"`
Locked bool `json:"locked"`
}
KeyValue represents a key-value pair, for example a request header setting, or a query parameter.
type Reminders ¶
type Reminders struct {
Amount int `json:"amount,omitempty"`
Interval int `json:"interval,omitempty"`
}
Reminders represents the number of reminders to send after an alert notification, and the time interval between them.
type Request ¶
type Request struct {
Method string `json:"method"`
URL string `json:"url"`
FollowRedirects bool `json:"followRedirects"`
Body string `json:"body"`
BodyType string `json:"bodyType,omitempty"`
Headers []KeyValue `json:"headers"`
QueryParameters []KeyValue `json:"queryParameters"`
Assertions []Assertion `json:"assertions"`
BasicAuth BasicAuth `json:"basicAuth,omitempty"`
}
Request represents the parameters for the request made by the check.
type RunBasedEscalation ¶
type RunBasedEscalation struct {
FailedRunThreshold int `json:"failedRunThreshold,omitempty"`
}
RunBasedEscalation represents an alert escalation based on a number of failed check runs.
type SSLCertificates ¶
type SSLCertificates struct {
Enabled bool `json:"enabled"`
AlertThreshold int `json:"alertThreshold"`
}
SSLCertificates represents alert settings for expiring SSL certificates.
type Subscription ¶
type Subscription struct {
ID string `json:"id,omitempty"`
CheckID string `json:"checkId,omitempty"`
AlertChannelID int64 `json:"alertChannelId,omitempty"`
Activated bool `json:"activated"`
}
Subscription represents a subscription to an alert channel. The API defines this data as read-only.
type TimeBasedEscalation ¶
type TimeBasedEscalation struct {
MinutesFailingThreshold int `json:"minutesFailingThreshold,omitempty"`
}
TimeBasedEscalation represents an alert escalation based on the number of minutes after a check first starts failing.
Source Files