Checkly Monitoring

• Refer to docs for Checkly CLI v6.0.0 and above.
• Check the Checkly CLI output to figure out into which folder the setup was generated.
• Use the Checkly CLI reference documentation.
• Use the Checkly construct reference documentation.
• Import and / or require any constructs you need in your code, such as ApiCheck, BrowserCheck, or PlaywrightCheck from the checkly/constructs package.
• Always ground generated code and CLI commands against the official documentation and examples in this file.

Installing the Checkly CLI

• ALWAYS use npm create checkly@latest.
• NEVER make up commands that do not exist.

Project Structure

• checkly.config.ts – Mandatory global project and CLI configuration. We recommend using TypeScript.
• *.check.ts|js – TS / JS files that define the checks.
• *.spec.ts|js – TS / JS files that contain Playwright code for Browser and MultiStep checks.
• src/__checks__ – Default directory where all your checks are stored. Use this directory if it already exists, otherwise create a new directory for your checks.
• 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.

Reference: https://www.checklyhq.com/docs/constructs/project/

import { defineConfig } from 'checkly'
import { Frequency } from 'checkly/constructs'

export default defineConfig({
  projectName: "Production Monitoring Suite",
  logicalId: "prod-monitoring-2025",
  repoUrl: "https://github.com/acme/monitoring",
  checks: {
    activated: true,
    muted: false,
    runtimeId: "2025.04",
    frequency: Frequency.EVERY_10M,
    locations: ["us-east-1", "eu-west-1", "ap-southeast-1"],
    tags: ["production", "critical"],
    checkMatch: "**/__checks__/*.check.ts",
    ignoreDirectoriesMatch: ["node_modules/**", "dist/**"],
    playwrightConfig: {
      use: {
        baseURL: "https://app.example.com",
      },
    },
    browserChecks: {
      frequency: Frequency.EVERY_30M,
      testMatch: "**/__tests__/*.spec.ts",
    },
  },
  cli: {
    runLocation: "eu-west-1",
    privateRunLocation: "private-dc1",
    retries: 2,
  },
})

Check and Monitor Constructs

API Check

• Import the ApiCheck construct from checkly/constructs.
• When adding assertions, always use AssertionBuilder class for API Checks.
• When referencing environment variables always use the handlebar syntax {{MY_ENV_VAR}}.
• When referencing secrets always use the handlebar syntax {{MY_SECRET}}.
• If endpoints require authentication ask the user which authentication method to use and then generate a setupScript to authenticate the given requests.
• Referenced setupScript.ts and teardownScript.ts for API checks must be plain ts files and not export anything.
• Check in the code if API endpoints require authentication.

Reference: https://www.checklyhq.com/docs/constructs/api-check/

import { AlertEscalationBuilder, ApiCheck, Frequency, RetryStrategyBuilder } from 'checkly/constructs'

new ApiCheck('example-api-check', {
  name: 'Example API Check',
  request: {
    url: 'https://api.example.com/v1/products',
    method: 'GET',
    ipFamily: 'IPv4',
  },
  setupScript: {
    entrypoint: './setup-script.ts',
  },
  tearDownScript: {
    entrypoint: './teardown-script.ts',
  },
  degradedResponseTime: 5000,
  maxResponseTime: 20000,
  activated: true,
  muted: false,
  shouldFail: false,
  locations: [
    'eu-central-1',
    'eu-west-2',
  ],
  frequency: Frequency.EVERY_5M,
  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
    amount: 0,
    interval: 5,
  }, {
    enabled: false,
    percentage: 10,
  }),
  retryStrategy: RetryStrategyBuilder.linearStrategy({
    baseBackoffSeconds: 60,
    maxRetries: 2,
    maxDurationSeconds: 600,
    sameRegion: true,
  }),
  runParallel: true,
})

Authentication Setup Scripts for API Checks

• Setup scripts should be flat scripts, no functions, no exports, they will be executed straight by Checkly.
• Use axios for making HTTP requests.
• Read the input credentials from env variables using process.env.
• Pass auth tokens to the request object using request.headers['key'] = AUTH_TOKEN_VALUE.

Browser Check

