Skip to content

Commit b166855

Browse files
mdbirnstiehlmdbirnstiehl
committed
add Create monitors with a Synthetics project
1 parent 60bc456 commit b166855

File tree

1 file changed

+268
-10
lines changed

1 file changed

+268
-10
lines changed

‎solutions/observability/apps/create-monitors-with-project-monitors.md‎

Lines changed: 268 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,281 @@
22
mapped_urls:
33
- https://www.elastic.co/guide/en/observability/current/synthetics-get-started-project.html
44
- https://www.elastic.co/guide/en/serverless/current/observability-synthetics-get-started-project.html
5+
6+
navigation_title: "Use a Synthetics project"
57
---
68

7-
# Create monitors with Project monitors
9+
# Create monitors with a Synthetics project [observability-synthetics-get-started-project]
10+
11+
12+
A Synthetics project is the most powerful and sophisticated way to configure synthetic monitors. A Synthetics project lets you define your infrastructure as code, more commonly known as IaaC or Git-ops. With monitors created and managed in Synthetics projects, you organize your YAML configuration and JavaScript- or TypeScript-defined monitors on the filesystem, use Git for version control, and deploy via a CLI tool, usually executed on a CI/CD platform.
13+
14+
:::{image} ../../../images/observability-synthetics-get-started-projects.png
15+
:alt: Diagram showing which pieces of software are used to configure monitors
16+
:::
17+
18+
This is one of [two approaches](../../../solutions/observability/apps/get-started.md) you can use to set up a synthetic monitor.
19+
20+
21+
## Prerequisites [synthetics-get-started-project-prerequisites]
22+
23+
For **serverless Observability projects**, you must be signed in as a user with [Editor](../../../solutions/observability/apps/grant-users-access-to-secured-resources.md) access.
24+
25+
For **Elastic Stack deployments**, you must be signed into {{kib}} as a user with at least [synthetics write permissions](../../../solutions/observability/apps/writer-role.md), and Monitor Management must be enabled by an administrator as described in [Setup role](../../../solutions/observability/apps/setup-role.md).
26+
27+
Working with a Synthetics project requires working with the Elastic Synthetics CLI tool, which can be invoked via the `npx @elastic/synthetics` command. Before getting started you’ll need to:
28+
29+
1. Install [Node.js](https://nodejs.dev/en/)
30+
2. Install the package:
31+
32+
```sh
33+
npm install -g @elastic/synthetics
34+
```
35+
36+
3. Confirm your system is setup correctly:
37+
38+
```sh
39+
npx @elastic/synthetics -h
40+
```
41+
42+
43+
You should also decide where you want to run the monitors before getting started. You can run monitors in Synthetics projects on one or both of the following:
44+
45+
* **Elastic’s global managed testing infrastructure**: With Elastic’s global managed testing infrastructure, you can create and run monitors in multiple locations without having to manage your own infrastructure. Elastic takes care of software updates and capacity planning for you.
46+
* **{{private-location}}s**: {{private-location}}s allow you to run monitors from your own premises. To use {{private-location}}s you must create a {{private-location}} before continuing. For step-by-step instructions, refer to [Monitor resources on private networks](../../../solutions/observability/apps/monitor-resources-on-private-networks.md).
47+
48+
% Stateful only for following note?
49+
50+
::::{note}
51+
If you are setting up Synthetics for a deployment configured with [traffic filters](../../../deploy-manage/security/traffic-filtering.md), connections into {{es}} are restricted and results will not be able to be written back into {{es}} unless granted. For more details, refer to [Use Synthetics with traffic filters](../../../solutions/observability/apps/use-synthetics-with-traffic-filters.md).
52+
53+
::::
54+
55+
56+
## Create a Synthetics project [synthetics-get-started-project-create-a-synthetics-project]
57+
58+
Start by creating your first Synthetics project. Run the command below to create a new Synthetics project named `synthetic-project-test` in the current directory.
59+
60+
```sh
61+
npx @elastic/synthetics init synthetic-project-test
62+
```
63+
64+
Then, follow the prompts on screen to set up the correct default variables for your Synthetics project. When complete, set the `SYNTHETICS_API_KEY` environment variable in your terminal, which is used to connect to your Observability project:
65+
66+
::::{tab-set}
67+
:group: stack-serverless
68+
69+
:::{tab-item} Elastic Stack v9
70+
:sync: stack
71+
72+
1. To generate an API key:
73+
74+
1. Go to **Synthetics** in your Observability project.
75+
2. Click **Settings**.
76+
3. Switch to the **Project API Keys** tab.
77+
4. Click **Generate Project API key**.
78+
79+
::::{important}
80+
To generate a Project API key, you must be logged in as a user with [Editor](../../../solutions/observability/apps/grant-users-access-to-secured-resources.md) access.
81+
82+
::::
83+
84+
85+
:::{image} ../../../images/serverless-synthetics-monitor-management-api-key.png
86+
:alt: Project API Keys tab in Synthetics settings
87+
:class: screenshot
88+
:::
89+
90+
::::{note}
91+
To use an API key to push to Elastic’s global managed testing infrastructure, the *Elastic managed locations enabled* toggle must be on when generating the API key. If the *Elastic managed locations enabled* toggle is disabled, an administrator has restricted access to Elastic’s global managed testing infrastructure.
92+
93+
::::
94+
95+
2. Set the `SYNTHETICS_API_KEY` environment variable in your terminal. You will most likely want to set this permanently. This is done differently in [Powershell](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.2#saving-changes-to-environment-variables) and [Bash](https://unix.stackexchange.com/a/117470).
96+
97+
Then, take a look at key files and directories inside your Synthetics project:
98+
99+
* `journeys` is where you’ll add `.ts` and `.js` files defining your browser monitors. When you create a new Synthetics project, this directory will contain files defining sample monitors.
100+
* `lightweight` is where you’ll add `.yaml` files defining your lightweight monitors. When you create a new Synthetics project, this directory will contain a file defining sample monitors.
101+
* `synthetics.config.ts` contains settings for your Synthetics project. When you create a new Synthetics project, it will contain some basic configuration options that you can customize later.
102+
103+
::::{note}
104+
The `synthetics.config.ts` in the sample Synthetics project uses a location on Elastic’s global managed testing infrastructure. Administrators can restrict access to Elastic’s global managed testing infrastructure. When you attempt to [`push` the sample monitors](../../../solutions/observability/apps/create-monitors-with-project-monitors.md#observability-synthetics-get-started-project-test-and-connect-to-your-observability-project), if you see an error stating that you don’t have permission to use Elastic managed global locations, refer to the [troubleshooting guide](../../../troubleshoot/observability/troubleshooting-synthetics.md#synthetics-troubleshooting-no-locations) for guidance.
105+
106+
::::
107+
108+
* `package.json` contains NPM settings for your Synthetics project. Learn more in the [NPM documentation](https://docs.npmjs.com/about-packages-and-modules).
109+
* `.github` contains sample workflow files to use with GitHub Actions.
110+
:::
111+
112+
:::{tab-item} Serverless
113+
:sync: serverless
114+
115+
1. To generate an API key:
116+
117+
1. Go to **Synthetics** in your Observability project.
118+
2. Click **Settings**.
119+
3. Switch to the **Project API Keys** tab.
120+
4. Click **Generate Project API key**.
121+
122+
::::{important}
123+
To generate a Project API key, you must be logged in as a user with [Editor](../../../solutions/observability/apps/grant-users-access-to-secured-resources.md) access.
124+
125+
::::
126+
127+
128+
:::{image} ../../../images/serverless-synthetics-monitor-management-api-key.png
129+
:alt: Project API Keys tab in Synthetics settings
130+
:class: screenshot
131+
:::
132+
133+
::::{note}
134+
To use an API key to push to Elastic’s global managed testing infrastructure, the *Elastic managed locations enabled* toggle must be on when generating the API key. If the *Elastic managed locations enabled* toggle is disabled, an administrator has restricted access to Elastic’s global managed testing infrastructure.
135+
136+
::::
137+
138+
2. Set the `SYNTHETICS_API_KEY` environment variable in your terminal. You will most likely want to set this permanently. This is done differently in [Powershell](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.2#saving-changes-to-environment-variables) and [Bash](https://unix.stackexchange.com/a/117470).
139+
140+
Then, take a look at key files and directories inside your Synthetics project:
141+
142+
* `journeys` is where you’ll add `.ts` and `.js` files defining your browser monitors. When you create a new Synthetics project, this directory will contain files defining sample monitors.
143+
* `lightweight` is where you’ll add `.yaml` files defining your lightweight monitors. When you create a new Synthetics project, this directory will contain a file defining sample monitors.
144+
* `synthetics.config.ts` contains settings for your Synthetics project. When you create a new Synthetics project, it will contain some basic configuration options that you can customize later.
145+
146+
::::{note}
147+
The `synthetics.config.ts` in the sample Synthetics project uses a location on Elastic’s global managed testing infrastructure. Administrators can restrict access to Elastic’s global managed testing infrastructure. When you attempt to [`push` the sample monitors](../../../solutions/observability/apps/create-monitors-with-project-monitors.md#observability-synthetics-get-started-project-test-and-connect-to-your-observability-project), if you see an error stating that you don’t have permission to use Elastic managed global locations, refer to the [troubleshooting guide](../../../troubleshoot/observability/troubleshooting-synthetics.md#synthetics-troubleshooting-no-locations) for guidance.
148+
149+
::::
150+
151+
* `package.json` contains NPM settings for your Synthetics project. Learn more in the [NPM documentation](https://docs.npmjs.com/about-packages-and-modules).
152+
* `.github` contains sample workflow files to use with GitHub Actions.
153+
154+
:::
155+
156+
::::
157+
158+
## Examine sample monitors [synthetics-get-started-project-examine-sample-monitors]
159+
160+
Inside the `lightweight` directory you’ll find sample lightweight monitors. Here’s an example of a YAML file defining a lightweight monitor:
161+
162+
```yaml
163+
# lightweight.yml
164+
heartbeat.monitors:
165+
- type: http
166+
name: Todos Lightweight
167+
id: todos-lightweight
168+
urls: "https://elastic.github.io/synthetics-demo/"
169+
schedule: '@every 1m'
170+
```
171+
172+
For more details on lightweight monitor configuration options, refer to [Configure lightweight monitors](../../../solutions/observability/apps/configure-lightweight-monitors.md).
173+
174+
Inside the `journeys` directory you’ll find sample browser monitors. Here’s an example of a TypeScript file defining a browser monitor:
175+
176+
```ts
177+
// example.journey.ts
178+
import { journey, step, monitor, expect } from '@elastic/synthetics';
179+
journey('My Example Journey', ({ page, params }) => {
180+
// Only relevant for the push command to create
181+
// monitors in Kibana or your serverless Observability project
182+
monitor.use({
183+
id: 'example-monitor',
184+
schedule: 10,
185+
});
186+
step('launch application', async () => {
187+
await page.goto(params.url);
188+
});
189+
step('assert title', async () => {
190+
const header = await page.locator('h1');
191+
expect(await header.textContent()).toBe('todos');
192+
});
193+
});
194+
```
195+
196+
For more details on writing journeys and configuring browser monitors, refer to [Scripting browser monitors](../../../solutions/observability/apps/scripting-browser-monitors.md).
197+
198+
199+
## Test and connect to your Observability project or Elastic Stack deployment[synthetics-get-started-project-test-and-connect-to-your-observability-project]
200+
201+
::::{tab-set}
202+
:group: stack-serverless
203+
204+
:::{tab-item} Elastic Stack v9
205+
:sync: stack
206+
207+
While inside the project directory you can do two things with the `npx @elastic/synthetics` command:
208+
209+
* Test browser-based monitors locally. To run all journeys defined in `.ts` and `.js` files:
210+
211+
```sh
212+
npx @elastic/synthetics journeys
213+
```
214+
215+
* Push all monitor configurations to an Elastic deployment. Run the following command from inside your project:
216+
217+
```sh
218+
npx @elastic/synthetics push --auth $SYNTHETICS_API_KEY --url <kibana-url>
219+
```
220+
221+
222+
One monitor will appear in the {{synthetics-app}} for each journey or lightweight monitor, and you’ll manage all monitors from your local environment. For more details on using the `push` command, refer to [`@elastic/synthetics push`](../../../solutions/observability/apps/use-synthetics-cli.md#elastic-synthetics-push-command).
223+
224+
::::{note}
225+
If you’ve [added a {{private-location}}](../../../solutions/observability/apps/monitor-resources-on-private-networks.md), you can `push` to that {{private-location}}.
226+
227+
To list available {{private-location}}s, run the [`elastic-synthetics locations` command](../../../solutions/observability/apps/use-synthetics-cli.md#elastic-synthetics-locations-command) with the {{kib}} URL for the deployment from which to fetch available locations.
228+
229+
::::
230+
231+
:::
232+
233+
:::{tab-item} Serverless
234+
:sync: serverless
235+
236+
While inside the Synthetics project directory you can do two things with the `npx @elastic/synthetics` command:
237+
238+
* Test browser-based monitors locally. To run all journeys defined in `.ts` and `.js` files:
239+
240+
```sh
241+
npx @elastic/synthetics journeys
242+
```
243+
244+
* Push all monitor configurations to an Observability project. Run the following command from inside your Synthetics project directory:
245+
246+
```sh
247+
npx @elastic/synthetics push --auth $SYNTHETICS_API_KEY --url <observability-project-url>
248+
```
249+
250+
251+
One monitor will appear in the Synthetics UI for each journey or lightweight monitor, and you’ll manage all monitors from your local environment. For more details on using the `push` command, refer to [`@elastic/synthetics push`](../../../solutions/observability/apps/use-synthetics-cli.md#elastic-synthetics-push-command).
252+
253+
::::{note}
254+
If you’ve [added a {{private-location}}](../../../solutions/observability/apps/monitor-resources-on-private-networks.md), you can `push` to that {{private-location}}.
255+
256+
To list available {{private-location}}s, run the [`elastic-synthetics locations` command](../../../solutions/observability/apps/use-synthetics-cli.md#elastic-synthetics-locations-command) with the URL for the Observability project from which to fetch available locations.
257+
258+
::::
259+
260+
:::
261+
262+
::::
263+
264+
265+
## View in the Synthetics UI [synthetics-get-started-project-view-in-your-observability-project]
8266
9-
% What needs to be done: Align serverless/stateful
267+
Then, go to **Synthetics** in your serverless Observability project or in {{kib}}. You should see your newly pushed monitors running. You can also go to the **Management** tab to see the monitors' configuration settings.
10268
11-
% Use migrated content from existing pages that map to this page:
269+
::::{note}
270+
When a monitor is created or updated, the first run might not occur immediately, but the time it takes for the first run to occur will be less than the monitor’s configured frequency. For example, if you create a monitor and configure it to run every 10 minutes, the first run will occur within 10 minutes of being created. After the first run, the monitor will begin running regularly based on the configured frequency. You can run a manual test if you want to see the results more quickly.
12271
13-
% - [ ] ./raw-migrated-files/observability-docs/observability/synthetics-get-started-project.md
14-
% - [ ] ./raw-migrated-files/docs-content/serverless/observability-synthetics-get-started-project.md
272+
::::
15273
16-
% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc):
17274
18-
$$$observability-synthetics-get-started-project-create-a-synthetics-project$$$
19275
20-
$$$observability-synthetics-get-started-project-test-and-connect-to-your-observability-project$$$
276+
## Next steps [observability-synthetics-get-started-project-next-steps]
21277
22-
$$$synthetics-get-started-project-init$$$
278+
Learn more about:
23279
24-
$$$synthetics-get-started-project-push$$$
280+
* [Configuring lightweight monitors](../../../solutions/observability/apps/configure-lightweight-monitors.md)
281+
* [Configuring browser monitors](../../../solutions/observability/apps/write-synthetic-test.md)
282+
* [Implementing best practices for working with Synthetics projects](../../../solutions/observability/apps/manage-monitors.md#synthetics-projects-best-practices)

0 commit comments

Comments
 (0)