Service Check Datasets

Service check datasets define what a Website writes beside its results. In Datasets & Profiles they are filed under Website. To create and assign datasets through the web interface, see Management. For the dataset and profile model, see Overview.

The results are no dataset. Every service check device checks its service on its own interval and writes the result itself, up or down, with the state the service is in: no dataset carries the results, and none can be assigned to have them. See Results and State.

A check has no datasets. An HTTP Check, a TCP Check, a DNS Check, an ICMP Check, and a TLS Check each write their results directly, and have no dataset to assign: every result of an HTTP or a TLS Check carries the service's certificate and the certificate of its chain that expires first. See Retired Datasets.

Collector Types

One dataset per data model, each with its own definition id, event.dataset, and pipeline:

Dataset (console title)	event.dataset	Definition	Definition id	Kind	Default interval	Minimum	Device types
Website Console	website.console	website_console_collector	63	log	60 s	30 s	website
Website HAR	website.har	website_har_collector	64	log	300 s	30 s	website
Website Coach	website.coach	website_coach_collector	65	log	3600 s	300 s	website
Website Filmstrip	website.filmstrip	website_filmstrip_collector	66	log	300 s	30 s	website
Website Screenshot	website.screenshot	website_screenshot_collector	68	log	60 s	30 s	website
Website Synthetic Check	website.synthetic	website_synthetic_collector	854	log	300 s (60 s with a cron)	60 s	website
Traceroute	traceroute	traceroute_collector	12101	inventory	3600 s	300 s	website

A website's page loads and synthetic runs go to the application log table, and its traceroute to the inventory table. Every dataset is named after the website but Traceroute, which keeps the name its records carried when the HTTP, TCP, ICMP, and TLS Checks shared it.

Every dataset takes these properties:

Field	Required	Type	Default	Description
interval	N	int	see above	Seconds between readings. At least the minimum above
pipeline_name	N	string	the device's	The preprocessing pipeline the dataset's records enter. One that was not shipped to the Director falls back to the device's, and the device's log says so once

Rules

• Checks. A dataset assigned to an HTTP, a TCP, a DNS, an ICMP, or a TLS Check is left out with a warning in the device's log, and the check writes its results as before: dataset 21 (traceroute_collector) is left out: tcp_check devices do not write it, website devices do. In the console, a check has no Data collection step in its wizard and no Data collection tab on its page.
• Intervals. An interval under the minimum, or not a whole number, is left out with a warning in the device's log.
• One of each. A dataset assigned twice is read once, the first assignment deciding its settings — but for Website Synthetic Check: each is a script, and a device runs every one assigned to it.
• Failures stay apart. The results and each dataset read on their own interval, each reading making its own check. What goes wrong in one of them is its alone: the others go on.

Inventories Are Marked

From an inventory dataset's second reading on, every record says how it compares with the dataset's last delivered reading:

event.action	event.type	Meaning
added	creation	New since the last reading
changed	change	Its key is there, and something else of it differs
unchanged	info	As it was
removed	deletion	Gone: its last record is written once more, as it was

The first reading after a start marks nothing: the last reading is kept in memory, so a restart, or a move to another Director, starts over. A reading whose records could not all be written never becomes the one the next compares with, so no change goes unreported.

Results and State

Every service check device writes the result of every check itself, on its interval, with no dataset: a record per check, up or down. A route carries a device's records by the device, never by a dataset, so it carries the results as it carries a listener's records. The results go through the device's pre-processing pipeline.

Device type	event.dataset	Definition id	Table	Interval (default / floor)
HTTP Check	http_check	12150	metric	60 / 10 s
TCP Check	tcp_check	12151	metric	60 / 10 s
DNS Check	dns_check	12152	metric	60 / 10 s
ICMP Check	icmp_check	12153	metric	60 / 10 s
Website	website	12154	metric	60 / 30 s
TLS Check	tls_check	12155	metric	60 / 10 s

Each device type's page lists the fields of its result.

State

Every result says the state the service is in, as Elastic Heartbeat writes it. A state is a run of one status: it begins at the check that first finds the service up, or down, and goes on while every check finds it the same. There is no state dataset.

Field	What it is
state.id	The state's id, the same on every result of the run: the device's id and when the state began, in hexadecimal Unix milliseconds (512300181-1a0e74bce20)
state.status	up or down: the status of every check of the state, this one's included
state.started_at	When the state began: the check that began it
state.duration_ms	How long the state has lasted, from its start to this check, in milliseconds
state.checks	How many checks the state has had, this one included
state.up, state.down	How many of them found the service up, and down
state.changed	true on the first result after the service went down or came back up; false otherwise
state.previous.status	On that first result: the status of the state it ended
state.previous.duration_ms	On that first result: how long the state it ended lasted, in milliseconds