• Import the BrowserCheck construct from checkly/constructs.
• Generate a separate .spec.ts file for the Playwright code referenced in the BrowserCheck construct.
• Use the code.entrypoint property to specify the path to your Playwright test file.

Reference: https://www.checklyhq.com/docs/constructs/browser-check/

import { AlertEscalationBuilder, BrowserCheck, Frequency, RetryStrategyBuilder } from 'checkly/constructs'

new BrowserCheck('example-browser-check', {
  name: 'Example Browser Check',
  code: {
    entrypoint: './example-browser-check.spec.ts',
  },
  activated: false,
  muted: false,
  shouldFail: false,
  locations: [
    'eu-central-1',
    'eu-west-2',
  ],
  frequency: Frequency.EVERY_10M,
  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
    amount: 0,
    interval: 5,
  }, {
    enabled: false,
    percentage: 10,
  }),
  retryStrategy: RetryStrategyBuilder.linearStrategy({
    baseBackoffSeconds: 60,
    maxRetries: 2,
    maxDurationSeconds: 600,
    sameRegion: true,
  }),
  runParallel: true,
})

Playwright Check Suite

• Import the PlaywrightCheck construct from checkly/constructs.
• use pwProjects if your tasked to reuse a Playwright project.

Reference: https://www.checklyhq.com/docs/constructs/playwright-check/

import { PlaywrightCheck } from "checkly/constructs"

const playwrightChecks = new PlaywrightCheck("multi-browser-check", {
  name: "Multi-browser check suite",
  playwrightConfigPath: "./playwright.config.ts",
  // Playwright Check Suites support all browsers
  // defined in your `playwright.config`
  pwProjects: ["chromium", "firefox", "webkit"],
});

MultiStep Check

• Import the MultiStepCheck construct from checkly/constructs.
• Generate a separate .spec.ts file for the Playwright code referenced in the MultiStepCheck construct.
• Use the code.entrypoint property to specify the path to your Playwright test file.

Reference: https://www.checklyhq.com/docs/constructs/multistep-check/

import { AlertEscalationBuilder, Frequency, MultiStepCheck, RetryStrategyBuilder } from 'checkly/constructs'

new MultiStepCheck('example-multi-step-check', {
  name: 'Example Multistep Check',
  code: {
    entrypoint: './example-multistep-check.spec.ts',
  },
  activated: true,
  muted: false,
  shouldFail: false,
  locations: [
    'eu-central-1',
    'eu-west-2',
  ],
  frequency: Frequency.EVERY_1H,
  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
    amount: 0,
    interval: 5,
  }, {
    enabled: false,
    percentage: 10,
  }),
  retryStrategy: RetryStrategyBuilder.noRetries(),
  runParallel: true,
})

TCP Monitor

• Import the TcpMonitor construct from checkly/constructs.
• When adding assertions, always use TcpAssertionBuilder class for TCP monitors.

Reference: https://www.checklyhq.com/docs/constructs/tcp-monitor/

import { AlertEscalationBuilder, Frequency, RetryStrategyBuilder, TcpAssertionBuilder, TcpMonitor } from 'checkly/constructs'

new TcpMonitor('example-tcp-monitor', {
  name: 'Example TCP Monitor',
  request: {
    hostname: 'tcp.example.com',
    port: 4242,
    ipFamily: 'IPv4',
    assertions: [
      TcpAssertionBuilder.responseTime().lessThan(200),
      TcpAssertionBuilder.responseData().isEmpty(),
    ],
  },
  degradedResponseTime: 5000,
  maxResponseTime: 5000,
  activated: true,
  muted: false,
  shouldFail: false,
  locations: [
    'eu-central-1',
    'eu-west-2',
  ],
  frequency: Frequency.EVERY_1H,
  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
    amount: 0,
    interval: 5,
  }, {
    enabled: false,
    percentage: 10,
  }),
  retryStrategy: RetryStrategyBuilder.linearStrategy({
    baseBackoffSeconds: 60,
    maxRetries: 2,
    maxDurationSeconds: 600,
    sameRegion: true,
  }),
  runParallel: true,
})

URL Monitor

• Import the UrlMonitor construct from checkly/constructs.
• When adding assertions, always use UrlAssertionBuilder.

