Site Availability Monitor (SAM) connector

Zenoss Cloud provides the SAM connector so you can monitor the uptime of your cloud-based web applications and notify business and application owners and administrators of problems before they impact your organization.

Before you begin

As a best practice before setting up your connector, check that your service allows the source IP address from where you expect connections. See Before setting up your connectors for the list of IP addresses and more information.

As part of setting up the connector, you upload a configuration file that includes one or more sites to monitor. After you add your SAM connector, Zenoss uses the Site Availability Monitor template to create your dashboard. For more information, see Site Availability Monitor (SAM).

Note

Events are automatically created. You can view them in the Events console.

Set up a Site Availability Monitor (SAM) connector

Perform the following steps to set up your Site Availability Monitor (SAM) connector.

Note

Your account must be assigned the Manager role to create and manage connectors.

Log in to Zenoss Cloud as a user with the Manager role, and then open the ADMIN > Connectors page. Click ADD CONNECTOR.
On the SELECT CONNECTOR TYPE dialog box, click the Site Availability Monitor card. The ADD CONNECTOR dialog box opens.
In Site Availability Monitor details, add information about your application.
1. In the Name field, enter a unique name for your connector. The name you choose is used as the source name for the data that Zenoss Cloud collects.
2. (Optional) In the Description field, enter text to associate with your connector.
3. Keep the Connector type as Site Availability Monitor.
4. (Optional) In the Tags field, enter one or more terms to associate with your connector.
In Configuration, choose a configuration file to upload.
1. Click the Sample Config button to download a sample configuration file. SAM configuration files are written in YAML. Alternatively, view the sample configuration by hovering your mouse over the info icon.
2. Customize the sample configuration file or create a new file based on the syntax of the sample. To learn more about the configuration options in the file, see Using the sample configuration file.
3. Click the upload icon or the filename field and choose your configuration file.
Click SAVE. A confirmation dialog box appears, asking you if you want to create a new dashboard.
(Optional) In the confirmation dialog box, choose CREATE DASHBOARD to create a new dashboard using the SAM template for your connector.
1. In the NAME DASHBOARD dialog box, enter a unique name for your dashboard.
2. When you see the success message, click DASHBOARDS to view your dashboard for the SAM connector. Zenoss creates the dashboard using the Site Availability Monitor template, so your dashboard might look similar to the following image:
For more information about the default SAM dashboard template, see Site Availability Monitor template.

Using the sample configuration file

Zenoss includes a sample YAML configuration file that you can use as the basis for your own connector. The content is similar to the following file content:

urls:
  example-01:
    interval: 30s
    address: https://example01.com
    send_metrics: true
    credentials:
      # For api keys on other headers:
      type: api-key
      field: X-API-Key
      key: myApiKeyValue

      # or, for http basic-auth:
      # type: basic-auth
      # login: myUsername
      # password: myPassword

      # or, for http 'bearer' type authentication:
      # type: api-key
      # key: myBearerTokenValue
      # key_prefix: Bearer
    redirection_params:
      follow_redirections: true
      fail_on_redirections: false
      max_redirections: 5
      redirect_location_pass: www.example01.org
      redirect_location_fail: www.failing-example.com
      payload_match_pass: "Example for pass"
      payload_match_fail: "example for fail"
    content_params:
      my-content-test:
        content_match: unavailable
        content_location: body
        expected_matches: 1
        action_on_match: fail
    metadata:
      name: example-1
    subpages:
      anything-blue:
        path: anything/blue/
        method: get
        metadata:
          # having the complete address as a user defined metadata field can be useful for understating which URL address is being pinged.
          myaddress: https://example01.com/anything-blue/anything/blue/
          myfield1: test
        status_params:
          # specify any exclusions to the default rules here.
          up:
            additional:
              - 777
              - 888
          down:
            exclusions:
              - 308
      anything-yellow:
        path: anything/yellow/
        method: post
        # Provide any HTTP POST method data to be sent in the request. Data will be sent as simple JSON
        data:
          data_string_1: "test data"
          data_integer_1: 1000

  example-02:
    interval: 2m
    address: https://example02.org
    send_metrics: false
    subpages:
      anything-red:
        path: anything/red/
        method: get
        redirection_params:
          follow_redirections: true
          fail_on_redirections: false
          max_redirections: 5
          redirect_location_pass: www.example02.org
          redirect_location_fail: www.failing-example02.com
          payload_match_pass: "Example for pass"
          payload_match_fail: "example for fail"
        content_params:
          my-content-check-foo:
            content_match: foo
            content_location: headers
            expected_matches: 2
            action_on_match: pass

