[synthetics] Update TLS certificate rule doc to include Synthetics (#…

…4750) (#4757)

* update tls rule doc to include synthetics

* apply suggestions from code review

Co-authored-by: Arianna Laudazzi <[email protected]>

---------

Co-authored-by: Arianna Laudazzi <[email protected]>
(cherry picked from commit a18b7e9)

Co-authored-by: Colleen McGinnis <[email protected]>

docs/en/observability/create-alerts.asciidoc

@@ -81,11 +81,11 @@ a| * <<logs-threshold-alert,Log threshold rule>>
 
 | *Synthetics*
 a| * <<monitor-status-alert-synthetics,Synthetics monitor status rule>>
-// * <<tls-certificate-alert,Synthetics TLS certificate >> rule
+* <<tls-rule-synthetics,Synthetics TLS certificate rule>>
 
 | *Uptime* (deprecated:[8.15.0])
 a| * <<monitor-status-alert-uptime,Uptime monitor status rule>>
-* <<tls-certificate-alert,Uptime TLS rule>>
+* <<tls-rule-uptime,Uptime TLS rule>>
 * <<duration-anomaly-alert,Uptime duration anomaly rule>>
 
 |===
@@ -199,7 +199,7 @@ include::metrics-threshold-alert.asciidoc[leveloffset=+2]
 
 include::monitor-status-alert.asciidoc[leveloffset=+2]
 
-include::uptime-tls-alert.asciidoc[leveloffset=+2]
+include::synthetics-uptime-tls-alert.asciidoc[leveloffset=+2]
 
 include::uptime-duration-anomaly-alert.asciidoc[leveloffset=+2]
 

docs/en/observability/synthetics-uptime-tls-alert.asciidoc

@@ -0,0 +1,220 @@
+[[tls-certificate-alert]]
+= Create a TLS certificate rule
+
+++++
+<titleabbrev>TLS certificate</titleabbrev>
+++++
+
+In {kib}, you can create a rule that notifies you when one or more of your monitors
+has a TLS certificate expiring within a specified threshold, or when it exceeds an age limit.
+
+There are two types of TLS certificate rule:
+
+* <<tls-rule-synthetics>> for use with <<monitor-uptime-synthetics,Elastic Synthetics>>.
+* deprecated:[8.15.0] <<tls-rule-uptime>> for use with the {uptime-app}.
+
+[discrete]
+[[tls-rule-synthetics]]
+== Synthetics TLS certificate rule
+
+Within the Synthetics UI, create a **TLS certificate** rule to receive notifications
+based on errors and outages.
+
+[discrete]
+[[tls-rule-synthetics-conditions]]
+=== Conditions
+
+You can specify the following thresholds for your rule:
+
+[cols="1,1"]
+|===
+| *Expiration threshold*
+| The `HAS A CERTIFICATE EXPIRING WITHIN DAYS` condition specifies when you are notified
+about certificates that are approaching expiration dates.
+
+| *Age limit*
+| The `OR OLDER THAN DAYS` condition specifies when you are notified about certificates
+that have been valid for too long.
+|===
+
+The *Rule schedule* defines how often to evaluate the condition.
+
+You can also set *Advanced options* such as the number of consecutive runs that must meet the rule conditions before
+an alert occurs.
+
+In this example, the conditions are met when any of the TLS certificates on sites we’re monitoring
+is expiring within 30 days or is older than 730 days. These conditions are evaluated every 6 hours,
+and you will only receive an alert when the conditions are met three times consecutively.
+
+[role="screenshot"]
+image::images/tls-rule-synthetics-conditions.png[Conditions and advanced options defining a Synthetics TLS certificate rule,width=600]
+
+[discrete]
+[[tls-rule-synthetics-action-types]]
+=== Action types
+
+Extend your rules by connecting them to actions that use the following supported built-in integrations.
+
+include::../shared/alerting-and-rules/alerting-connectors.asciidoc[]
+
+After you select a connector, you must set the action frequency.
+You can choose to create a summary of alerts on each check interval or on a custom interval.
+For example, send email notifications that summarize the new, ongoing, and recovered alerts each hour:
+
+[role="screenshot"]
+image::images/tls-rule-synthetics-action-types-summary.png[width=600]
+
+Alternatively, you can set the action frequency such that you choose how often the action runs
+(for example, at each check interval, only when the alert status changes, or at a custom action interval).
+In this case, you must also select the specific threshold condition that affects when actions run:
+the _Synthetics TLS certificate_ changes or when it is _Recovered_ (went from down to up).
+
+[role="screenshot"]
+image::images/tls-rule-synthetics-action-types-each-alert.png[width=600]
+
+You can also further refine the conditions under which actions run by specifying that actions only run
+when they match a KQL query or when an alert occurs within a specific time frame:
+
+* *If alert matches query*: Enter a KQL query that defines field-value pairs or query conditions that must
+  be met for notifications to send. The query only searches alert documents in the indices specified for the rule.
+* *If alert is generated during timeframe*: Set timeframe details. Notifications are only sent if alerts are
+  generated within the timeframe you define.
+
+[role="screenshot"]
+image::images/tls-rule-synthetics-action-types-more-options.png[width=600]
+
+[discrete]
+[[tls-rule-synthetics-action-variables]]
+==== Action variables
+
+Use the default notification message or customize it.
+You can add more context to the message by clicking the icon above the message text box
+and selecting from a list of available variables.
+
+[role="screenshot"]
+image::images/tls-rule-synthetics-action-variables.png[width=600]
+
+The following variables are specific to this rule type.
+You an also specify {kibana-ref}/rule-action-variables.html[variables common to all rules].
+
+`context.checkedAt`:: Timestamp of the monitor run.
+`context.hostName`:: Hostname of the location from which the check is performed.
+`context.labels`::  Labels associated with the monitor.
+`context.lastErrorMessage`:: Monitor last error message.
+`context.lastErrorStack`:: Monitor last error stack trace.
+`context.locationId`:: Location ID from which the check is performed.
+`context.locationName`:: Location name from which the check is performed.
+`context.locationNames`:: Location names from which the checks are performed.
+`context.monitorType`:: Type (for example, HTTP/TCP) of the monitor.
+`context.monitorUrl`:: URL of the monitor.
+`context.reason`:: A concise description of the reason for the alert.
+`context.recoveryReason`:: A concise description of the reason for the recovery.
+`context.serviceName`:: Service name associated with the monitor.
+`context.status`:: Monitor status (for example, "down").
+`context.viewInAppUrl`:: Open alert details and context in Synthetics app.
+
+[discrete]
+[[tls-rule-uptime]]
+== Uptime TLS rule
+
+deprecated[8.15.0]
+
+Within the {uptime-app}, create a **TLS certificate** rule to receive notifications
+based on errors and outages.
+
+[discrete]
+[[tls-rule-uptime-filters]]
+=== Filters
+
+The *Filter by* section controls the scope of the rule.
+The rule will only check monitors that match the filters defined in this section.
+
+[discrete]
+[[tls-alert-conditions]]
+=== Conditions
+
+You can specify the following thresholds for your rule:
+
+[cols="1,1"]
+|===
+| *Expiration threshold*
+| The `HAS A CERTIFICATE EXPIRING WITHIN DAYS` threshold specifies when you are notified
+about certificates that are approaching expiration dates.
+
+| *Age limit*
+| The `OR OLDER THAN DAYS` threshold specifies when you are notified about certificates
+that have been valid for too long.
+|===
+
+In this example, the conditions are met when any of the TLS certificates on sites we’re monitoring
+is expiring within 30 days or is older than 730 days. These conditions are evaluated every 6 hours,
+and you will only receive an alert when the conditions are met three times consecutively.
+
+[role="screenshot"]
+image::images/tls-rule-uptime-conditions.png[Monitor status rule]
+
+[discrete]
+[[action-types-certs]]
+=== Action types
+
+Extend your rules by connecting them to actions that use the following
+supported built-in integrations. Actions are {kib} services or integrations with
+third-party systems that run as background tasks on the {kib} server when rule conditions are met.
+
+You can configure action types on the <<configure-uptime-alert-connectors,Settings>> page.
+
+include::../shared/alerting-and-rules/alerting-connectors.asciidoc[]
+
+After you select a connector, you must set the action frequency.
+You can choose to create a summary of alerts on each check interval or on a custom interval.
+For example, send email notifications that summarize the new, ongoing, and recovered alerts each hour:
+
+[role="screenshot"]
+image::images/tls-rule-uptime-action-types-summary.png[width=600]
+
+Alternatively, you can set the action frequency such that you choose how often the action runs
+(for example, at each check interval, only when the alert status changes, or at a custom action interval).
+In this case, you must also select the specific threshold condition that affects when actions run:
+_Uptime TLS Alert_ or _Recovered_ (went from down to up).
+
+[role="screenshot"]
+image::images/tls-rule-uptime-action-types-each-alert.png[width=600]
+
+You can also further refine the conditions under which actions run by specifying that actions only run
+when they match a KQL query or when an alert occurs within a specific time frame:
+
+* *If alert matches query*: Enter a KQL query that defines field-value pairs or query conditions that must
+  be met for notifications to send. The query only searches alert documents in the indices specified for the rule.
+* *If alert is generated during timeframe*: Set timeframe details. Notifications are only sent if alerts are
+  generated within the timeframe you define.
+
+[role="screenshot"]
+image::images/tls-rule-uptime-action-types-more-options.png[width=600]
+
+[discrete]
+[[action-variables-certs]]
+==== Action variables
+
+Use the default notification message or customize it.
+You can add more context to the message by clicking the icon above the message text box
+and selecting from a list of available variables.
+
+[role="screenshot"]
+image::images/tls-rule-uptime-default-message.png[Default notification message for TLS rules with open "Add variable" popup listing available action variables,width=600]
+
+The following variables are specific to this rule type.
+You an also specify {kibana-ref}/rule-action-variables.html[variables common to all rules].
+
+`context.agingCommonNameAndDate`:: The common names and expiration date/time of the detected certs.
+`context.agingCount`:: The number of detected certs that are becoming too old.
+`context.alertDetailsUrl`:: Link to the alert troubleshooting view for further context and details. This will be an empty string if the `server.publicBaseUrl` is not configured.
+`context.count`:: The number of certs detected by the alert executor.
+`context.currentTriggerStarted`:: Timestamp indicating when the current trigger state began, if alert is triggered.
+`context.expiringCommonNameAndDate`:: The common names and expiration date/time of the detected certs.
+`context.expiringCount`:: The number of expiring certs detected by the alert.
+`context.firstCheckedAt`:: Timestamp indicating when this alert first checked.
+`context.firstTriggeredAt`:: Timestamp indicating when the alert first triggered.
+`context.isTriggered`:: Flag indicating if the alert is currently triggering.
+`context.lastCheckedAt`:: Timestamp indicating the alert's most recent check time.
+`context.lastResolvedAt`:: Timestamp indicating the most recent resolution time for this alert.
+`context.lastTriggeredAt`:: Timestamp indicating the alert's most recent trigger time.