Reference: https://www.checklyhq.com/docs/constructs/url-monitor/

import { AlertEscalationBuilder, Frequency, RetryStrategyBuilder, UrlAssertionBuilder, UrlMonitor } from 'checkly/constructs'

new UrlMonitor('example-url-monitor', {
  name: 'Example URL Monitor',
  request: {
    url: 'https://example.com',
    ipFamily: 'IPv4',
    assertions: [
      UrlAssertionBuilder.statusCode().equals(200),
    ],
  },
  degradedResponseTime: 5000,
  maxResponseTime: 20000,
  activated: true,
  muted: false,
  shouldFail: false,
  locations: [
    'eu-central-1',
    'eu-west-2',
  ],
  frequency: Frequency.EVERY_5M,
  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
    amount: 0,
    interval: 5,
  }, {
    enabled: false,
    percentage: 10,
  }),
  retryStrategy: RetryStrategyBuilder.linearStrategy({
    baseBackoffSeconds: 60,
    maxRetries: 2,
    maxDurationSeconds: 600,
    sameRegion: true,
  }),
  runParallel: true,
})

DNS Monitor

• Import the DnsMonitor construct from checkly/constructs.
• Reference the docs for DNS monitors before generating any code.
• When adding assertions, always use DnsAssertionBuilder class.

Reference: https://www.checklyhq.com/docs/constructs/dns-monitor/

import { AlertEscalationBuilder, DnsAssertionBuilder, DnsMonitor, Frequency, RetryStrategyBuilder } from 'checkly/constructs'

new DnsMonitor('example-dns-monitor', {
  name: 'Example DNS Monitor',
  request: {
    recordType: 'AAAA',
    query: 'welcome.checklyhq.com',
    assertions: [
      DnsAssertionBuilder.responseCode().equals('NOERROR'),
    ],
  },
  degradedResponseTime: 500,
  maxResponseTime: 1000,
  activated: true,
  muted: false,
  shouldFail: false,
  locations: [
    'eu-central-1',
    'eu-north-1',
  ],
  frequency: Frequency.EVERY_10M,
  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
    amount: 0,
    interval: 5,
  }, {
    enabled: false,
    percentage: 10,
  }),
  retryStrategy: RetryStrategyBuilder.noRetries(),
  runParallel: false,
})

Heartbeat Monitor

• Import the HeartbeatMonitor construct from checkly/constructs.

Reference: https://www.checklyhq.com/docs/constructs/heartbeat-monitor/

import { AlertEscalationBuilder, Frequency, HeartbeatMonitor, RetryStrategyBuilder } from 'checkly/constructs'

new HeartbeatMonitor('example-heartbeat-monitor', {
  name: 'Example Heartbeat Monitor',
  period: 1,
  periodUnit: 'hours',
  grace: 30,
  graceUnit: 'minutes',
  activated: true,
  muted: false,
  shouldFail: false,
  frequency: Frequency.EVERY_10S,
  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
    amount: 0,
    interval: 5,
  }, {
    enabled: false,
    percentage: 10,
  }),
  retryStrategy: RetryStrategyBuilder.linearStrategy({
    baseBackoffSeconds: 60,
    maxRetries: 2,
    maxDurationSeconds: 600,
    sameRegion: true,
  }),
  runParallel: true,
})

Check Group

• Import the CheckGroupV2 construct from checkly/constructs.
• Check Groups are used to group checks together for easier management and organization.
• Checks are added to Check Groups by referencing the group in the group property of a check.

Reference: https://www.checklyhq.com/docs/constructs/check-group/

import { CheckGroupV2 } from 'checkly/constructs'

export const exampleGroup = new CheckGroupV2('example-group', {
  name: 'Example Group',
})

Alert Channel Constructs

• Alert channels are used to send notifications when checks and monitors fail or recover.
• Alert channels are added to checks, monitors, and check groups constructs by adding them to the alertChannels array property.

Here are some examples of how to create different types of alert channels. All alert are described in the Checkly docs.

Email Alert Channel

Reference: https://www.checklyhq.com/docs/constructs/email-alert-channel/