You can use a single configuration file to monitor multiple URLs (example-01 and example-02).

Optionally, you can set redirection and content parameters for a site or for specific subpages. These parameters are useful if you want to fine-tune site availability monitoring when your sites are redirected. For example, your site might automatically redirect to a temporary "site down" page. In this case, you can configure these parameters to indicate that the site is down in your SAM dashboard tile even though a site page was reached.

URL configuration options

Use the following tables of URL configuration options and values to set up your web applications with SAM.

Option	Values	Description
`interval`	integer followed by `s`, `m`, or `h`	The cycle time in seconds, minutes, or hours used to poll the URL and any defined subpages.
`address`	`http://` or `https://`	The URL to be polled.
`send-metrics`	boolean (`true`\|`false`)	Set this flag to `true` to enable the URL and its subpages to collect and send metrics. Set to `false` if you do not want to collect and receive metrics.

Note

Sometimes, a URL without a subpage is unreachable because of network, DNS, or site errors. In such cases, Zenoss sends an event indicating that the site is down.

Credentials options

You can use the credentials parameters to specify a login method and authentication values. Supported authentication methods include HTTP basic, HTTP bearer, and API keys.

A failure event is generated if the supplied credentials fail to validate with the target URL.

Basic Authentication

Basic authentication is a simple HTTP authentication scheme that sends credentials as user ID/password pairs in an encoded (not encrypted) string. In the configuration file, basic authentication uses the type: basic-auth parameter with the login and password parameters.

Note

In Zenoss, you can only perform basic authentication at the domain level. It does not work for subpages.

Option	Value	Description
`type`	`basic-auth`	Sets the authentication mode to HTTP-basic using the `Authorization: Basic` field.
`login`	string	A user ID allowed by the target URL.
`password`	string	The password for the user ID specified by `login`.

Bearer Authentication

Bearer authentication (sometimes called token authentication) is an HTTP authentication scheme that uses access tokens called bearer tokens. When you use bearer authentication, you are granting permission to the "bearer" of this token to access protected resources. The bearer token is a cryptic string in the Authorization header. It’s widely used for securing API access.

In the configuration file, bearer authentication uses the type: api-key parameter, as well the key_prefix: <prefix_value> and key: <token_value> parameters. A common format of the bearer token in the header might be:

Authorization: Bearer {token_value}

Option	Value	Description
`type`	`api-key`	Sets the authentication mode to HTTP-bearer using the `<prefix_value>` field.
`key_prefix`	string	The token prefix expected by the target URL.
`key`	string	An authentication token.

API Keys

API key authentication uses an API key to authenticate to an API.

In the configuration file, API key authentication uses the type: api-key and key: <API_key> parameters, and the field : <X-API-Key> parameter.

Option	Value	Description
`type`	`api-key`	Sets the authentication mode to API key using a user-supplied field.
`field`	string	The name of the field expected by the URL.
`key`	string	The API key to supply to the URL.

Note

Both HTTP-bearer and API key authentication use the type: api-key and key parameters. However, they differ in their use of subsequent parameters: key_prefix for bearer mode and field for API mode.

Metadata options

You can add metadata to a site or a subpage in the form of one or more key-value pairs. Add the key and its value to the site or subpage entities as attributes. Metadata is only used to add information to an entity and has no effect on monitoring.

Option	Values	Description
`metadata`	one or more key-value elements	Keys and their values will be added to the URL entity.

Note

If the same key is used on a site and on one of its subpages, the subpage value will override the site value.

Subpage configuration options

Subpage configuration options include the following:

Option	Values	Description
`path`	string with no leading `/` character. If you want to monitor the root of a website, set this value to `/` only.	The path to an individual page or root of a website that the connector should monitor.
`method`	string (`get`\|`post`)	The HTTP method that the connector uses to poll the page.
`event_body_limit_bytes`	2048 (default)	Define how many bytes of the response to attach to a warning, error, or critical event for a subpage. You can use this parameter to limit the size of the response to an error event. This is an optional parameter.

Redirection options

Redirection configuration options include the following:

