diff --git a/detect/synthetic-monitoring/api-checks/requests.mdx b/detect/synthetic-monitoring/api-checks/requests.mdx index dfcf514a..575c7e81 100644 --- a/detect/synthetic-monitoring/api-checks/requests.mdx +++ b/detect/synthetic-monitoring/api-checks/requests.mdx @@ -4,7 +4,7 @@ description: 'Requests' sidebarTitle: 'Requests' --- - +import GenericRuntimeVariablesTable from '/snippets/generic-runtime-variables-table.mdx'; A full HTTP request is created by filling out the various parts of the HTTP request settings screen. Not all sections and fields are mandatory, only a name and URL are required to get going. @@ -98,6 +98,46 @@ request, use the username and password fields in the relevant section. ![api monitoring basic auth](/images/docs/images/api-checks/http-request-auth.png) +## Accessing environment variables + +[Environment variables](/platform/variables) are exposed to your API checks using the common Handlebars/Moustache templating delimiters, i.e. `{{USER_API_KEY}}`. Note that Handlebars (double brackets) variables will be URI encoded. To avoid encoding, you can access your environment variables with triple brackets, i.e. `{{{USER_API_KEY}}}`. + +Variables can be used in the following API checks fields: + +- URL +- Body +- Header values +- Query parameters values +- Basic authentication username and password + +### Using helpers and built-in variables + +Next to your own variables, we've added some built-in ones. + +These variables are specific to API checks: + +| Helper | Description | +|----------------------|------------ | +| `{{GROUP_BASE_URL}}` | If your check belongs to a group, this resolves to the group's configured base URL. | +| `{{REQUEST_URL}}` | The request URL. | +| `{{$UUID}}` | Generates a random UUID/v4, i.e. 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d. | +| `{{$RANDOM_NUMBER}}` | Generates a random decimal number between 0 and 10000, i.e. 345. | +| `{{moment}}` | Generates a date or time using **moment.js** and allows for formatting: | + +A practical example of using the `{{moment}}` helper would be setting the pagination options on a typical API endpoint: + +``` + GET https://api.acme.com/events?from={{moment "last week" "X"}}&to={{moment "X"}} +``` + + +For a full overview of date formatting option, check the [moment.js docs](https://momentjs.com/docs/#/displaying/format/). + + +In addition, you have access to these generic variables available to all checks: + + + ## Import a cURL request You can import the request method, url, headers and body from a [cURL](https://curl.haxx.se/) command. @@ -160,5 +200,4 @@ This list shows all content types that we scrub from the response data. |`video/x-ms-wmv`| |`video/x-msvideo`| |`video/x-flv`| -|`video/webm`| - +|`video/webm`| \ No newline at end of file diff --git a/detect/synthetic-monitoring/api-checks/set-up-and-tear-down.mdx b/detect/synthetic-monitoring/api-checks/set-up-and-tear-down.mdx index dbc217a6..4439e499 100644 --- a/detect/synthetic-monitoring/api-checks/set-up-and-tear-down.mdx +++ b/detect/synthetic-monitoring/api-checks/set-up-and-tear-down.mdx @@ -5,6 +5,8 @@ description: 'Learn how to set up and tear down an API check with Checkly.' sidebarTitle: Set Up and Tear Down --- +import GenericRuntimeVariablesTable from '/snippets/generic-runtime-variables-table.mdx'; + Setup and teardown scripts can be used to execute arbitrary JavaScript/TypeScript code before and/or after an API check. Both script types have access to all environment variables, runtime objects like `request` and `response` and popular npm packages like `moment`, `axios` and `lodash`. @@ -166,7 +168,7 @@ delete process.env.SOME_OTHER_KEY In setup scripts, the modified environment object is used for the subsequent HTTP request. In teardown script, the modified environment object is just there for informational purposes. -[More about using environment variables](/api-checks/variables/) +[More about using environment variables](/platform/variables) ### Request @@ -196,16 +198,18 @@ Response properties are exposed a standard Javascript object. These are only ava ### Built-in runtime variables [The setup and teardown runtime](/platform/runtimes/overview) also exposes a set of specific environment variables to the setup and teardown scripts, -next to the "generic" runtime variables like `process.env.CHECK_NAME` you find in all check runtimes +next to the "generic" runtime variables like `process.env.CHECK_NAME` you find in all check runtimes. #### Setup & teardown specific variables -| variable | description | +| Variable | Description | |------------------|------------------------------------------------------------| | `GROUP_BASE_URL` | The `{{GROUP_BASE_URL}}` value of the grouped `API` check. | | `REQUEST_URL` | The request URL of the `API` check executed. | +#### Generic runtime variables + ## Included libraries diff --git a/detect/synthetic-monitoring/browser-checks/mac-structure.mdx b/detect/synthetic-monitoring/browser-checks/mac-structure.mdx index 477c7868..f790789c 100644 --- a/detect/synthetic-monitoring/browser-checks/mac-structure.mdx +++ b/detect/synthetic-monitoring/browser-checks/mac-structure.mdx @@ -4,6 +4,7 @@ description: 'Learn how to structure your Browser Checks with Monitoring as Code sidebarTitle: MaC Structure --- +import GenericRuntimeVariablesTable from '/snippets/generic-runtime-variables-table.mdx'; Monitoring as Code works by connecting Playwrighttest files with Checkly constructs to handle the end-to-endconfiguration of your Browser Check. @@ -42,3 +43,39 @@ test('Environment-aware test', async ({ page }) => { }) ``` +## Environment variables + +[Check, group and global variables](/platform/variables) are accessible in your code using the standard Node.js `process.env.MY_VAR` notation. For example, the code snippet below show how you can log into GitHub. + + + +```ts variables.spec.ts +import { test } from '@playwright/test' + +test('GitHub login', async ({ page }) => { + await page.goto('https://github.com/login') + await page.getByLabel('Username or email address').type(process.env.GITHUB_USER) + await page.getByLabel('Password').type(process.env.GITHUB_PWD) + await page.getByRole('button', { name: 'Sign in' }).click() +}) +``` + +```js variables.spec.js +const { test } = require('@playwright/test') + +test('GitHub login', async ({ page }) => { + await page.goto('https://github.com/login') + await page.getByLabel('Username or email address').type(process.env.GITHUB_USER) + await page.getByLabel('Password').type(process.env.GITHUB_PWD) + await page.getByRole('button', { name: 'Sign in' }).click() +}) +``` + + + +### Built-in runtime variables + +Our [check runtimes](/platform/runtimes/overview/) also expose a set of environment variables (e.g. `process.env.CHECK_NAME`) +to figure out what check, check type etc. you are running. + + \ No newline at end of file diff --git a/detect/synthetic-monitoring/multistep-checks/overview.mdx b/detect/synthetic-monitoring/multistep-checks/overview.mdx index 3d7f36ad..7abad674 100644 --- a/detect/synthetic-monitoring/multistep-checks/overview.mdx +++ b/detect/synthetic-monitoring/multistep-checks/overview.mdx @@ -4,6 +4,8 @@ description: 'Monitor complex API workflows with sequential requests using Playw sidebarTitle: 'Overview' --- +import GenericRuntimeVariablesTable from '/snippets/generic-runtime-variables-table.mdx'; + **Monitoring as Code**: Learn more about the [Multistep Check Construct](/constructs/multistep-check). @@ -66,5 +68,6 @@ As with Browser checks, Checkly runs Multistep checks for a maximum of 240s. Scr The Multistep Check [runtime](/platform/runtimes/overview) exposes a set of environment variables (e.g. `process.env.CHECK_NAME`) that indicate what check, check type etc. you are running. + - +[Learn more about environment variables.](/platform/variables) diff --git a/platform/variables.mdx b/platform/variables.mdx index f8f5da40..22836efb 100644 --- a/platform/variables.mdx +++ b/platform/variables.mdx @@ -1,116 +1,94 @@ --- -title: 'Environment variables' +title: 'Environment variables and secrets' sidebarTitle: 'Environment Variables' -description: 'Securely store and manage sensitive data like credentials and configuration values across your monitoring checks' +description: 'Store and manage common configuration values across your checks' --- -Environment variables allow you to store sensitive data like credentials and configuration values that can be reused across your monitoring setup. This keeps secrets out of your code and enables flexible configuration management. +import GenericRuntimeVariablesTable from '/snippets/generic-runtime-variables-table.mdx'; -## Managing variables +Your checks might share the same configuration data, like an authentication token, a user name, or even a specific part of the URL. You can use variables and secrets to 'DRY' up your checks, store these variables in one place, and keep sensitive data secure. -You can create environment variables at three hierarchical levels, with check-level variables taking precedence over group and global variables. +## Overview - -Variables defined at the check level are only available to that specific check. Use these for check-specific configuration or to override group/global variables. +There are two ways to store configuration information in Checkly: Variables and secrets. Both variables and secrets are encrypted at rest and in flight. +* **Variables** are used to store non-sensitive information. Variables are shown in plaintext when being edited, on the check result page and in logs. Variables can be accessed via the CLI and API. +* **Secrets** allow you to store sensitive data for use in checks. Once saved, secrets are never shown in the UI or in logs and cannot be accessed via the CLI or API. -**Supported by:** API, Browser, Multistep & Playwright checks + +Secrets are fully supported starting with runtime version 2024.09 and later. For [Private Locations](/docs/private-locations/), secrets are available in agent version `3.3.4` and later, and for the [CLI](/docs/cli/), in version `4.9.0` and later. + -Add variables on the **Variables** tab when editing a check. + +To ensure the integrity of Playwright artifacts (traces, videos and screenshots), the following are not scrubbed, even when saved as secrets: The characters `/` and `*` and the full or partial match of `/artifact/`, `https://`, `http://`, `*********`, and `123`. +Values of the keys `sha1`, `_sha1`, `pageref`, `downloadsPath`, `tracesDir`, `pageId` and any string that ends with `sha1` will not be scrubbed from the Playwright trace, but will be scrubbed from the general check result. +Numbers are not scrubbed from the Playwright trace, but from the general check result. + -![check environment variables](/images/docs/images/browser-checks/check-environment-variables.png) + + This page provides a general overview of environment variables. For information specific to the CLI, refer to our [Checkly CLI documentation](/cli/environment-variables). + -**Example use cases:** -- Test-specific credentials -- Different API endpoints per check -- Override default timeout values - +From here on, in this document, we refer to both variables and secrets as 'variables' for ease of reading, unless explicitly mentioned. - -Variables defined at the group level are inherited by all checks within that group. This is ideal for sharing common configuration across related checks. +## Managing variables -**Benefits:** -- Reduces duplication across checks in the same group -- Consistent configuration for related monitoring scenarios -- Easy maintenance when credentials or endpoints change +You can create environment variables and secrets at three hierarchical levels: -**Example use cases:** -- Shared service credentials for all checks in a group -- Common API base URLs -- Environment-specific configuration (staging vs production) - + +Variables defined at the check level are only available to that specific check. Use these for check-specific configuration or to override group/global variables. - -Variables defined at the global level are available to all checks across your entire account. Use these for organization-wide configuration. +**Supported by:** API (only via the CLI), Browser, Multistep & Playwright checks -**Best practice:** Store variables at the global level whenever possible to follow the DRY (Don't Repeat Yourself) principle. +Check-level variables are shown in the **Variables** tab on the check edit page. -**Example use cases:** -- Organization-wide credentials -- Global configuration values -- Default timeout and retry settings +![check environment variables](/images/docs/images/browser-checks/check-environment-variables.png) -## Variable hierarchy + +Group variables are only accessible in the context of a group, which includes the checks within the group and their configuration. -When checks run, Checkly merges variables from all three levels into a single dataset. Variables at more specific levels override those at broader levels: +Group-level variables are shown the **Variables** tab in a check group. -**Check variables** > **Group variables** > **Global variables** +![set group environment variable](/images/docs/images/browser-checks/group-environment-variables.png) + -This hierarchy allows you to: -- Set default values at the global or group level -- Override specific values at the check level when needed -- Maintain flexible configuration with minimal duplication + +Variables defined at the global level are available throughout Checkly, including in checks, alert channels, and global configuration options. -## Accessing variables +Global variables are shown in the [Environment variables](https://app.checklyhq.com/environment-variables) section on the left-side menu. + +![set global environment variable](/images/docs/images/browser-checks/global-environment-variables.png) -Environment variables are accessible in your code using the standard Node.js `process.env.VARIABLE_NAME` notation. + +Store variables at the global level whenever possible to follow the DRY (Don't Repeat Yourself) principle. + - - + -```ts variables.spec.ts -import { test } from '@playwright/test' +By default, all variables are stored as string values. -test('GitHub login', async ({ page }) => { - await page.goto('https://github.com/login') - await page.getByLabel('Username or email address').type(process.env.GITHUB_USER) - await page.getByLabel('Password').type(process.env.GITHUB_PWD) - await page.getByRole('button', { name: 'Sign in' }).click() -}) -``` +When using variables, you can click the lock icon to hide the value. Any data you “lock” is encrypted at rest and in flight on our back end and is only decrypted when needed. Locked environment variables can only be accessed by team members with [Read & Write access](/admin/team-management/overview/) or above. -```js variables.spec.js -const { test } = require('@playwright/test') +Secrets are never visible for any user and are always encrypted. -test('GitHub login', async ({ page }) => { - await page.goto('https://github.com/login') - await page.getByLabel('Username or email address').type(process.env.GITHUB_USER) - await page.getByLabel('Password').type(process.env.GITHUB_PWD) - await page.getByRole('button', { name: 'Sign in' }).click() -}) -``` +## Variable hierarchy - - +As checks are scheduled, Checkly merges the check, group, and global environment variables into one data set and exposes them +to the runtime environment. During merging, variables at more specific levels override those at broader levels. -## Built-in variables +Or, in other words: **check** variables override **group** variables override **global** variables. -Checkly provides several built-in environment variables that are automatically available in your checks: +You can make use of this by providing a default value for a specific variable at the global or group level, but allow that variable to +be overridden at the check level. - -- `CHECK_NAME` - The name of the current check -- `CHECK_TYPE` - The type of check (API, BROWSER, etc.) -- `CHECK_ID` - The unique identifier of the check -- `REGION` - The current data center location (e.g., `us-east-1`) -- `RUN_ID` - Unique identifier for the current check run - +## Accessing variables -## Security +How variables are accessed depends on where you're accessing them from: -- **Encryption:** All variable data is encrypted at rest and in transit -- **Access control:** Locked variables can only be accessed by team members with Read & Write access or above -- **Best practices:** Avoid logging sensitive variables in your check results to prevent exposure to Read Only team members +* In [Browser](/detect/synthetic-monitoring/browser-checks/mac-structure#environment-variables), [Multistep](/detect/synthetic-monitoring/multistep-checks/overview#built-in-runtime-variables), and [API Check setup/teardown scripts](/detect/synthetic-monitoring/api-checks/set-up-and-tear-down#built-in-variables), use the standard Node.js `process.env.VARIABLE_NAME` notation. +* In [API Check requests](/detect/synthetic-monitoring/api-checks/requests#accessing-environment-variables), use Handlebars/Moustache templating delimiters, i.e. `{{VARIABLE_NAME}}` +* In [webhook alert channels](/integrations/alerts/webhooks#template-variables), also use the Handlebar/Moustache format, i.e. `{{VARIABLE_NAME}}` -For more login scenarios and examples, see our [login scenarios documentation](/browser-checks/login-scenarios/). + Handlebar (double brackets) variables will be URI encoded. To avoid encoding, you can access your environment variables with triple brackets, i.e. `{{{VARIABLE_NAME}}}`. diff --git a/snippets/generic-runtime-variables-table.mdx b/snippets/generic-runtime-variables-table.mdx new file mode 100644 index 00000000..854c04ab --- /dev/null +++ b/snippets/generic-runtime-variables-table.mdx @@ -0,0 +1,12 @@ +| Variable | Description | Availability | +|-------------------|---------------------------------------------|--------------------------------------| +| `ACCOUNT_ID` | The ID of the account the check belongs to. | | +| `CHECK_ID` | The UUID of the check being executed. | Only available after saving the check. | +| `CHECK_NAME` | The name of the check being executed. | | +| `CHECK_RESULT_ID` | The UUID where the result will be saved. | Only available on scheduled runs. | +| `CHECK_RUN_ID` | The UUID of the check run execution. | Only available on scheduled runs. | +| `CHECK_TYPE` | The type of the check, e.g. `BROWSER`. | | +| `PUBLIC_IP_V4` | The IPv4 of the check run execution. | | +| `PUBLIC_IP_V6` | The IPv6 of the check run execution. | | +| `REGION` | The current region, e.g. `us-west-1`. | | +| `RUNTIME_VERSION` | The version of the runtime, e.g, `2023.09`. | Only in Browser, Multistep, and API setup/teardown scripts. | \ No newline at end of file