import { EmailAlertChannel } from 'checkly/constructs'

export const testEmailAlert = new EmailAlertChannel('example-email-alert-channel', {
  address: 'test@example.com',
  sslExpiry: true,
})

Phone Call Alert Channel

Reference: https://www.checklyhq.com/docs/constructs/phone-call-alert-channel/

import { PhoneCallAlertChannel } from 'checkly/constructs'

export const testUserPhoneCallAlert = new PhoneCallAlertChannel('example-call-alert-channel', {
  name: 'Test User',
  phoneNumber: '+311234567890',
})

Slack Alert Channel

Reference: https://www.checklyhq.com/docs/constructs/slack-alert-channel/

import { SlackAlertChannel } from 'checkly/constructs'

export const generalSlackAlert = new SlackAlertChannel('example-slack-alert-channel', {
  url: 'https://hooks.slack.com/services/TK123456789123/12345/123456789',
  channel: '#general',
})

Supporting Constructs

Status Page

• Import the StatusPage construct from checkly/constructs.
• Status pages are used to display the status of your services to your users.
• A Status Page consists of cards which include Status Page Services.

Reference: https://www.checklyhq.com/docs/constructs/status-page/

import { StatusPage } from 'checkly/constructs'
import { exampleService } from './services/example-service.check'

new StatusPage('example-status-page', {
  name: 'Example Status Page',
  url: 'example-status-page',
  cards: [
    {
      name: 'Example service',
      services: [
        exampleService,
      ],
    },
  ],
  customDomain: 'status.example.com',
  defaultTheme: 'AUTO',
})

Status Page Service

• Import the StatusPageService construct from checkly/constructs.
• Status Page Services are used to represent individual services on a Status Page.

Reference: https://www.checklyhq.com/docs/constructs/status-page-service/

import { StatusPageService } from 'checkly/constructs'

export const exampleService = new StatusPageService('example-status-page-service', {
  name: 'Example Service',
})

Dashboard

• Import the Dashboard construct from checkly/constructs.
• Dashboards are used to display the results of your checks on screens external to Checkly.

Reference: https://www.checklyhq.com/docs/constructs/dashboard/

import { Dashboard } from 'checkly/constructs'

new Dashboard('example-dashboard', {
  tags: [
    'app:webshop',
  ],
  customUrl: 'example-dashboard',
  customDomain: 'dash.example.com',
  header: 'Example Dashboard',
  description: 'Example dashboard',
  width: 'FULL',
  refreshRate: 60,
  paginate: true,
  paginationRate: 60,
  checksPerPage: 15,
  useTagsAndOperator: false,
  hideTags: false,
  enableIncidents: false,
  expandChecks: false,
  showHeader: true,
  isPrivate: false,
  showP95: true,
  showP99: true,
})

Maintenance Window

• Import the MaintenanceWindow construct from checkly/constructs.
• Maintenance windows are used to pause checks during maintenance periods so no alerts are sent.
• Checks are referenced by their tags in the tags property.

Reference: https://www.checklyhq.com/docs/constructs/maintenance-window/

import { MaintenanceWindow } from 'checkly/constructs'

new MaintenanceWindow('example-maintenance-window', {
  name: 'Example Maintenance Window',
  tags: [
    'app:webshop',
  ],
  startsAt: new Date('2025-07-01T09:00:00.000Z'),
  endsAt: new Date('2025-07-01T10:00:00.000Z'),
  repeatInterval: 1,
  repeatUnit: 'WEEK',
  repeatEndsAt: new Date('2025-08-01T00:00:00.000Z'),
})

Private Location

• Import the PrivateLocation construct from checkly/constructs.
• Private locations are used to run checks from your own infrastructure with the Checkly Agent, an OCI compatible container.

Reference: https://www.checklyhq.com/docs/constructs/private-location/

import { PrivateLocation } from 'checkly/constructs'

export const examplePrivateLocation = new PrivateLocation('example-private-location', {
  name: 'Example Private Location',
  slugName: 'example-private-location',
  icon: 'location',
})

Testing and Debugging

• Test checks using npx checkly test command pass env variables using -e param, use --record to persist results and --verbose to be able to see all errors