Option	Values	Description
`follow_redirections`	boolean (`true`\|`false`)	Set this flag to `true` to accept when this page redirects to another page or pages. Set to `false` to reject when this page redirects to other pages. When set to `true`, the site status in your SAM dashboard tile maintains a status of "Up" when the site redirects to another page. Additionally, when this parameter is set to `true`, it overrides the `fail_on_redirections` parameter.
`fail_on_redirections`	boolean (`true`\|`false`)	Set this flag to `true` to reject when this page redirects to another page or pages. Set to `false` to accept when this page redirects to other pages. This parameter works together wtih the `follow_redirections` parameter: If the `follow_redirections` parameter is set to `false` and the `fail_on_redirections` is set to `false`, then the site in the SAM dashboard tile maintains a status of "Down" and the redirect status code is returned. If the `follow_redirections` parameter is set to `true` and the `fail_on_redirections` parameter is set to `false`, then the site has a status of "Up".
`max_redirections`	integer	The maximum number of times a site is permitted to redirect to another page before impacting the site status in the SAM dashboard tile. To activate redirection, set a value of `1` or greater. If you set this parameter to `0`, redirection is deactivated.
`redirect_location_pass`	string	Enter the name of the redirecton site that is allowed. When this final destination is reached through redirection, the status of the site in the SAM dashboard is "Up".
`redirect_location_fail`	string	Enter the name of the redirection site that is disallowed. When this destination is detected within a chain of redirections, the status of the site in the SAM dashboard is "Down".
`payload_match_pass`	string or regex	Enter a string or regular expression for Zenoss to search. If it is found, the site is allowed and the status of the site in the SAM dashboard tile is "Up". If it is not found, the status of the site in the SAM dashboard tile is "Down".
`payload_match_fail`	string or regex	Enter a string or regular expression for Zenoss to search. If it is found, the site is disallowed and the status of the site in the SAM dashboad tile is "Down". If it is not found, the status of the site in the SAM dashboard tile is "Up".

Content options

You can use the content parameters separately or jointly with the redirections parameters. This group of content parameters work together to provide the criteria for a specific action. You can specify the text to search, where to find it, how many times to find it, and what action to perform when the criteria is met.

Content configuration options include the following:

Option	Values	Description
`content_match`	string	Enter the text that you want to search on the site in order to perform a specific action. For example, you might want to enter "site down" as the text to find if you want to set the monitoring status to "Down" in the SAM dashboard when this text appears on the page.
`content_location`	string	Specify the location of the text in the `content_match` parameter. You can specify `headers`, the name of a specific header, or `body`. The default value is `body`.
`expected_matches`	integer	Enter the exact number of matches to find on the site. When Zenoss finds this exact number of matches, it performs the action specified in the `action_on_match` parameter. The default value is `1`.
`action_on_match`	`pass`\|`fail`	Enter the action to perform when the criteria from the other three content parameters is met. If you enter `pass`, the site is allowed and the status in the SAM dashboard tile is "Up". If you enter `fail`, the site is disallowed, and the status in the SAM dashboard is "Down". The default value is `fail`.

Status parameters

The SAM Connector is configured with default ranges of response codes to indicate when a site has a status of Up and when a site has a status of Down.

When the response code is in the range of 100-299, the site is assigned a status of Up.
When the response code is in the range of 300-599, the site is assigned a status of Down.

For a specific site or subpage, you can define response codes that you want to exclude or include in these ranges. For example, you might have subpages which send custom status codes. In these cases, use the exclusions or additional parameters.

Note

As a best practice, only specify status codes for exclusion and inclusion when you want to change the default ranges.

Option	Values	Description
`exclusions`	a list of HTTP response code(s)	You can add response codes to exclude from either the `up` range or the `down` range.
`additional`	a list of HTTP response code(s)	You can add response codes to include in either the `up` range or the `down` range.

Example of status parameters

In the following example, the SAM connector is configured for the following exceptions to the default up and down ranges for a site or subpage:

In the up range, exclude the response codes of 298 and 299 from the default range of 100-299, and include the response code of 308.
In the down range, exclude the response code of 418 from the default range of 300-599 and include the response code of 266.

status_params:
  up:
    exclusions:
      - 298
      - 299
    additional:
      - 308
  down:
    exclusions:
      - 418
    additional:
      - 266

If a response code of 298, 299, or 266 is returned, the status will be Down for the site. If a response code of 308 or 418 is returned, the status will be Up for the site.

Data options

When using method: post on a subpage, you can use the data parameter to specify a list of key-value pairs. These keys and their values are reformatted as a JSON object and sent to the subpage as a data payload, for example, Content-Type: application/json.

Option	Values	Description
`data`	one or more key-value elements	Configured key-value pairs are sent to the subpage as a JSON payload.

Metadata options for subpages

You can add metadata to a site or a subpage in the form of one or more key-value pairs. Add the key and its value to the site or subpage entities as attributes. Metadata is only used to add information to an entity and has no effect on monitoring.

Option	Values	Description
`metadata`	one or more key-value elements	Keys and their values will be added to the subpage entity.

Note

If the same key is used on a site and on one of its subpages, the subpage value will override the site value.