Ingest uptime data
editIngest uptime data
editIf you haven’t already, you need to install Elasticsearch for storing and searching your data, and Kibana for visualizing and managing it. For more information, see Send data to Elasticsearch.
Install and configure Heartbeat on your servers to periodically check the status of your services. Heartbeat uses probing to monitor the availability of services and helps verify that you’re meeting your service level agreements for service uptime. You typically install Heartbeat as part of a monitoring service that runs on a separate machine and possibly even outside of the network where the services that you want to monitor are running.
Deployment considerations
editThere are multiple ways to deploy Uptime and Heartbeat. A guiding principle is that when an outage takes down the service being monitored, it should not take down Heartbeat.
Heartbeat is commonly run as a centralized service within a data center. While it’s 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 instances of Heartbeat across geographic and network boundaries to provide more data.
For example:
-
A site served from a content delivery network (CDN) with points of presence (POPs) around the globe.
To check if your site is reachable via CDN POPS, deploy multiple Heartbeat instances at different data centers around the world.
-
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. In the event of an outage, having both instances helps pinpoint the network errors.
-
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 apparent if the service has a connectivity issue to the outside world, or if the failure is only internal.
Step 1: Install Heartbeat
editYou typically install Heartbeat as part of a monitoring service that runs on a separate machine and possibly even outside of the network where the services that you want to monitor are running.
To download and install Heartbeat, use the commands that work with your system:
curl -L -O https://artifacts.elastic.co/downloads/beats/heartbeat/heartbeat-7.10.2-amd64.deb sudo dpkg -i heartbeat-7.10.2-amd64.deb
curl -L -O https://artifacts.elastic.co/downloads/beats/heartbeat/heartbeat-7.10.2-x86_64.rpm sudo rpm -vi heartbeat-7.10.2-x86_64.rpm
curl -L -O https://artifacts.elastic.co/downloads/beats/heartbeat/heartbeat-7.10.2-darwin-x86_64.tar.gz tar xzvf heartbeat-7.10.2-darwin-x86_64.tar.gz
brew tap elastic/tap brew install elastic/tap/heartbeat-full
This command installs the most recently released default distribution of
Heartbeat. To install the OSS distribution, specify
elastic/tap/heartbeat-oss
.
curl -L -O https://artifacts.elastic.co/downloads/beats/heartbeat/heartbeat-7.10.2-linux-x86_64.tar.gz tar xzvf heartbeat-7.10.2-linux-x86_64.tar.gz
- Download the Heartbeat Windows zip file from the downloads page.
-
Extract the contents of the zip file into
C:\Program Files
. -
Rename the
heartbeat-<version>-windows
directory toHeartbeat
. - Open a PowerShell prompt as an Administrator (right-click the PowerShell icon and select Run As Administrator).
-
From the PowerShell prompt, run the following commands to install Heartbeat as a Windows service:
PS > cd 'C:\Program Files\Heartbeat' PS C:\Program Files\Heartbeat> .\install-service-heartbeat.ps1
If script execution is disabled on your system, you need to set the
execution policy for the current session to allow the script to run. For
example:
PowerShell.exe -ExecutionPolicy UnRestricted -File .\install-service-heartbeat.ps1
.
Other installation options
editStep 2: Connect to Elasticsearch and Kibana
editConnections to Elasticsearch and Kibana are required to set up Heartbeat.
Set the connection information in heartbeat.yml
. To locate this configuration file,
see Directory layout.
Specify the cloud.id of your Elasticsearch Service, and set cloud.auth to a user who is authorized to set up Heartbeat. For example:
cloud.id: "staging:dXMtZWFzdC0xLmF3cy5mb3VuZC5pbyRjZWM2ZjI2MWE3NGJmMjRjZTMzYmI4ODExYjg0Mjk0ZiRjNmMyY2E2ZDA0MjI0OWFmMGNjN2Q3YTllOTYyNTc0Mw==" cloud.auth: "heartbeat_setup:YOUR_PASSWORD"
This examples shows a hard-coded password, but you should store sensitive values in the secrets keystore. |
-
Set the host and port where Heartbeat can find the Elasticsearch installation, and set the username and password of a user who is authorized to set up Heartbeat. For example:
output.elasticsearch: hosts: ["myEShost:9200"] username: "heartbeat_internal" password: "YOUR_PASSWORD"
This examples shows a hard-coded password, but you should store sensitive values in the secrets keystore.
-
If you plan to use our pre-built Kibana dashboards, configure the Kibana endpoint. Skip this step if Kibana is running on the same host as Elasticsearch.
The hostname and port of the machine where Kibana is running, for example,
mykibanahost:5601
. If you specify a path after the port number, include the scheme and port:http://mykibanahost:5601/path
.The
username
andpassword
settings for Kibana are optional. If you don’t specify credentials for Kibana, Heartbeat uses theusername
andpassword
specified for the Elasticsearch output.To use the pre-built Kibana dashboards, this user must be authorized to view dashboards or have the
kibana_admin
built-in role.
You can send data to other outputs, such as Logstash, but that requires additional configuration and setup.
To learn more about required roles and privileges, see Grant users access to secured resources.
Step 3: Configure Heartbeat monitors
editHeartbeat provides monitors to check the status of hosts at set intervals. Heartbeat currently provides monitors for ICMP, TCP, and HTTP (see Heartbeat overview for more about these monitors).
You configure each monitor individually. In heartbeat.yml
, specify the
list of monitors that you want to enable. Each item in the list begins with a
dash (-). The following example configures Heartbeat to use two monitors, an
icmp
monitor and a tcp
monitor:
heartbeat.monitors: - type: icmp schedule: '*/5 * * * * * *' hosts: ["myhost"] - type: tcp schedule: '@every 5s' hosts: ["myhost:12345"] mode: any
The |
|
The |
|
The |
To test your configuration file, change to the directory where the Heartbeat binary
is installed, and run Heartbeat in the foreground with the following options specified:
./heartbeat test config -e
. Make sure your config files are in the path expected by
Heartbeat (see Directory layout), or use the
-c
flag to specify the path to the config file.
For more information about configuring Heartbeat, also see:
- Configure Heartbeat
- Config file format
-
heartbeat.reference.yml
: This reference configuration file shows all non-deprecated options. You’ll find it in the same location asheartbeat.yml
.
Step 4: Configure Heartbeat location
editHeartbeat can be deployed in multiple locations so that you can detect differences in availability and response times across those locations. Configure the Heartbeat location to allow Kibana to display location-specific information on Uptime maps and perform Uptime anomaly detection based on location.
To configure the location of a Heartbeat instance, modify the
add_observer_metadata
processor in heartbeat.yml
. The following
example specifies the geo.name
of the add_observer_metadata
processor as
us-east-1a
:
# ============================ Processors ============================ processors: - add_observer_metadata: # Optional, but recommended geo settings for the location Heartbeat is running in geo: # Token describing this location name: us-east-1a # Lat, Lon " #location: "37.926868, -78.024902"
Uncomment the |
|
Uncomment |
|
Optionally uncomment |
To test your configuration file, change to the directory where the Heartbeat binary
is installed, and run Heartbeat in the foreground with the following options specified:
./heartbeat test config -e
. Make sure your config files are in the path expected by
Heartbeat (see Directory layout), or use the
-c
flag to specify the path to the config file.
Step 5: Set up assets
editHeartbeat comes with predefined assets for parsing, indexing, and visualizing your data. To load these assets:
-
Make sure the user specified in
heartbeat.yml
is authorized to set up Heartbeat. -
From the installation directory, run:
heartbeat setup -e
heartbeat setup -e
./heartbeat setup -e
heartbeat setup -e
./heartbeat setup -e
PS > .\heartbeat.exe setup -e
-e
is optional and sends output to standard error instead of the configured log output.
This step loads the recommended index template for writing to Elasticsearch. It does not install Heartbeat dashboards. Heartbeat dashboards and installation steps are available in the uptime-contrib GitHub repository.
A connection to Elasticsearch (or Elasticsearch Service) is required to set up the initial environment. If you’re using a different output, such as Logstash, see Load the index template manually.
Step 6: Start Heartbeat
editBefore starting Heartbeat, modify the user credentials in
heartbeat.yml
and specify a user who is
authorized to publish events.
To start Heartbeat, run:
sudo service heartbeat-elastic start
If you use an init.d
script to start Heartbeat, you can’t specify command
line flags (see Command reference). To specify flags, start Heartbeat in
the foreground.
Also see Heartbeat and systemd.
sudo service heartbeat-elastic start
If you use an init.d
script to start Heartbeat, you can’t specify command
line flags (see Command reference). To specify flags, start Heartbeat in
the foreground.
Also see Heartbeat and systemd.
You’ll be running Heartbeat as root, so you need to change ownership
of the configuration file, or run Heartbeat with |
To have launchd start elastic/tap/heartbeat
and then restart it at login,
run:
brew services start elastic/tap/heartbeat-full
To run Heartbeat in the foreground instead of running it as a background service, run:
You’ll be running Heartbeat as root, so you need to change ownership
of the configuration file, or run Heartbeat with |
You’ll be running Heartbeat as root, so you need to change ownership
of the configuration file, or run Heartbeat with |
PS C:\Program Files\heartbeat> Start-Service heartbeat
By default, Windows log files are stored in C:\ProgramData\heartbeat\Logs
.
Heartbeat is now ready to check the status of your services and send events to your defined output.
Step 7: View your data in Kibana
editLet’s confirm your data is correctly ingested to your cluster.
-
Launch Kibana:
- Log in to your Elastic Cloud account.
- Navigate to the Kibana endpoint in your deployment.
Point your browser to http://localhost:5601, replacing
localhost
with the name of the Kibana host. - In the side navigation, click Observability > Uptime.
Now let’s have a look at the Uptime app.