diff --git a/docs/en/observability/synthetics-reference/lightweight-config/http.asciidoc b/docs/en/observability/synthetics-reference/lightweight-config/http.asciidoc index 0dbaa69eca..db3bc89d49 100644 --- a/docs/en/observability/synthetics-reference/lightweight-config/http.asciidoc +++ b/docs/en/observability/synthetics-reference/lightweight-config/http.asciidoc @@ -4,8 +4,8 @@ |=== | Option (type) | Description -// hosts -| [[monitor-http-hosts]] *`hosts`* +// urls +| [[monitor-http-urls]] *`urls`* (<>) a| *Required*. The URL to ping. @@ -70,7 +70,7 @@ a| The TLS/SSL connection settings for use with the HTTPS endpoint. If you don't - type: http id: my-http-service name: My HTTP Service - hosts: "https://myhost:443" + urls: "https://myhost:443" schedule: '@every 5s' ssl: certificate_authorities: ['/etc/ca.crt'] diff --git a/docs/en/serverless/transclusion/synthetics/reference/lightweight-config/http.asciidoc b/docs/en/serverless/transclusion/synthetics/reference/lightweight-config/http.asciidoc new file mode 100644 index 0000000000..3e38556266 --- /dev/null +++ b/docs/en/serverless/transclusion/synthetics/reference/lightweight-config/http.asciidoc @@ -0,0 +1,201 @@ +|=== +| Option (type) | Description + +| [[monitor-http-urls]]**`urls`** +(<>) +| **Required**. The URL to ping. + +| [[monitor-http-max_redirects]]**`max_redirects`** +(<>) +a| The total number of redirections Synthetics will follow. + +By default, Synthetics will not follow redirects, but will report the status of the redirect. If set to a number greater than `0`, Synthetics will follow that number of redirects. + +When this option is set to a value greater than `0`, the `monitor.ip` field will no longer be reported, as multiple DNS requests across multiple IPs may return multiple IPs. Fine-grained network timing data will also not be recorded, as with redirects that data will span multiple requests. Specifically the fields `http.rtt.content.us`, `http.rtt.response_header.us`, `http.rtt.total.us`, `http.rtt.validate.us`, `http.rtt.write_request.us` and `dns.rtt.us` will be omitted. + +**Default**: `0` + +| [[monitor-http-proxy_headers]]**`proxy_headers`** +| Additional headers to send to proxies during `CONNECT` requests. + +| [[monitor-http-proxy_url]]**`proxy_url`** +(<>) +a| The HTTP proxy URL. This setting is optional. + +**Example**: + +[source,yaml] +---- +http://proxy.mydomain.com:3128 +---- + +| [[monitor-http-username]]**`username`** +(<>) +a| The username for authenticating with the server. The credentials are passed with the request. This setting is optional. + +You need to specify credentials when your `check.response` settings require it. For example, you can check for a 403 response (`check.response.status: [403]`) without setting credentials. + +| [[monitor-http-password]]**`password`** +(<>) +| The password for authenticating with the server. This setting is optional. + +| [[monitor-http-ssl]]**`ssl`** +({heartbeat-ref}/configuration-ssl.html[SSL]) +a| The TLS/SSL connection settings for use with the HTTPS endpoint. If you don't specify settings, the system defaults are used. + +**Example**: + +[source,yaml] +---- +- type: http + id: my-http-service + name: My HTTP Service + urls: "https://myhost:443" + schedule: '@every 5s' + ssl: + certificate_authorities: ['/etc/ca.crt'] + supported_protocols: ["TLSv1.0", "TLSv1.1", "TLSv1.2"] +---- + +| [[monitor-http-headers]]**`headers`** +(<>) +a| Controls the indexing of the HTTP response headers `http.response.body.headers` field. Set `response.include_headers` to `false` to disable. + +**Default**: `true` + +| [[monitor-http-response]]**`response`** +a| Controls the indexing of the HTTP response body contents to the `http.response.body.contents` field. + +**`include_body`** (`"on_error"`, `"never"`, or `"always"`):: +Set `response.include_body` to one of the following: ++ +* `on_error`: Include the body if an error is encountered during the check. This is the default. +* `never`: Never include the body. +* `always`: Always include the body with checks. + +**`include_body_max_bytes`** (<>):: +Set `response.include_body_max_bytes` to control the maximum size of the stored body contents. ++ +**Default**: `1024` + +| [[monitor-http-check]]**`check`** +a| **`request`**:: +An optional `request` to send to the remote host. Under `check.request`, specify these options: ++ +-- +**`method`** (`"HEAD"`, `"GET"`, `"POST"`, or `"OPTIONS"`)::: +The HTTP method to use. + +**`headers`** (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers[HTTP headers])::: +A dictionary of additional HTTP headers to send. By default Synthetics will set the 'User-Agent' header to identify itself. + +**`body`** (<>)::: +Optional request body content. +-- ++ +**Example**: This monitor POSTs an `x-www-form-urlencoded` string to the endpoint `/demo/add`. ++ +[source,yaml] +---- +check.request: + method: POST + headers: + 'Content-Type': 'application/x-www-form-urlencoded' + # urlencode the body: + body: "name=first&email=someemail%40someemailprovider.com" +---- + +**`response`**:: +The expected `response`. ++ +Under `check.response`, specify these options: ++ +**`status`** (list of <>s)::: +A list of expected status codes. 4xx and 5xx codes are considered `down` by default. Other codes are considered `up`. ++ +**Example**: ++ +[source,yaml] +---- +check.response: + status: [200, 201] +---- + +**`headers`** (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers[HTTP headers])::: +The required response headers. + +**`body.positive`** (list of <>s)::: +A list of regular expressions to match the body output. Only a single expression needs to match. ++ +**Example**: ++ +This monitor examines the response body for the strings 'foo' or 'Foo': ++ +[source,yaml] +---- +check.response: + status: [200, 201] + body: + positive: + - foo + - Foo +---- + +**`body.negative`** (list of <>s)::: +A list of regular expressions to match the body output negatively. Return match failed if single expression matches. HTTP response bodies of up to 100MiB are supported. ++ +This monitor examines match successfully if there is no 'bar' or 'Bar' at all, examines match failed if there is 'bar' or 'Bar' in the response body: ++ +**Example**: ++ +[source,yaml] +---- +check.response: + status: [200, 201] + body: + negative: + - bar + - Bar +---- ++ +**Example**: ++ +This monitor examines match successfully only when 'foo' or 'Foo' in body AND no 'bar' or 'Bar' in body: ++ +[source,yaml] +---- +check.response: + status: [200, 201] + body: + positive: + - foo + - Foo + negative: + - bar + - Bar +---- + +**`json`**::: +A list of expressions executed against the body when parsed as JSON. +Body sizes must be less than or equal to 100 MiB. ++ +**`description`**:::: +A description of the check. + +**`expression`**:::: +The following configuration shows how to check the response using +https://github.com/PaesslerAG/gval/blob/master/README.md[gval] expressions +when the body contains JSON: ++ +**Example**: ++ +[source,yaml] +---- +check.response: + status: [200] + json: + - description: check status + expression: 'foo.bar == "myValue"' +---- + +|===