diff --git a/packages/cli/scripts/prepare-ai-context.ts b/packages/cli/scripts/prepare-ai-context.ts index 91190bc0e..9f59ab95b 100644 --- a/packages/cli/scripts/prepare-ai-context.ts +++ b/packages/cli/scripts/prepare-ai-context.ts @@ -1,21 +1,30 @@ import { mkdir, readFile, writeFile } from 'fs/promises' import { join } from 'path' -import { EXAMPLE_CONFIGS } from '../src/ai-context/context' +import { EXAMPLE_CONFIGS, REFERENCES } from '../src/ai-context/context' const EXAMPLES_DIR = join(__dirname, '../gen/') -const CONTEXT_TEMPLATE_PATH = join( - __dirname, - '../src/ai-context/checkly.context.template.md', -) +const AI_CONTEXT_DIR = join(__dirname, '../src/ai-context') const RULES_OUTPUT_DIR = join(__dirname, '../dist/ai-context') const SKILL_OUTPUT_DIR = join(__dirname, '../dist/ai-context/skills/monitoring') -const README_PATH = join(__dirname, '../src/ai-context/README.md') +const REFERENCES_OUTPUT_DIR = join(SKILL_OUTPUT_DIR, 'references') function stripYamlFrontmatter (content: string): string { const frontmatterRegex = /^---\r?\n[\s\S]*?\r?\n---\r?\n+/ return content.replace(frontmatterRegex, '') } +// Demote headings by two levels (# -> ###, ## -> ####) to maintain proper +// heading hierarchy when reference docs are concatenated after the header. +// The header has "# Checkly Monitoring" and "## ..." sections, so reference +// content needs to start at ### to avoid multiple H1s and broken structure. +function demoteHeadings (content: string): string { + return content.replace(/^(#+)/gm, '##$1') +} + +function normalizeBlankLines (content: string): string { + return content.replace(/\n{3,}/g, '\n\n') +} + async function writeOutput (content: string, dir: string, filename: string): Promise { await mkdir(dir, { recursive: true }) const outputPath = join(dir, filename) @@ -24,40 +33,10 @@ async function writeOutput (content: string, dir: string, filename: string): Pro console.log(`✅ Wrote ${outputPath}`) } -async function prepareContext () { - try { - // eslint-disable-next-line no-console - console.log('📝 Preparing AI context...') - - let content = await readFile(CONTEXT_TEMPLATE_PATH, 'utf8') - const examples = await readExampleCode() - - for (const example of examples) { - content = content.replace(example.templateString, example.code) - } - - await writeOutput(content, SKILL_OUTPUT_DIR, 'SKILL.md') - await writeOutput( - stripYamlFrontmatter(content), - RULES_OUTPUT_DIR, - 'checkly.rules.md', - ) +async function readExampleCode (): Promise> { + const examples = new Map() - const readme = await readFile(README_PATH, 'utf8') - await writeOutput(readme, SKILL_OUTPUT_DIR, 'README.md') - } catch (error) { - // eslint-disable-next-line no-console - console.error('❌ Failed to prepare AI context:', error) - process.exit(1) - } -} - -async function readExampleCode (): Promise< - { templateString: string, code: string }[] -> { - const examples: { templateString: string, code: string }[] = [] - - for (const config of Object.values(EXAMPLE_CONFIGS)) { + for (const [key, config] of Object.entries(EXAMPLE_CONFIGS)) { let code: string | undefined if (config.exampleConfig) { @@ -69,21 +48,84 @@ async function readExampleCode (): Promise< } catch { // eslint-disable-next-line no-console console.warn( - `Warning: Could not read example for ${config.templateString} from ${filePath}. It might not exist or be accessible.`, + `Warning: Could not read example for ${key} from ${filePath}. It might not exist or be accessible.`, ) } } if (code) { const wrappedCode = `**Reference:** ${config.reference}\n\n\`\`\`typescript\n${code}\`\`\`` - examples.push({ - templateString: config.templateString, - code: wrappedCode, - }) + examples.set(config.templateString, wrappedCode) } } return examples } +function replaceExamples (content: string, examples: Map): string { + let result = content + for (const [templateString, code] of examples) { + result = result.replaceAll(templateString, code) + } + return result +} + +function generateReferenceLinks (): string { + return REFERENCES.map( + ref => `- [${ref.linkText}](references/${ref.id}.md) - ${ref.description}`, + ).join('\n') +} + +async function prepareContext () { + try { + // eslint-disable-next-line no-console + console.log('📝 Preparing AI context...') + + const examples = await readExampleCode() + + // Read source files + const header = await readFile(join(AI_CONTEXT_DIR, 'skill-header.md'), 'utf8') + const footer = await readFile(join(AI_CONTEXT_DIR, 'skill-footer.md'), 'utf8') + + // Process reference files and collect their content + const referenceContents: string[] = [] + + for (const ref of REFERENCES) { + const refContent = await readFile( + join(AI_CONTEXT_DIR, 'references', `${ref.id}.md`), + 'utf8', + ) + const processedRefContent = replaceExamples(refContent, examples) + referenceContents.push(processedRefContent) + + // Write reference file to skill output + await writeOutput(processedRefContent, REFERENCES_OUTPUT_DIR, `${ref.id}.md`) + } + + // Generate SKILL.md (header with reference links + footer) + const headerWithLinks = header.replace('', generateReferenceLinks()) + const skillContent = replaceExamples(headerWithLinks, examples) + '\n' + footer + await writeOutput(skillContent, SKILL_OUTPUT_DIR, 'SKILL.md') + + // Generate checkly.rules.md (header + all references concatenated + footer) + const demotedReferences = referenceContents.map(demoteHeadings).join('\n\n') + const rulesContent = normalizeBlankLines(stripYamlFrontmatter( + replaceExamples(header.replace('', ''), examples) + + '\n' + + demotedReferences + + '\n\n' + + footer, + )) + await writeOutput(rulesContent, RULES_OUTPUT_DIR, 'checkly.rules.md') + + // Copy README + const readme = await readFile(join(AI_CONTEXT_DIR, 'README.md'), 'utf8') + await writeOutput(readme, SKILL_OUTPUT_DIR, 'README.md') + } catch (error) { + // eslint-disable-next-line no-console + console.error('❌ Failed to prepare AI context:', error) + process.exit(1) + } +} + prepareContext() diff --git a/packages/cli/src/ai-context/README.md b/packages/cli/src/ai-context/README.md index ab9e48119..a00a1a750 100644 --- a/packages/cli/src/ai-context/README.md +++ b/packages/cli/src/ai-context/README.md @@ -8,7 +8,16 @@ This directory contains the agent skill for creating and managing end-to-end tes skills/ └── monitoring/ ├── README.md # Documentation about the skill - └── SKILL.md # Main skill instructions + ├── SKILL.md # Main skill instructions + └── references/ # Detailed construct documentation + ├── api-checks.md + ├── browser-checks.md + ├── playwright-checks.md + ├── multistep-checks.md + ├── monitors.md + ├── check-groups.md + ├── alert-channels.md + └── supporting-constructs.md ``` ## What is an Agent Skill? @@ -27,13 +36,15 @@ Agent Skills are a standardized format for giving AI agents specialized knowledg AI agents can load this skill to gain expertise in Checkly monitoring. The skill follows the [Agent Skills specification](https://agentskills.io) with: - **SKILL.md**: Core instructions loaded when the skill is activated +- **references/**: Detailed documentation loaded on demand ## Progressive Disclosure The skill is structured for efficient context usage: 1. **Metadata** (~80 tokens): Name and description in frontmatter -2. **Core Instructions** (~4.5K tokens): Main SKILL.md content with construct examples +2. **Core Instructions** (~1K tokens): Main SKILL.md content with links to references +3. **References** (loaded on demand): Detailed construct documentation with examples Agents load what they need for each task. diff --git a/packages/cli/src/ai-context/checkly.context.template.md b/packages/cli/src/ai-context/checkly.context.template.md deleted file mode 100644 index 559c7aba1..000000000 --- a/packages/cli/src/ai-context/checkly.context.template.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -name: monitoring -description: Create and manage monitoring checks using the Checkly CLI. Use when working with API checks, browser checks, URL monitors, ICMP monitors, Playwright checks, heartbeat monitors, alert channels, dashboards, or status pages. -allowed-tools: Bash(npx:checkly:*) Bash(npm:create:checkly@latest) -metadata: - author: checkly ---- - -# 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](https://www.checklyhq.com/docs/cli/overview/). -- Use the [Checkly construct reference documentation](https://www.checklyhq.com/docs/constructs/overview/). -- 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. - -// INSERT CHECKLY CONFIG EXAMPLE HERE // - -## 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. - -// INSERT API CHECK EXAMPLE HERE // - -#### 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. - -// INSERT BROWSER CHECK EXAMPLE HERE // - -### Playwright Check Suite - -- Import the `PlaywrightCheck` construct from `checkly/constructs`. -- use `pwProjects` if your tasked to reuse a Playwright project. - -// INSERT PLAYWRIGHT CHECK EXAMPLE HERE // - -### 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. - -// INSERT MULTISTEP CHECK EXAMPLE HERE // - -### TCP Monitor - -- Import the `TcpMonitor` construct from `checkly/constructs`. -- When adding `assertions`, always use `TcpAssertionBuilder` class for TCP monitors. - -// INSERT TCP MONITOR EXAMPLE HERE // - -### URL Monitor - -- Import the `UrlMonitor` construct from `checkly/constructs`. -- When adding `assertions`, always use `UrlAssertionBuilder`. - -// INSERT URL MONITOR EXAMPLE HERE // - -### DNS Monitor - -- Import the `DnsMonitor` construct from `checkly/constructs`. -- Reference [the docs for DNS monitors](https://www.checklyhq.com/docs/constructs/dns-monitor/) before generating any code. -- When adding `assertions`, always use `DnsAssertionBuilder` class. - -// INSERT DNS MONITOR EXAMPLE HERE // - -### ICMP Monitor - -- Import the `IcmpMonitor` construct from `checkly/constructs`. -- Reference [the docs for ICMP monitors](https://www.checklyhq.com/docs/constructs/icmp-monitor/) before generating any code. -- When adding `assertions`, always use `IcmpAssertionBuilder` class. -- Latency assertions require a property parameter: `'avg'`, `'min'`, `'max'`, or `'stdDev'`. -- Use `degradedPacketLossThreshold` and `maxPacketLossThreshold` for packet loss thresholds (percentages). - -// INSERT ICMP MONITOR EXAMPLE HERE // - -### Heartbeat Monitor - -- Import the `HeartbeatMonitor` construct from `checkly/constructs`. - -// INSERT HEARTBEAT MONITOR EXAMPLE HERE // - -### 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. - -// INSERT CHECK GROUP EXAMPLE HERE // - -## 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](https://www.checklyhq.com/docs/constructs/overview/). - -### Email Alert Channel - -// INSERT EMAIL ALERT CHANNEL EXAMPLE HERE // - - -### Phone Call Alert Channel - -// INSERT PHONE CALL ALERT CHANNEL EXAMPLE HERE // - - -### Slack Alert Channel - -// INSERT SLACK ALERT CHANNEL EXAMPLE HERE // - - -## 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. - -// INSERT STATUS PAGE EXAMPLE HERE // - -### Status Page Service - -- Import the `StatusPageService` construct from `checkly/constructs`. -- Status Page Services are used to represent individual services on a Status Page. - -// INSERT STATUS PAGE SERVICE EXAMPLE HERE // - -### Dashboard - -- Import the `Dashboard` construct from `checkly/constructs`. -- Dashboards are used to display the results of your checks on screens external to Checkly. - -// INSERT DASHBOARD EXAMPLE HERE // - -### 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. - -// INSERT MAINTENANCE WINDOW EXAMPLE HERE // - -### 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. - -// INSERT PRIVATE LOCATION EXAMPLE HERE // - -## 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 diff --git a/packages/cli/src/ai-context/context.fixtures.json b/packages/cli/src/ai-context/context.fixtures.json index c61067ae5..505307c2e 100644 --- a/packages/cli/src/ai-context/context.fixtures.json +++ b/packages/cli/src/ai-context/context.fixtures.json @@ -1072,7 +1072,7 @@ "type": "CALL", "config": { "name": "Test User", - "number": "+311234567890" + "number": "INSERT_PHONE_NUMBER" }, "accountId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "created_at": "2025-07-07T11:36:19.897Z", @@ -1095,7 +1095,7 @@ "id": 100000014, "type": "SLACK", "config": { - "url": "https://hooks.slack.com/services/TK123456789123/12345/123456789", + "url": "INSERT_SLACK_URL", "channel": "#general" }, "accountId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", @@ -1113,4 +1113,4 @@ "friends": [], "auxiliary": [] } -} \ No newline at end of file +} diff --git a/packages/cli/src/ai-context/context.ts b/packages/cli/src/ai-context/context.ts index c9f701550..68f59856d 100644 --- a/packages/cli/src/ai-context/context.ts +++ b/packages/cli/src/ai-context/context.ts @@ -1,14 +1,56 @@ -export const EXAMPLE_CONFIGS: Record< - string, +export const REFERENCES = [ { - templateString: string - reference: string - exampleConfig?: string - exampleConfigPath?: string - } -> = { + id: 'api-checks', + linkText: 'API Checks', + description: 'ApiCheck construct, assertions, and authentication setup scripts', + }, + { + id: 'browser-checks', + linkText: 'Browser Checks', + description: 'BrowserCheck construct with Playwright test files', + }, + { + id: 'playwright-checks', + linkText: 'Playwright Checks', + description: 'PlaywrightCheck construct for multi-browser test suites', + }, + { + id: 'multistep-checks', + linkText: 'MultiStep Checks', + description: 'MultiStepCheck construct for complex user flows', + }, + { + id: 'monitors', + linkText: 'Monitors', + description: 'TCP, URL, DNS, ICMP, and Heartbeat monitors', + }, + { + id: 'check-groups', + linkText: 'Check Groups', + description: 'CheckGroupV2 construct for organizing checks', + }, + { + id: 'alert-channels', + linkText: 'Alert Channels', + description: 'Email, Phone, and Slack alert channels', + }, + { + id: 'supporting-constructs', + linkText: 'Supporting Constructs', + description: 'Status pages, dashboards, maintenance windows, and private locations', + }, +] as const + +interface ExampleConfig { + templateString: string + reference: string + exampleConfig?: string + exampleConfigPath?: string +} + +export const EXAMPLE_CONFIGS: Record = { CHECKLY_CONFIG: { - templateString: '// INSERT CHECKLY CONFIG EXAMPLE HERE //', + templateString: '', exampleConfig: `import { defineConfig } from 'checkly' import { Frequency } from 'checkly/constructs' @@ -45,13 +87,13 @@ export default defineConfig({ reference: 'https://www.checklyhq.com/docs/constructs/project/', }, BROWSER_CHECK: { - templateString: '// INSERT BROWSER CHECK EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/browser-checks/example-browser-check/example-browser-check.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/browser-check/', }, PLAYWRIGHT_CHECK: { - templateString: '// INSERT PLAYWRIGHT CHECK EXAMPLE HERE //', + templateString: '', exampleConfig: `import { PlaywrightCheck } from "checkly/constructs" const playwrightChecks = new PlaywrightCheck("multi-browser-check", { @@ -65,90 +107,90 @@ const playwrightChecks = new PlaywrightCheck("multi-browser-check", { reference: 'https://www.checklyhq.com/docs/constructs/playwright-check/', }, API_CHECK: { - templateString: '// INSERT API CHECK EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/api-checks/example-api-check/example-api-check.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/api-check/', }, MULTISTEP_CHECK: { - templateString: '// INSERT MULTISTEP CHECK EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/multi-step-checks/example-multistep-check/example-multistep-check.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/multistep-check/', }, TCP_MONITOR: { - templateString: '// INSERT TCP MONITOR EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/tcp-monitors/example-tcp-monitor.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/tcp-monitor/', }, HEARTBEAT_MONITOR: { - templateString: '// INSERT HEARTBEAT MONITOR EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/heartbeat-monitors/example-heartbeat-monitor.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/heartbeat-monitor/', }, URL_MONITOR: { - templateString: '// INSERT URL MONITOR EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/url-monitors/example-url-monitor.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/url-monitor/', }, DNS_MONITOR: { - templateString: '// INSERT DNS MONITOR EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/dns-monitors/example-dns-monitor.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/dns-monitor/', }, ICMP_MONITOR: { - templateString: '// INSERT ICMP MONITOR EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/icmp-monitors/example-icmp-monitor.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/icmp-monitor/', }, CHECK_GROUP: { - templateString: '// INSERT CHECK GROUP EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/check-group/example-group/example-group.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/check-group/', }, STATUS_PAGE: { - templateString: '// INSERT STATUS PAGE EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/status-pages/example-status-page.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/status-page/', }, STATUS_PAGE_SERVICE: { - templateString: '// INSERT STATUS PAGE SERVICE EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/status-pages/services/example-service.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/status-page-service/', }, DASHBOARD: { - templateString: '// INSERT DASHBOARD EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/dashboards/example-dashboard/example-dashboard.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/dashboard/', }, MAINTENANCE_WINDOW: { - templateString: '// INSERT MAINTENANCE WINDOW EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/maintenance-windows/example-maintenance-window.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/maintenance-window/', }, PRIVATE_LOCATION: { - templateString: '// INSERT PRIVATE LOCATION EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/private-locations/example-private-location.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/private-location/', }, EMAIL_ALERT_CHANNEL: { - templateString: '// INSERT EMAIL ALERT CHANNEL EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/alert-channels/email/test.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/email-alert-channel/', }, PHONE_CALL_ALERT_CHANNEL: { - templateString: '// INSERT PHONE CALL ALERT CHANNEL EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/alert-channels/phone-call/test-user.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/phone-call-alert-channel/', }, SLACK_ALERT_CHANNEL: { - templateString: '// INSERT SLACK ALERT CHANNEL EXAMPLE HERE //', + templateString: '', exampleConfigPath: 'resources/alert-channels/slack/general.check.ts', reference: 'https://www.checklyhq.com/docs/constructs/slack-alert-channel/', }, diff --git a/packages/cli/src/ai-context/references/alert-channels.md b/packages/cli/src/ai-context/references/alert-channels.md new file mode 100644 index 000000000..39c13f04c --- /dev/null +++ b/packages/cli/src/ai-context/references/alert-channels.md @@ -0,0 +1,22 @@ +# Alert Channels + +- 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 available alerts are described in the [Checkly docs](https://www.checklyhq.com/docs/constructs/overview/). + +*Important*: Don't make up email addresses, phone numbers, Slack URLs or similar static values. Scan the project to discover a valid configuration or ask what the values should be. + +## Email Alert Channel + + + +## Phone Call Alert Channel + + + +## Slack Alert Channel + + diff --git a/packages/cli/src/ai-context/references/api-checks.md b/packages/cli/src/ai-context/references/api-checks.md new file mode 100644 index 000000000..a2cabb91d --- /dev/null +++ b/packages/cli/src/ai-context/references/api-checks.md @@ -0,0 +1,18 @@ +# API Checks + +- 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 `setup-script.ts` and `teardown-script.ts` for API checks must be plain ts files and not export anything. +- Check in the code if API endpoints require authentication. + + + +## 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`. diff --git a/packages/cli/src/ai-context/references/browser-checks.md b/packages/cli/src/ai-context/references/browser-checks.md new file mode 100644 index 000000000..897380803 --- /dev/null +++ b/packages/cli/src/ai-context/references/browser-checks.md @@ -0,0 +1,7 @@ +# Browser Checks + +- 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. + + diff --git a/packages/cli/src/ai-context/references/check-groups.md b/packages/cli/src/ai-context/references/check-groups.md new file mode 100644 index 000000000..bfcb81b90 --- /dev/null +++ b/packages/cli/src/ai-context/references/check-groups.md @@ -0,0 +1,7 @@ +# Check Groups + +- 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. + + diff --git a/packages/cli/src/ai-context/references/monitors.md b/packages/cli/src/ai-context/references/monitors.md new file mode 100644 index 000000000..1f473b4c4 --- /dev/null +++ b/packages/cli/src/ai-context/references/monitors.md @@ -0,0 +1,39 @@ +# Monitors + +## TCP Monitor + +- Import the `TcpMonitor` construct from `checkly/constructs`. +- When adding `assertions`, always use `TcpAssertionBuilder` class for TCP monitors. + + + +## URL Monitor + +- Import the `UrlMonitor` construct from `checkly/constructs`. +- When adding `assertions`, always use `UrlAssertionBuilder`. + + + +## DNS Monitor + +- Import the `DnsMonitor` construct from `checkly/constructs`. +- Reference [the docs for DNS monitors](https://www.checklyhq.com/docs/constructs/dns-monitor/) before generating any code. +- When adding `assertions`, always use `DnsAssertionBuilder` class. + + + +### ICMP Monitor + +- Import the `IcmpMonitor` construct from `checkly/constructs`. +- Reference [the docs for ICMP monitors](https://www.checklyhq.com/docs/constructs/icmp-monitor/) before generating any code. +- When adding `assertions`, always use `IcmpAssertionBuilder` class. +- Latency assertions require a property parameter: `'avg'`, `'min'`, `'max'`, or `'stdDev'`. +- Use `degradedPacketLossThreshold` and `maxPacketLossThreshold` for packet loss thresholds (percentages). + + + +## Heartbeat Monitor + +- Import the `HeartbeatMonitor` construct from `checkly/constructs`. + + diff --git a/packages/cli/src/ai-context/references/multistep-checks.md b/packages/cli/src/ai-context/references/multistep-checks.md new file mode 100644 index 000000000..6b81c41c4 --- /dev/null +++ b/packages/cli/src/ai-context/references/multistep-checks.md @@ -0,0 +1,7 @@ +# MultiStep Checks + +- 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. + + diff --git a/packages/cli/src/ai-context/references/playwright-checks.md b/packages/cli/src/ai-context/references/playwright-checks.md new file mode 100644 index 000000000..4f0391a93 --- /dev/null +++ b/packages/cli/src/ai-context/references/playwright-checks.md @@ -0,0 +1,7 @@ +# Playwright Check Suites + +- Import the `PlaywrightCheck` construct from `checkly/constructs`. +- use `pwProjects` if you're tasked to reuse a Playwright project. +- use `pwTags` if you're tasked to reuse a Playwright tag. + + diff --git a/packages/cli/src/ai-context/references/supporting-constructs.md b/packages/cli/src/ai-context/references/supporting-constructs.md new file mode 100644 index 000000000..102847e7b --- /dev/null +++ b/packages/cli/src/ai-context/references/supporting-constructs.md @@ -0,0 +1,38 @@ +# 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. + + + +## Status Page Service + +- Import the `StatusPageService` construct from `checkly/constructs`. +- Status Page Services are used to represent individual services on a Status Page. + + + +## Dashboard + +- Import the `Dashboard` construct from `checkly/constructs`. +- Dashboards are used to display the results of your checks on screens external to Checkly. + + + +## 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. + + + +## 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. + + diff --git a/packages/cli/src/ai-context/skill-footer.md b/packages/cli/src/ai-context/skill-footer.md new file mode 100644 index 000000000..e9155ce38 --- /dev/null +++ b/packages/cli/src/ai-context/skill-footer.md @@ -0,0 +1,3 @@ +## Testing and Debugging + +- Test checks using the `npx checkly test` command. Pass environment variables with the `-e` flag, use `--record` to persist results, and use `--verbose` to see all errors. diff --git a/packages/cli/src/ai-context/skill-header.md b/packages/cli/src/ai-context/skill-header.md new file mode 100644 index 000000000..0fddc2c95 --- /dev/null +++ b/packages/cli/src/ai-context/skill-header.md @@ -0,0 +1,49 @@ +--- +name: monitoring +description: Create and manage monitoring checks using the Checkly CLI. Use when working with API checks, browser checks, URL monitors, ICMP monitors, Playwright checks, heartbeat monitors, alert channels, dashboards, or status pages. +allowed-tools: Bash(npx:checkly:*) Bash(npm:create:checkly@latest) +metadata: + author: checkly +--- + +# 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](https://www.checklyhq.com/docs/cli/overview/). +- Use the [Checkly construct reference documentation](https://www.checklyhq.com/docs/constructs/overview/). +- 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. + +## Using the Checkly CLI + +- Use `npx checkly` instead of installing the Checkly CLI globally. +- NEVER make up commands that do not exist. +- Use `npm create checkly@latest` to set up a new Checkly project via the CLI. + +## 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. + + + +## Check and Monitor Constructs + + diff --git a/packages/cli/src/constructs/api-check-codegen.ts b/packages/cli/src/constructs/api-check-codegen.ts index e25d849d8..28a4248f2 100644 --- a/packages/cli/src/constructs/api-check-codegen.ts +++ b/packages/cli/src/constructs/api-check-codegen.ts @@ -39,8 +39,6 @@ export class ApiCheckCodegen extends Codegen { builder.new(builder => { builder.string(logicalId) builder.object(builder => { - builder.value('request', valueForRequest(this.program, file, context, resource.request)) - if (resource.localSetupScript) { const content = resource.localSetupScript validateScript(content) @@ -106,6 +104,8 @@ export class ApiCheckCodegen extends Codegen { } buildRuntimeCheckProps(this.program, file, builder, resource, context) + + builder.value('request', valueForRequest(this.program, file, context, resource.request)) }) }) })) diff --git a/packages/cli/src/constructs/api-request-codegen.ts b/packages/cli/src/constructs/api-request-codegen.ts index fe1c2f35e..2150e186c 100644 --- a/packages/cli/src/constructs/api-request-codegen.ts +++ b/packages/cli/src/constructs/api-request-codegen.ts @@ -14,7 +14,7 @@ export function valueForRequest ( builder.string('url', request.url) builder.string('method', request.method) - if (request.ipFamily) { + if (request.ipFamily && request.ipFamily !== 'IPv4') { builder.string('ipFamily', request.ipFamily) } diff --git a/packages/cli/src/constructs/check-codegen.ts b/packages/cli/src/constructs/check-codegen.ts index 905470095..583132873 100644 --- a/packages/cli/src/constructs/check-codegen.ts +++ b/packages/cli/src/constructs/check-codegen.ts @@ -50,11 +50,11 @@ export function buildCheckProps ( builder.boolean('activated', resource.activated) } - if (resource.muted !== undefined) { + if (resource.muted !== undefined && resource.muted !== false) { builder.boolean('muted', resource.muted) } - if (resource.shouldFail !== undefined) { + if (resource.shouldFail !== undefined && resource.shouldFail !== false) { builder.boolean('shouldFail', resource.shouldFail) } @@ -167,13 +167,13 @@ export function buildCheckProps ( builder.value('alertEscalationPolicy', valueForAlertEscalation(genfile, resource.alertSettings)) } - if (resource.testOnly !== undefined) { + if (resource.testOnly !== undefined && resource.testOnly !== false) { builder.boolean('testOnly', resource.testOnly) } builder.value('retryStrategy', valueForRetryStrategy(genfile, resource.retryStrategy)) - if (resource.runParallel !== undefined) { + if (resource.runParallel !== undefined && resource.runParallel !== false) { builder.boolean('runParallel', resource.runParallel) } } diff --git a/packages/cli/src/constructs/dns-monitor-codegen.ts b/packages/cli/src/constructs/dns-monitor-codegen.ts index 021bbe550..e6931c82c 100644 --- a/packages/cli/src/constructs/dns-monitor-codegen.ts +++ b/packages/cli/src/constructs/dns-monitor-codegen.ts @@ -32,8 +32,6 @@ export class DnsMonitorCodegen extends Codegen { builder.new(builder => { builder.string(logicalId) builder.object(builder => { - builder.value('request', valueForDnsRequest(this.program, file, context, resource.request)) - if (resource.degradedResponseTime !== undefined) { builder.number('degradedResponseTime', resource.degradedResponseTime) } @@ -43,6 +41,8 @@ export class DnsMonitorCodegen extends Codegen { } buildMonitorProps(this.program, file, builder, resource, context) + + builder.value('request', valueForDnsRequest(this.program, file, context, resource.request)) }) }) })) diff --git a/packages/cli/src/constructs/tcp-monitor-codegen.ts b/packages/cli/src/constructs/tcp-monitor-codegen.ts index a99912b8e..2b02331d3 100644 --- a/packages/cli/src/constructs/tcp-monitor-codegen.ts +++ b/packages/cli/src/constructs/tcp-monitor-codegen.ts @@ -1,7 +1,7 @@ -import { Codegen, Context } from './internal/codegen' import { expr, GeneratedFile, ident, Value } from '../sourcegen' -import { buildMonitorProps, MonitorResource } from './monitor-codegen' import { valueForGeneralAssertion, valueForNumericAssertion } from './internal/assertion-codegen' +import { Codegen, Context } from './internal/codegen' +import { buildMonitorProps, MonitorResource } from './monitor-codegen' import { TcpAssertion, TcpRequest } from './tcp-monitor' export interface TcpMonitorResource extends MonitorResource { @@ -45,6 +45,16 @@ export class TcpMonitorCodegen extends Codegen { builder.new(builder => { builder.string(logicalId) builder.object(builder => { + if (resource.degradedResponseTime !== undefined) { + builder.number('degradedResponseTime', resource.degradedResponseTime) + } + + if (resource.maxResponseTime !== undefined) { + builder.number('maxResponseTime', resource.maxResponseTime) + } + + buildMonitorProps(this.program, file, builder, resource, context) + builder.object('request', builder => { builder.string('hostname', resource.request.hostname) builder.number('port', resource.request.port) @@ -68,16 +78,6 @@ export class TcpMonitorCodegen extends Codegen { } } }) - - if (resource.degradedResponseTime !== undefined) { - builder.number('degradedResponseTime', resource.degradedResponseTime) - } - - if (resource.maxResponseTime !== undefined) { - builder.number('maxResponseTime', resource.maxResponseTime) - } - - buildMonitorProps(this.program, file, builder, resource, context) }) }) })) diff --git a/packages/cli/src/constructs/url-monitor-codegen.ts b/packages/cli/src/constructs/url-monitor-codegen.ts index 0a3f066dc..cd155ac62 100644 --- a/packages/cli/src/constructs/url-monitor-codegen.ts +++ b/packages/cli/src/constructs/url-monitor-codegen.ts @@ -32,7 +32,7 @@ export class UrlMonitorCodegen extends Codegen { builder.new(builder => { builder.string(logicalId) builder.object(builder => { - builder.value('request', valueForUrlRequest(this.program, file, context, resource.request)) + buildMonitorProps(this.program, file, builder, resource, context) if (resource.degradedResponseTime !== undefined) { builder.number('degradedResponseTime', resource.degradedResponseTime) @@ -42,7 +42,7 @@ export class UrlMonitorCodegen extends Codegen { builder.number('maxResponseTime', resource.maxResponseTime) } - buildMonitorProps(this.program, file, builder, resource, context) + builder.value('request', valueForUrlRequest(this.program, file, context, resource.request)) }) }) })) diff --git a/skills/monitoring/README.md b/skills/monitoring/README.md index ab9e48119..a00a1a750 100644 --- a/skills/monitoring/README.md +++ b/skills/monitoring/README.md @@ -8,7 +8,16 @@ This directory contains the agent skill for creating and managing end-to-end tes skills/ └── monitoring/ ├── README.md # Documentation about the skill - └── SKILL.md # Main skill instructions + ├── SKILL.md # Main skill instructions + └── references/ # Detailed construct documentation + ├── api-checks.md + ├── browser-checks.md + ├── playwright-checks.md + ├── multistep-checks.md + ├── monitors.md + ├── check-groups.md + ├── alert-channels.md + └── supporting-constructs.md ``` ## What is an Agent Skill? @@ -27,13 +36,15 @@ Agent Skills are a standardized format for giving AI agents specialized knowledg AI agents can load this skill to gain expertise in Checkly monitoring. The skill follows the [Agent Skills specification](https://agentskills.io) with: - **SKILL.md**: Core instructions loaded when the skill is activated +- **references/**: Detailed documentation loaded on demand ## Progressive Disclosure The skill is structured for efficient context usage: 1. **Metadata** (~80 tokens): Name and description in frontmatter -2. **Core Instructions** (~4.5K tokens): Main SKILL.md content with construct examples +2. **Core Instructions** (~1K tokens): Main SKILL.md content with links to references +3. **References** (loaded on demand): Detailed construct documentation with examples Agents load what they need for each task. diff --git a/skills/monitoring/SKILL.md b/skills/monitoring/SKILL.md index 34a5da649..1a175fe12 100644 --- a/skills/monitoring/SKILL.md +++ b/skills/monitoring/SKILL.md @@ -15,10 +15,11 @@ metadata: - 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 +## Using the Checkly CLI -- ALWAYS use `npm create checkly@latest`. +- Use `npx checkly` instead of installing the Checkly CLI globally. - NEVER make up commands that do not exist. +- Use `npm create checkly@latest` to set up a new Checkly project via the CLI. ## Project Structure @@ -80,565 +81,15 @@ export default defineConfig({ ## 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](https://www.checklyhq.com/docs/constructs/dns-monitor/) 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, -}) -``` - -### ICMP Monitor - -- Import the `IcmpMonitor` construct from `checkly/constructs`. -- Reference [the docs for ICMP monitors](https://www.checklyhq.com/docs/constructs/icmp-monitor/) before generating any code. -- When adding `assertions`, always use `IcmpAssertionBuilder` class. -- Latency assertions require a property parameter: `'avg'`, `'min'`, `'max'`, or `'stdDev'`. -- Use `degradedPacketLossThreshold` and `maxPacketLossThreshold` for packet loss thresholds (percentages). - -**Reference:** https://www.checklyhq.com/docs/constructs/icmp-monitor/ - -```typescript -import { AlertEscalationBuilder, Frequency, IcmpAssertionBuilder, IcmpMonitor, RetryStrategyBuilder } from 'checkly/constructs' - -new IcmpMonitor('example-icmp-monitor', { - name: 'Example ICMP Monitor', - request: { - hostname: '1.1.1.1', - pingCount: 10, - assertions: [ - IcmpAssertionBuilder.latency('avg').lessThan(100), - IcmpAssertionBuilder.latency('max').lessThan(200), - ], - }, - degradedPacketLossThreshold: 10, - maxPacketLossThreshold: 20, - activated: true, - muted: 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](https://www.checklyhq.com/docs/constructs/overview/). - -### 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', -}) -``` +- [API Checks](references/api-checks.md) - ApiCheck construct, assertions, and authentication setup scripts +- [Browser Checks](references/browser-checks.md) - BrowserCheck construct with Playwright test files +- [Playwright Checks](references/playwright-checks.md) - PlaywrightCheck construct for multi-browser test suites +- [MultiStep Checks](references/multistep-checks.md) - MultiStepCheck construct for complex user flows +- [Monitors](references/monitors.md) - TCP, URL, DNS, ICMP, and Heartbeat monitors +- [Check Groups](references/check-groups.md) - CheckGroupV2 construct for organizing checks +- [Alert Channels](references/alert-channels.md) - Email, Phone, and Slack alert channels +- [Supporting Constructs](references/supporting-constructs.md) - Status pages, dashboards, maintenance windows, and private locations ## 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 +- Test checks using the `npx checkly test` command. Pass environment variables with the `-e` flag, use `--record` to persist results, and use `--verbose` to see all errors. diff --git a/skills/monitoring/references/alert-channels.md b/skills/monitoring/references/alert-channels.md new file mode 100644 index 000000000..0332144ff --- /dev/null +++ b/skills/monitoring/references/alert-channels.md @@ -0,0 +1,49 @@ +# Alert Channels + +- 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 available alerts are described in the [Checkly docs](https://www.checklyhq.com/docs/constructs/overview/). + +*Important*: Don't make up email addresses, phone numbers, Slack URLs or similar static values. Scan the project to discover a valid configuration or ask what the values should be. + +## 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: 'INSERT_PHONE_NUMBER', +}) +``` + +## 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: 'INSERT_SLACK_URL', + channel: '#general', +}) +``` diff --git a/skills/monitoring/references/api-checks.md b/skills/monitoring/references/api-checks.md new file mode 100644 index 000000000..8a5df0208 --- /dev/null +++ b/skills/monitoring/references/api-checks.md @@ -0,0 +1,58 @@ +# API Checks + +- 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 `setup-script.ts` and `teardown-script.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', + setupScript: { + entrypoint: './setup-script.ts', + }, + tearDownScript: { + entrypoint: './teardown-script.ts', + }, + degradedResponseTime: 5000, + maxResponseTime: 20000, + activated: true, + 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, + request: { + url: 'https://api.example.com/v1/products', + method: 'GET', + }, +}) +``` + +## 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`. diff --git a/skills/monitoring/references/browser-checks.md b/skills/monitoring/references/browser-checks.md new file mode 100644 index 000000000..15fc98fb9 --- /dev/null +++ b/skills/monitoring/references/browser-checks.md @@ -0,0 +1,38 @@ +# Browser Checks + +- 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, + 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, +}) +``` diff --git a/skills/monitoring/references/check-groups.md b/skills/monitoring/references/check-groups.md new file mode 100644 index 000000000..1d71353b6 --- /dev/null +++ b/skills/monitoring/references/check-groups.md @@ -0,0 +1,15 @@ +# Check Groups + +- 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', +}) +``` diff --git a/skills/monitoring/references/monitors.md b/skills/monitoring/references/monitors.md new file mode 100644 index 000000000..0231be27e --- /dev/null +++ b/skills/monitoring/references/monitors.md @@ -0,0 +1,206 @@ +# Monitors + +## 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', + degradedResponseTime: 5000, + maxResponseTime: 5000, + activated: true, + 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, + request: { + hostname: 'tcp.example.com', + port: 4242, + ipFamily: 'IPv4', + assertions: [ + TcpAssertionBuilder.responseTime().lessThan(200), + TcpAssertionBuilder.responseData().isEmpty(), + ], + }, +}) +``` + +## 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', + activated: true, + 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, + degradedResponseTime: 5000, + maxResponseTime: 20000, + request: { + url: 'https://example.com', + ipFamily: 'IPv4', + assertions: [ + UrlAssertionBuilder.statusCode().equals(200), + ], + }, +}) +``` + +## DNS Monitor + +- Import the `DnsMonitor` construct from `checkly/constructs`. +- Reference [the docs for DNS monitors](https://www.checklyhq.com/docs/constructs/dns-monitor/) 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', + degradedResponseTime: 500, + maxResponseTime: 1000, + activated: true, + 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(), + request: { + recordType: 'AAAA', + query: 'welcome.checklyhq.com', + assertions: [ + DnsAssertionBuilder.responseCode().equals('NOERROR'), + ], + }, +}) +``` + +### ICMP Monitor + +- Import the `IcmpMonitor` construct from `checkly/constructs`. +- Reference [the docs for ICMP monitors](https://www.checklyhq.com/docs/constructs/icmp-monitor/) before generating any code. +- When adding `assertions`, always use `IcmpAssertionBuilder` class. +- Latency assertions require a property parameter: `'avg'`, `'min'`, `'max'`, or `'stdDev'`. +- Use `degradedPacketLossThreshold` and `maxPacketLossThreshold` for packet loss thresholds (percentages). + +**Reference:** https://www.checklyhq.com/docs/constructs/icmp-monitor/ + +```typescript +import { AlertEscalationBuilder, Frequency, IcmpAssertionBuilder, IcmpMonitor, RetryStrategyBuilder } from 'checkly/constructs' + +new IcmpMonitor('example-icmp-monitor', { + name: 'Example ICMP Monitor', + request: { + hostname: '1.1.1.1', + pingCount: 10, + assertions: [ + IcmpAssertionBuilder.latency('avg').lessThan(100), + IcmpAssertionBuilder.latency('max').lessThan(200), + ], + }, + degradedPacketLossThreshold: 10, + maxPacketLossThreshold: 20, + activated: true, + 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(), +}) +``` + +## 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, + 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, +}) +``` diff --git a/skills/monitoring/references/multistep-checks.md b/skills/monitoring/references/multistep-checks.md new file mode 100644 index 000000000..251a166d9 --- /dev/null +++ b/skills/monitoring/references/multistep-checks.md @@ -0,0 +1,33 @@ +# MultiStep Checks + +- 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, + 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, +}) +``` diff --git a/skills/monitoring/references/playwright-checks.md b/skills/monitoring/references/playwright-checks.md new file mode 100644 index 000000000..4dfdc4334 --- /dev/null +++ b/skills/monitoring/references/playwright-checks.md @@ -0,0 +1,19 @@ +# Playwright Check Suites + +- Import the `PlaywrightCheck` construct from `checkly/constructs`. +- use `pwProjects` if you're tasked to reuse a Playwright project. +- use `pwTags` if you're tasked to reuse a Playwright tag. + +**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"], +}); +``` diff --git a/skills/monitoring/references/supporting-constructs.md b/skills/monitoring/references/supporting-constructs.md new file mode 100644 index 000000000..4cde3407c --- /dev/null +++ b/skills/monitoring/references/supporting-constructs.md @@ -0,0 +1,119 @@ +# 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', +}) +```