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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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/

typescript

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

monitoring

NPX Install

Tags

SKILL.md Content

Checkly Monitoring

Installing the Checkly CLI

Project Structure

Check and Monitor Constructs

API Check

Authentication Setup Scripts for API Checks

Browser Check

Playwright Check Suite

MultiStep Check

TCP Monitor

URL Monitor

DNS Monitor

Heartbeat Monitor

Check Group

Alert Channel Constructs

Email Alert Channel

Phone Call Alert Channel

Slack Alert Channel

Supporting Constructs

Status Page

Status Page Service

Dashboard

Maintenance Window

Private Location

Testing and Debugging