Skip to content

overview.mdx

Latest commit

 

History

History
162 lines (122 loc) · 6.12 KB

overview.mdx

File metadata and controls

162 lines (122 loc) · 6.12 KB
title Using Checkly CLI Constructs
description Build monitoring infrastructure using JavaScript/TypeScript and the Checkly CLI
sidebarTitle Overview

import JsTsNote from '/snippets/js-ts-note.mdx'; import ChecklyConfigCodeBlock from '/snippets/checkly-config-example-code-block.mdx';

Every resource you create using the Checkly CLI is represented by a "construct": it's a class you import from checkly/constructs, for instance an ApiCheck or EmailAlertChannel. A construct is the "as-code" representation of the eventual resource created / deleted / updated on the Checkly cloud once you run npx checkly deploy.

You must install the [Checkly CLI](/cli/overview) before you can use constructs.

Constructs are JavaScript/TypeScript classes that represent your all monitoring resources. Import them from checkly/constructs to create checks, alert channels, and other resources in code.

import { ApiCheck, AssertionBuilder } from 'checkly/constructs'

new ApiCheck('api-health-check', {
  name: 'API Health Check',
  request: {
    url: 'https://danube-web.shop/api/books',
    method: 'GET',
    assertions: [
      AssertionBuilder.statusCode().equals(200),
    ],
  },
})
const { ApiCheck, AssertionBuilder } = require('checkly/constructs')

new ApiCheck('api-health-check', {
  name: 'API Health Check',
  request: {
    url: 'https://danube-web.shop/api/books',
    method: 'GET',
    assertions: [
      AssertionBuilder.statusCode().equals(200),
    ],
  },
})

Test this API check with npx checkly test and transform it to production monitoring with npx checkly deploy.

Project Structure

  • checkly.config.ts - Mandatory global project and CLI configuration. We recommend using TypeScript.
  • src/__checks__/* - TS/JS files defining your checks and other resources.
  • package.json - Standard NPM project manifest.

Here is an example directory tree of what that would look like:

.
|-- checkly.config.ts
|-- package.json
`-- src
    `-- __checks__
      |-- alert-channels.ts
      |-- api-check.check.ts
      `-- homepage.spec.ts

The checkly.config.ts at the root of your project defines a range of defaults for all your checks.

Project Configuration

As your project grows, you will want to override these defaults for specific checks or check groups. The recommended way to tackle this is using a mix of global and local configuration.

Global Configuration

As mentioned, your global checkly.config.ts holds a set of defaults for your project, checks, and some CLI commands. Use defineConfig to configure your Checkly project.

Find a full reference of all project properties in the Project construct section.

Local Configuration

Override any of the checks global configuration settings at the individual check level.

import { ApiCheck, AssertionBuilder, Frequency } from 'checkly/constructs'

new ApiCheck('books-api', {
  name: 'Books API',
  locations: ['ap-south-1'], // overrides the locations property
  frequency: Frequency.EVERY_30M, // overrides the frequency property
  request: {
    method: 'GET',
    url: 'https://danube-web.shop/api/books',
    assertions: [AssertionBuilder.statusCode().equals(200)],
  },
})
const { ApiCheck, AssertionBuilder, Frequency } = require('checkly/constructs')

new ApiCheck('books-api', {
  name: 'Books API',
  locations: ['ap-south-1'], // overrides the locations property
  frequency: Frequency.EVERY_30M, // overrides the frequency property
  request: {
    method: 'GET',
    url: 'https://danube-web.shop/api/books',
    assertions: [AssertionBuilder.statusCode().equals(200)],
  },
})

Find a full reference of all check properties in the ApiCheck construct or BrowserCheck construct section.

Logical IDs

Assigning a logicalId is crucial when creating a construct. Remember the following rules when creating and updating constructs:

  1. Every construct needs to have a logicalId. This is the first argument when instantiating a class, i.e.
const check  = new ApiCheck('my-logical-id', { name: 'My API check' })
  1. Every logicalId needs to be unique within the scope of a Project.
  2. A Project also has a logicalId. This needs to be unique within the scope of the Checkly account.
  3. A logicalId can be any string up to 255 characters in length.
  4. There is no hard limit on the amount of Projects you can have in your Checkly account.

Behind the scenes, we use the logicalId to create a graph of your resources so we know what to persist, update and remove from our database. Changing the logicalId on an existing resource in your code base will tell the Checkly backend that a resource was removed and a new resource was created.

When using the Checkly CLI to manage multiple projects and repositories, each project's logicalId should be unique within the Checkly account. The project's logicalId is used during the Checkly CLI commands to detect exactly which project is being used. If multiple projects are using the same project logicalId, deploying one project will delete the checks that were deployed by another project. The project logicalId can be configured in the project's global configuration.

When changing the logical ID of a project you will keep all resources on your Checkly account, unless you run [`npx checkly destroy`](/cli/monitoring/checkly-destroy/) to remove the old project.

Programming with Constructs

All resources you can create and manage using the Checkly CLI are derived from "constructs". These constructs are just TypeScript classes.

You can use standard JS/TS programming to use these constructs to create the monitoring setup of your choice. Loops, variables, if-statements, file imports, extensions etc. Here are some examples.