A device's first result begins a state with no previous one: state.changed is false, and state.checks is 1. So:

• to alert on a service going down, alert on state.changed: true with state.status: down;
• to alert on a service found down, whether or not it just went, alert on state.status: down with state.checks: 1.

The state outlives the device's collector. It is kept in the Director cluster's replicated store for a week past its last write:

• A restart of the device (every configuration change restarts it) or of the Director, and a move to another Director of the cluster, go on with the state where the device left it. A change that happened while the device was stopped is written once, at its first result.
• A stop writes nothing and changes nothing: the time the device was stopped counts in the state's duration when it starts again and finds the service the same. A device stopped for more than a week lets its state expire, and its first result then begins a new one.
• A check that could not be made — a failure on the Director's side, such as credentials that do not resolve, no resolver, a Director that may not send ICMP, or no browser — writes no result, is not counted, and changes no state. The device's connection state says what went wrong.
• A device edited to check another service begins a state of its own.

The state is stored when it begins, otherwise at most every five minutes, and when the device stops. After a crash the counts may lag by the checks of those minutes, never the state's id, start, or status.

Common Fields

Every record is one ECS 8.11 document:

• @timestamp (when the check began), ecs.version, event.module (the device type: website, http_check, tcp_check, dns_check, icmp_check, tls_check), event.dataset, event.kind (metric for a result, event for what a page load found and a synthetic step, state for an inventory record), event.category (web and network for an HTTP Check and a website, network for the others), event.outcome (success up, failure down), and event.duration (the check's, in nanoseconds).
• The observer is the check: observer.vendor (VirtualMetric), observer.product (Website, HTTP Check, TCP Check, DNS Check, ICMP Check, TLS Check), observer.name (the device), and observer.hostname (the Director it ran on, since a check's answer depends on where it is made from).
• What ECS has no name for is under service_check.*, the namespace the six device types share, so a pipeline or a search reads one name for one thing whichever device wrote it. service_check.kind (http, tcp, dns, icmp, browser, tls), service_check.status (up, down), and service_check.target (the URL, host:port, the host, or <name> <type> @<resolver>) are on every record, and error.type and error.message on one that is down.
• Durations are whole microseconds ({"us": 1234}), and a share is a fraction of 1. A value the check did not measure is left out, never written as zero.

Website Page Loads

The Website Console, HAR, Coach, Filmstrip, and Screenshot datasets write what a page load found, a record per thing found, each with url.* (the page) and the load's service_check.kind, target, and status. Datasets due within a second of each other share one load, and the load captures only what they ask for.

Dataset	One record per	Fields
Website Console	Console warning or error, uncaught exception, or request that got no answer	log.level (warning, error), message, error.type (exception), error.message, error.stack_trace; service_check.console.type (console, exception, browser, request), source, arguments (a console call's arguments as a JSON array), location.url, line, column, function (where it happened), request.url, method, resource_type, error, blocked_reason
Website HAR	Request of the page, a HAR entry each	event.start, event.duration, event.outcome (failure for no answer or a status of 400 or more), url.* (masked), http.request.method, http.response.status_code, mime_type, bytes, body.bytes, http.version, destination.ip, port, error.message; service_check.har.sequence, resource_type, main (a hop of the main document), timings.blocked, dns, connect, ssl, send, wait, receive, status_text, cache, redirect_url, content.bytes, compression.bytes, failed, error, blocked_reason, canceled, pending, initiator.*
Website Coach	A summary, then each piece of advice	Summary: service_check.coach.type, version (coach-core's), score, categories.<category>.score, advice.count, failing, severities.<severity>, info, errors. Advice: service_check.coach.advice.id, title, description, text, score, weight, severity, category, tags, offending (at most 20), offending_total
Website Filmstrip	Page load	service_check.filmstrip.frames (each data, a JPEG as base64, mime_type, width, height, bytes, time from the navigation's start, progress in percent), painted, visual.first_change, last_change, complete_85, speed_index
Website Screenshot	Page load	service_check.screenshot.thumbnail and full (each data, a JPEG as base64, mime_type, width, height, bytes; full.reason: first, changed, or failed, full.scaled, or full.left_out: too_large), hash (the viewport's 256-bit perceptual hash), change.distance, threshold, changed

• Website Console keeps nothing below a warning. At most 200 records a load, the rest counted in the device's log; a text or a stack is cut at 8 KiB, and says so.
• Website HAR writes every hop of a redirect as an entry, at most 1000 a load, and never a header, a cookie, or a query string: they carry credentials.
• Website Coach is the sitespeed.io coach, coach-core 9.2.1: its DOM advice evaluated in the loaded page, and its HAR advice evaluated on the load's own HAR. The Director needs no Node. Its technology detection and its two CPU rules are left out.
• Website Filmstrip comes from the browser's screencast of the page building up, at the thumbnail's width, with at most filmstrip_frames frames evenly spaced from the navigation's start to the last visual change. Its visual metrics are speedline's: first and last visual change, visually complete 85, and the Speed Index.
• Website Screenshot writes a thumbnail at every reading. The full viewport goes into the record too at the first reading, when the check failed, and when the page visibly changed since the last full screenshot: its perceptual hash moved change_threshold bits or more. The last full screenshot's hash is kept in the cluster's replicated store, so a restart, or a move to another Director, does not take the page it left for a change.

Pictures are bounded, never cut. A record past the device's max_record_bytes has its full screenshot, then its thumbnail, scaled down to three quarters of its width at each try, and a filmstrip its frames scaled down, then fewer of them, until it fits. One that still does not fit is left out, with its reason kept and a warning in the device's log.

tip

A picture is still a large record. Route the Website Screenshot and Website Filmstrip datasets to a target that takes large records, such as blob storage, and leave the SIEM the results, the console, and the requests.

Website Synthetic Check

A Website Synthetic Check dataset is a script the website runs in a page of its own, step by step. The script is the definition's transaction, one step per line:

Step	What it does
vm.visit('<url>');	Loads the URL, and waits until the page's network is almost idle
vm.get('<selector>').type('<text>');	Waits for document.querySelector('<selector>'), sets its value to the text, and sends it a keyup event
vm.get('<selector>').click();	Waits for the element, and clicks it. .submit() in .click()'s place clicks too: a form is submitted by clicking its button
vm.url().should('contains', '<text>');	Waits until the page's URL holds the text

• A selector is any CSS selector the page's querySelector takes. The text typed is a JavaScript string, quoted, with a quote inside it escaped ('it\'s'). A step ends with ); as shown.
• A step waits for its element, or its URL, up to 30 tries a second apart, and fails without it. A click whose element never comes, after a click and before a vm.url step, passes when that URL check does: the click before it has already left the page.
• The steps run in order until one fails, and the steps after it do not run. A line that is none of the four is written as a step with no type that did not pass, and the run goes on. A blank line is no step.
• After each step that passes, the whole page is taken as its screenshot, a JPEG fitted to the device's max_record_bytes.
• Each run's page is in a browser context of its own, closed with the run, so every run starts signed out. It is laid out at the device's viewport.

Field	Required	Type	Default	Description
transaction	Y	string	-	The script, a step per line. One that is a single ${ENV_VAR} reference takes the variable's value when a run begins
timeout	N	int	300	Seconds a run may take, its page loads and every step's waits among them, from 1 to 3600
interval	N	int	300; 60 with a cron	Seconds between runs, or with a cron between checks of it. At least 60: a run is heavy, so a synthetic check runs once a minute at the most
cron	N	string	-	A cron expression (five fields, or Quartz's six or seven) the runs follow, checked every minute. Empty or 0 is none; a whole number is the seconds between runs, at least 60
max_retries	N	int	1	With a cron: how many times a run that could not be made, or not written, is tried again before the fire waits for the next
skippable	N	bool	true	With a cron: false runs every fire missed while the device was stopped, one a reading; true runs the latest alone
pipeline_name	N	string	the device's	The preprocessing pipeline the dataset's records enter

An interval under a minute, or a cron that is a number of seconds under 60, leaves the dataset out with a warning in the device's log. In the console the schedule is the standard switch: an interval in minutes, or a custom cron. With a cron, the fire is committed to the cluster's replicated store once the run was made and its records written, so a restart, or a move to another Director, resumes the schedule.

Credentials. A run's page sends one of the device's credentials — basic authentication, else its headers, else its HMAC header — and only to the device's URL and the pages its script visits, each matched by scheme, host, and port. A third party the page loads, or another site a link or a redirect leads to, gets none. See Credentials for Synthetic Runs.

A value typed is never written. A type step's text is masked as **** in every field of every record and in the device's log (vm.get('#password').type('****');). The dataset keeps the script as it is written, and the API returns it as every dataset's definition, so keep a script that types a password in the Director's environment: transaction: "${SHOP_LOGIN_SCRIPT}". No reference inside a script is resolved.

A run moves nothing of the device's state, which follows the page loads: a site that fails a run is the run's records' finding (event.outcome: failure), and the device's log says at which step.

Records

Fields

A step the run ran

@timestamp (when the run began), event.action (the step's type), event.outcome (success when the step passed), event.type (info, error), event.start, event.duration, error.message, url.* (a visit's URL, masked); service_check.synthetic.step.number (from 1), type (navigate, type, click, urlcheck), text (the step as written), action, previous, next, status (OK, Error), duration, screenshot (data, a JPEG as base64, mime_type, width, height, bytes, full_page, scaled, or left_out: too_large); and the run's run.outcome (success when every step ran and passed), steps, ran, passed, timed_out. service_check.status is the run's: up when it passed

Retired Datasets

HTTP Check Certificates (http_check_certificate_collector, definition id 12100) and TLS Check Certificates (tls_check_certificate_collector, 12102) are retired, and their ids are not reused. Each made a check of its own, and wrote every certificate the service presented, a record each. A check needs neither now: every result of an HTTP Check or a TLS Check carries the service's certificate (tls.server.x509.*, tls.server.hash.sha256), its days left, and the certificate of its chain that expires first, with its days left.

One still assigned reads nothing, and the device's log says so when the device starts:

dataset 7 (http_check_certificate_collector) is left out: that dataset type is retired, since every result carries the certificate the service presents: unassign it

Unassign it: the device's other datasets, and its results, are not affected.

Traceroute

A Traceroute dataset traces the route to the host of the website's URL. The host is resolved at every trace, to its first address. A trace makes no check, and moves nothing of the device's state.

A check has no Traceroute. An HTTP, a TCP, an ICMP, and a TLS Check traced the host they reach until the checks lost their datasets; one still assigned to a check is left out with a warning in the device's log.

A trace sends ICMP echo requests whose TTL (an IPv6 hop limit) goes up one hop at a time, as tracert does, through the same sockets an ICMP Check opens — see Permission to Ping. Nothing is run through a shell. A Director that may not send ICMP, a host that does not resolve, and a Director with no route to the host's network fail the reading, write no record, and say why in the device's log.

• Gentle on routers. Each hop's probes go one at a time, and never sooner than 100 ms after the last began: ten a second at most, never two in flight.
• End. The trace ends when the host answers (reached), when a hop answers with a destination unreachable (unreachable), at the last hop (max_hops), or when its time runs out (timeout), keeping the hops it traced.
• Names. The names of the hops' addresses are asked while the trace goes on, through a PTR question to the resolver the Director's system lists first.

Field	Required	Type	Default	Description
interval	N	int	3600	Seconds between traces. At least 300, which is never shorter than a trace may take
max_hops	N	int	30	The TTL of the last hop probed, from 1 to 64
probes	N	int	3	Echo requests each hop is sent, from 1 to 10
probe_timeout	N	int	2	Seconds each probe waits for what answers it, from 1 to 10
trace_timeout	N	int	120	Seconds the whole trace may take, from 10 to 300, and no shorter than probe_timeout
pipeline_name	N	string	the device's	The preprocessing pipeline the dataset's records enter

How long a trace takes. A hop that answers costs about a third of a second; a hop no probe of which is answered costs probes × probe_timeout, six seconds by default. A host that drops echo requests leaves every hop past the last router silent, and the trace runs until trace_timeout.

Dataset	One record per	Fields
Traceroute	Hop	event.kind state, event.action, event.duration (the trace's); destination.address, ip (the host traced); network.transport (icmp, ipv6-icmp); related.ip, hosts; service_check.traceroute.hop (the TTL, the key), ip (the address that answered), names (its PTR records), reply (time_exceeded: a router on the way, echo_reply: the host, unreachable), unreachable (network, host, protocol, port, prohibited, or the ICMP code), probes, lost, rtt (each answered probe's round trip, in order), trace.end, trace.hops

Each hop is keyed by its number: a router that answers a hop in another's place changed it, a longer route adds hops, and a shorter one removes them. A hop no probe of which was answered has no ip, reply, or rtt; it is written as it is, marked with nothing, and the next trace compares with what the last one that heard it found.

Examples

Tracing the route to a shop's host every two hours, with a shorter probe timeout...

devices: - id: 512300189 name: shop-route type: website status: true properties: url: "https://shop.example.com/" definitions: - name: traceroute_collector properties: interval: 7200 probe_timeout: 1

Running a search script against a shop every ten minutes, with a two-minute timeout...

devices: - id: 512300184 name: shop-browser type: website status: true properties: url: "https://shop.example.com/" definitions: - name: website_synthetic_collector properties: transaction: | vm.visit('https://shop.example.com/'); vm.get('#search').type('coffee grinder'); vm.get('#search-button').click(); vm.url().should('contains', '/search'); timeout: 120 interval: 600