diff --git a/docs/en/uptime/deployment-arch.asciidoc b/docs/en/uptime/deployment-arch.asciidoc new file mode 100644 index 0000000000..d8edf290b9 --- /dev/null +++ b/docs/en/uptime/deployment-arch.asciidoc @@ -0,0 +1,25 @@ +[role="xpack"] +[[uptime-deployment-arch]] +== Deployment Architecture + +There are multiple ways to deploy Uptime and Heartbeat. +Use the information in this section to determine the best deployment for you. +A guiding principle is that an outage that takes down the service being monitored should not also take down Heartbeat. +You want Heartbeat to be functioning even when your service is not, so the guidelines here help you maximise this possibility. + +Heartbeat is generally run as a centralized service within a data center. +While it is possible to run it as a separate "sidecar" process paired with each process/container, we recommend against it. +Running Heartbeat centrally ensures you will still be able to see monitoring data in the event of an overloaded, disconnected, or otherwise malfunctioning server. + +For further redundancy, you may want to deploy multiple Heartbeats across geographic and/or network boundaries to provide more data. + Specify Heartbeat's observer {heartbeat-ref}/configuration-observer-options.html[geo options] to do so. Some examples might be: + +* **A site served from a content delivery network (CDN) with points of presence (POPs) around the globe:** +In this case you may want to have multiple Heartbeat instances at different data centers around the world checking to see if your site is reachable via local CDN POPs. +* **A service within a single data center that is accessed across multiple VPNs:** +Set up one Heartbeat instance within the VPN the service operates from, and another within an additional VPN that users access the service from. +Having both instances will help pinpoint network errors in the event of an outage. +* **A single service running primarily in a US east coast data center, with a hot failover located in a US west coast data center:** +In each data center, run a Heartbeat instance that checks both the local copy of the service and its counterpart across the country. +Set up two monitors in each region, one for the local service and one for the remote service. +In the event of a data center failure it will be immediately obvious if the service had a connectivity issue to the outside world or if the failure was only internal. diff --git a/docs/en/uptime/images/uptime-multi-deployment.png b/docs/en/uptime/images/uptime-multi-deployment.png new file mode 100644 index 0000000000..5440d91e48 Binary files /dev/null and b/docs/en/uptime/images/uptime-multi-deployment.png differ diff --git a/docs/en/uptime/images/uptime-setup.png b/docs/en/uptime/images/uptime-setup.png new file mode 100644 index 0000000000..398125202f Binary files /dev/null and b/docs/en/uptime/images/uptime-setup.png differ diff --git a/docs/en/uptime/images/uptime-simple-deployment.png b/docs/en/uptime/images/uptime-simple-deployment.png new file mode 100644 index 0000000000..f46dfdb2b8 Binary files /dev/null and b/docs/en/uptime/images/uptime-simple-deployment.png differ diff --git a/docs/en/uptime/index.asciidoc b/docs/en/uptime/index.asciidoc new file mode 100644 index 0000000000..7bbc01bb30 --- /dev/null +++ b/docs/en/uptime/index.asciidoc @@ -0,0 +1,15 @@ +// short-version can be: 8, 7, 6, etc. +:short-version: 8 + +include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[] +include::{asciidoc-dir}/../../shared/attributes.asciidoc[] + += Uptime monitoring guide + +include::overview.asciidoc[] + +include::install.asciidoc[] + +include::deployment-arch.asciidoc[] + +include::security.asciidoc[] diff --git a/docs/en/uptime/install.asciidoc b/docs/en/uptime/install.asciidoc new file mode 100644 index 0000000000..e7c50bb760 --- /dev/null +++ b/docs/en/uptime/install.asciidoc @@ -0,0 +1,69 @@ +[[install-uptime]] +== Install Uptime + +The easiest way to get started with Elastic Uptime is by using our hosted {es} Service on Elastic Cloud. +The {es} Service is available on both AWS and GCP, +and automatically configures {es} and {kib}. + +[float] +=== Hosted Elasticsearch Service + +Skip managing your own {es} and {kib} instance by using our +https://www.elastic.co/cloud/elasticsearch-service[hosted {es} Service] on +Elastic Cloud. + +{ess-trial}[Try out the {es} Service for free], +then jump straight to <>. + +[float] +[[before-installation]] +=== Install the stack yourself + +If you'd rather install the stack yourself, +first see the https://www.elastic.co/support/matrix[Elastic Support Matrix] for information about supported operating systems and product compatibility. + +* <> +* <> +* <> + +[[install-elasticsearch]] +=== Step 1: Install Elasticsearch + +Install an Elasticsearch cluster, start it up, and make sure it's running. + +. Verify that your system meets the +https://www.elastic.co/support/matrix#matrix_jvm[minimum JVM requirements] for {es}. +. {stack-gs}/get-started-elastic-stack.html#install-elasticsearch[Install Elasticsearch]. +. {stack-gs}/get-started-elastic-stack.html#_make_sure_elasticsearch_is_up_and_running[Make sure elasticsearch is up and running]. + +[[install-kibana]] +=== Step 2: Install Kibana + +Install Kibana, start it up, and open up the web interface: + +. {stack-gs}/get-started-elastic-stack.html#install-kibana[Install Kibana]. +. {stack-gs}/get-started-elastic-stack.html#_launch_the_kibana_web_interface[Launch the Kibana Web Interface]. + +[[install-heartbeat]] +=== Step 3: Install and configure Heartbeat + +Uptime requires the setup of monitors in Heartbeat. +These monitors provide the data you'll be visualizing in the {kibana-ref}/xpack-uptime.html[Uptime UI]. + +See the *Setup Instructions* in Kibana for instructions on installing and configuring Heartbeat. +Additional information is available in {heartbeat-ref}/heartbeat-configuration.html[Configure Heartbeat]. + +[role="screenshot"] +image::images/uptime-setup.png[Installation instructions on the Uptime page in Kibana] + +[float] +==== Important considerations + +* Make sure you're using the same major versions of Heartbeat and Kibana. + +* Index patterns tell Kibana which Elasticsearch indices you want to explore. +The Uptime UI requires a +heartbeat-{short-version}*+ index pattern. +If you have configured a different index pattern, you can use {ref}/indices-aliases.html[index aliases] to ensure data is recognized by the UI. + +After you install and configure Heartbeat, +the {kibana-ref}/xpack-uptime.html[Uptime UI] will automatically populate with the Heartbeat monitors. diff --git a/docs/en/uptime/overview.asciidoc b/docs/en/uptime/overview.asciidoc new file mode 100644 index 0000000000..c6bd71b1f5 --- /dev/null +++ b/docs/en/uptime/overview.asciidoc @@ -0,0 +1,53 @@ +[role="xpack"] +[[uptime-overview]] +== Elastic Uptime overview + +Elastic Uptime allows you to monitor the availability and response times of applications and services in real time and to detect problems before they affect users. + +Elastic Uptime can help you to understand uptime and response time characteristics for your services and applications. +It can be deployed both inside and outside your organization's network, so you can analyze problems from multiple vantage points. + +Elastic Uptime uses these components: *Heartbeat*, *Elasticsearch* and *Kibana*. + +[float] +=== Heartbeat + +{heartbeat-ref}/index.html[Heartbeat] is an open source data shipper that performs uptime monitoring. +Elastic Uptime uses Heartbeat to collect monitoring data from your target applications and services, and ship it to Elasticsearch. + +[float] +=== Elasticsearch + +{ref}/index.html[Elasticsearch] is a highly scalable, open source, search and analytics engine. +Elasticsearch can store, search, and analyze large volumes of data in near real-time. +Elastic Uptime uses Elasticsearch to store monitoring data from Heartbeat in Elasticsearch documents. + +[float] +=== Kibana + +{kibana-ref}/index.html[Kibana] is an open source analytics and visualization platform designed to work with Elasticsearch. +You can use Kibana to search, view, and interact with data stored in Elasticsearch. +You can easily perform advanced data analysis and visualize your data in a variety of charts, tables, and maps. + +The {kibana-ref}/xpack-uptime.html[Elasticsearch Uptime app] in Kibana provides a dedicated user interface for viewing uptime data and identifying problem areas. + +[float] +=== Example deployments +// ++ I like the Infra/logging diagram which shows Metrics and Logging apps as separate components inside Kibana +// ++ In diagram, should be Uptime app, not Uptime UI, possibly even Elastic Uptime? Also applies to Metrics/Logging/APM. +// ++ Need more whitespace around components. + +image::images/uptime-simple-deployment.png[Uptime simple deployment] + +In this simple deployment, a single instance of Heartbeat is deployed at a single monitoring location to monitor a single service. +The Heartbeat instance sends the monitoring data to Elasticsearch. +Then you can use the Uptime app in Kibana to view the data from Heartbeat and determine the status of the service. + +image::images/uptime-multi-deployment.png[Uptime multiple server deployment] + +In this deployment, two instances of Heartbeat are deployed at two different monitoring locations. +Both instances monitor the same service. +The Heartbeat instances send the monitoring data to Elasticsearch. +As before, you can use the Uptime app in Kibana to view the Heartbeat data and determine the status of the service. +When a failure occurs, the multiple monitoring locations enable you to pinpoint the area in which the failure has occurred. + diff --git a/docs/en/uptime/security.asciidoc b/docs/en/uptime/security.asciidoc new file mode 100644 index 0000000000..16b3c59b92 --- /dev/null +++ b/docs/en/uptime/security.asciidoc @@ -0,0 +1,60 @@ +[[uptime-security]] +== Elasticsearch Security + +If you use Elasticsearch security, you'll need to enable certain privileges for users +that would like to access the Uptime app. For example, create user and support roles to implement the privileges: + +[float] +=== Create a role + +You'll need a role that lets you access the Heartbeat indices, which by default are `heartbeat-*`. +You can create this with the following request: + +["source","sh",subs="attributes,callouts"] +--------------------------------------------------------------- +PUT /_security/role/uptime +{ "indices" : [ + { + "names" : [ + "heartbeat-*" + ], + "privileges" : [ + "read", + "view_index_metadata" + ], + "field_security" : { + "grant" : [ + "*" + ] + }, + "allow_restricted_indices" : false + } + ], + "transient_metadata" : { + "enabled" : true + } +} +--------------------------------------------------------------- +// CONSOLE + +[float] +=== Assign the role to a user + +Next, you'll need to create a user with both the `uptime` role, and another role with sufficient {kibana-ref}/kibana-privileges.html[Kibana privileges], +such as the `kibana_user` role. +You can do this with the following request: + +["source","sh",subs="attributes,callouts"] +--------------------------------------------------------------- +PUT /_security/user/jacknich +{ + "password" : "j@rV1s", + "roles" : [ "uptime", "kibana_user" ], + "full_name" : "Jack Nicholson", + "email" : "jacknich@example.com", + "metadata" : { + "intelligence" : 7 + } +} +--------------------------------------------------------------- +// CONSOLE