From a0d45125c9b1073fee8f0f4de68c1fc1b361345e Mon Sep 17 00:00:00 2001 From: dbrian57 Date: Fri, 29 Dec 2023 16:34:25 -0500 Subject: [PATCH 1/5] clarifies docs string and adds examples for each command --- commands/monitoring.go | 50 ++++++++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/commands/monitoring.go b/commands/monitoring.go index 56a2195d0..178345359 100644 --- a/commands/monitoring.go +++ b/commands/monitoring.go @@ -33,8 +33,7 @@ func Monitoring() *Command { Short: "[Beta] Display commands to manage monitoring", Long: `The sub-commands of ` + "`" + `doctl monitoring` + "`" + ` manage the monitoring on your account. -An alert policy can be applied to resource(s) (currently Droplets) -in order to alert on resource consumption.`, +You can create alert policies to monitor the resource consumption of your Droplets, and uptime checks to monitor the availability of your websites and services`, GroupID: manageResourcesGroup, }, } @@ -50,27 +49,27 @@ func alertPolicies() *Command { Use: "alert", Aliases: []string{"alerts", "a"}, Short: "Display commands for managing alert policies", - Long: `The commands under ` + "`" + `doctl monitoring alert` + "`" + ` are for the management of alert policies. + Long: `The commands under ` + "`" + `doctl monitoring alert` + "`" + ` are for managing alert policies. -An alert policy can be applied to resource(s) (currently Droplets) -in order to alert on resource consumption. +You can apply alert policies to resources in order to receive alerts on resource consumption. If you'd like to alert on the uptime of a specific URL or IP address, use ` + "`" + `doctl monitoring uptime alert` + "` instead", }, } - cmdAlertPolicyCreate := CmdBuilder(cmd, RunCmdAlertPolicyCreate, "create", "Create an alert policy", `Use this command to create a new alert policy.`, Writer) - AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyDescription, "", "", "A description of the alert policy.") - AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyType, "", "", "The type of alert policy.") - AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyCompare, "", "", "The comparator of the alert policy. Either `GreaterThan` or `LessThan`") - AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyWindow, "", "5m", "The window to apply the alert policy conditions against.") - AddIntFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyValue, "", 0, "The value of the alert policy to compare against.") - AddBoolFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyEnabled, "", true, "Whether the alert policy is enabled.") - AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyEmails, "", nil, "Emails to send alerts to.") - AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyTags, "", nil, "Tags to apply the alert against.") - AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyEntities, "", nil, "Entities to apply the alert against. (e.g. a droplet ID for a droplet alert policy)") + cmdAlertPolicyCreate := CmdBuilder(cmd, RunCmdAlertPolicyCreate, "create", "Create an alert policy", `Create a new alert policy.`, Writer) + AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyDescription, "", "", "A description of the alert policy") + AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyType, "", "", "The type of alert policy") + AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyCompare, "", "", "The comparator of the alert policy. Possible values: `GreaterThan` or `LessThan`") + AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyWindow, "", "5m", "The amount of time the resource must exceed the threshold value before an alert is triggered. Possible values: `5m`, `10m`, `30m`, or `1h`") + AddIntFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyValue, "", 0, "The threshold value of the alert policy to compare against. For example, if the alert policy is of type `DropletCPUUtilizationPercent` and the value is set to `80`, an alert is triggered if the Droplet's CPU usage exceeds 80% for the specified window.") + AddBoolFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyEnabled, "", true, "Enables the alert policy") + AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyEmails, "", nil, "Email address to send alerts to") + AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyTags, "", nil, "Tags to apply the alert policy to. If set to a tag, all Droplet with that tag are monitored by the alert policy.") + AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyEntities, "", nil, "Resources to apply the alert against, such as a Droplet ID.") AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicySlackChannels, "", nil, "Slack channels to send alerts to.") AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicySlackURLs, "", nil, "Slack URLs to send alerts to.") + cmdAlertPolicyCreate.Example = `doctl monitoring alert create --type DropletCPUUtilizationPercent --value 80 --window 5m --entities 386734086,191669331 --emails admin@example.com` cmdAlertPolicyUpdate := CmdBuilder(cmd, RunCmdAlertPolicyUpdate, "update ...", "Update an alert policy", `Use this command to update an existing alert policy.`, Writer) AddStringFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyDescription, "", "", "A description of the alert policy.") @@ -79,20 +78,23 @@ If you'd like to alert on the uptime of a specific URL or IP address, use ` + "` AddStringFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyWindow, "", "5m", "The window to apply the alert policy conditions against.") AddIntFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyValue, "", 0, "The value of the alert policy to compare against.") AddBoolFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyEnabled, "", true, "Whether the alert policy is enabled.") - AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyEmails, "", nil, "Emails to send alerts to.") - AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyTags, "", nil, "Tags to apply the alert against.") - AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyEntities, "", nil, "Entities to apply the alert against. (e.g. a droplet ID for a droplet alert policy)") - AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicySlackChannels, "", nil, "Slack channels to send alerts to.") - AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicySlackURLs, "", nil, "Slack URLs to send alerts to.") + AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyEmails, "", nil, "Email addresses to send alerts to") + AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyTags, "", nil, "Tags to apply the alert against") + AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyEntities, "", nil, "Resources to apply the policy to") + AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicySlackChannels, "", nil, "A Slack channel to send alerts to. Must be used with `--slack-url`.") + AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicySlackURLs, "", nil, "A Slack webhook URL to send alerts to") - CmdBuilder(cmd, RunCmdAlertPolicyGet, "get ", "Retrieve information about an alert policy", `Use this command to retrieve an alert policy and see its configuration.`, Writer, + AlertPolicyGet := CmdBuilder(cmd, RunCmdAlertPolicyGet, "get ", "Retrieve information about an alert policy", `Retrieve an alert policy and its configuration.`, Writer, displayerType(&displayers.AlertPolicy{})) + AlertPolicyGet.Example = `The following example retrieves information about a policy with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl monitoring alert get f81d4fae-7dec-11d0-a765-00a0c91e6bf6` - CmdBuilder(cmd, RunCmdAlertPolicyList, "list", "List all alert policies", `Use this command to retrieve a list of all the alert policies in your account.`, Writer, + cmdAlertPolicyList := CmdBuilder(cmd, RunCmdAlertPolicyList, "list", "List all alert policies", `Retrieves a list of all the alert policies in your account.`, Writer, aliasOpt("ls"), displayerType(&displayers.AlertPolicy{})) + cmdAlertPolicyList.Example = `The following example lists all alert policies in your account: doctl monitoring alert list` - cmdRunAlertPolicyDelete := CmdBuilder(cmd, RunCmdAlertPolicyDelete, "delete ...", "Delete an alert policy", `Use this command to delete an alert policy.`, Writer, aliasOpt("rm")) - AddBoolFlag(cmdRunAlertPolicyDelete, doctl.ArgForce, doctl.ArgShortForce, false, "Delete an alert policy without confirmation prompt") + cmdRunAlertPolicyDelete := CmdBuilder(cmd, RunCmdAlertPolicyDelete, "delete ...", "Delete an alert policy", `Deletes an alert policy.`, Writer, aliasOpt("rm")) + AddBoolFlag(cmdRunAlertPolicyDelete, doctl.ArgForce, doctl.ArgShortForce, false, "Delete an alert policy without a confirmation prompt") + cmdRunAlertPolicyDelete.Example = `The following example deletes an alert policy with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl monitoring alert delete f81d4fae-7dec-11d0-a765-00a0c91e6bf6` return cmd } From 93b6b5de272f78e6fac560ed8f9c3d3fb334605d Mon Sep 17 00:00:00 2001 From: dbrian57 Date: Wed, 3 Jan 2024 13:11:57 -0500 Subject: [PATCH 2/5] Adds examples and clarifies docs strings for monitoring commands --- commands/monitoring.go | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/commands/monitoring.go b/commands/monitoring.go index 178345359..5bae8b591 100644 --- a/commands/monitoring.go +++ b/commands/monitoring.go @@ -59,7 +59,7 @@ If you'd like to alert on the uptime of a specific URL or IP address, use ` + "` cmdAlertPolicyCreate := CmdBuilder(cmd, RunCmdAlertPolicyCreate, "create", "Create an alert policy", `Create a new alert policy.`, Writer) AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyDescription, "", "", "A description of the alert policy") - AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyType, "", "", "The type of alert policy") + AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyType, "", "", "The type of alert policy. For example,`v1/insights/droplet/memory_utilization_percent` alerts on the percent of memory utilization. For a full list of alert types, see https://docs.digitalocean.com/reference/api/api-reference/#operation/monitoring_create_alertPolicy") AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyCompare, "", "", "The comparator of the alert policy. Possible values: `GreaterThan` or `LessThan`") AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyWindow, "", "5m", "The amount of time the resource must exceed the threshold value before an alert is triggered. Possible values: `5m`, `10m`, `30m`, or `1h`") AddIntFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyValue, "", 0, "The threshold value of the alert policy to compare against. For example, if the alert policy is of type `DropletCPUUtilizationPercent` and the value is set to `80`, an alert is triggered if the Droplet's CPU usage exceeds 80% for the specified window.") @@ -67,13 +67,13 @@ If you'd like to alert on the uptime of a specific URL or IP address, use ` + "` AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyEmails, "", nil, "Email address to send alerts to") AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyTags, "", nil, "Tags to apply the alert policy to. If set to a tag, all Droplet with that tag are monitored by the alert policy.") AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyEntities, "", nil, "Resources to apply the alert against, such as a Droplet ID.") - AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicySlackChannels, "", nil, "Slack channels to send alerts to.") - AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicySlackURLs, "", nil, "Slack URLs to send alerts to.") - cmdAlertPolicyCreate.Example = `doctl monitoring alert create --type DropletCPUUtilizationPercent --value 80 --window 5m --entities 386734086,191669331 --emails admin@example.com` + AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicySlackChannels, "", nil, "A Slack channel to send alerts to. For example, `production-alerts`") + AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicySlackURLs, "", nil, "A Slack webhook URL to send alerts to, for example, `https://hooks.slack.com/services/T1234567/AAAAAAAA/ZZZZZZ`.") + cmdAlertPolicyCreate.Example = `The following example creates an alert policy that sends an email to ` + "`" + `admin@example.com` + "`" + ` whenever the memory usage on the listed Droplets (entities) exceeds 80% for more than five minutes: doctl monitoring alert create --type "v1/insights/droplet/memory_utilization_percent" --compare GreaterThan --value 80 --window 5m --entities 386734086,191669331 --emails admin@example.com` cmdAlertPolicyUpdate := CmdBuilder(cmd, RunCmdAlertPolicyUpdate, "update ...", "Update an alert policy", `Use this command to update an existing alert policy.`, Writer) AddStringFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyDescription, "", "", "A description of the alert policy.") - AddStringFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyType, "", "", "The type of alert policy.") + AddStringFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyType, "", "", "The type of alert policy. For example,`v1/insights/droplet/memory_utilization_percent` alerts on the percent of memory utilization. For a full list of alert types, see https://docs.digitalocean.com/reference/api/api-reference/#operation/monitoring_create_alertPolicy") AddStringFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyCompare, "", "", "The comparator of the alert policy. Either `GreaterThan` or `LessThan`") AddStringFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyWindow, "", "5m", "The window to apply the alert policy conditions against.") AddIntFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyValue, "", 0, "The value of the alert policy to compare against.") @@ -81,8 +81,9 @@ If you'd like to alert on the uptime of a specific URL or IP address, use ` + "` AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyEmails, "", nil, "Email addresses to send alerts to") AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyTags, "", nil, "Tags to apply the alert against") AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyEntities, "", nil, "Resources to apply the policy to") - AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicySlackChannels, "", nil, "A Slack channel to send alerts to. Must be used with `--slack-url`.") - AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicySlackURLs, "", nil, "A Slack webhook URL to send alerts to") + AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicySlackChannels, "", nil, "A Slack channel to send alerts to, for example, `production-alerts`. Must be used with `--slack-url`.") + AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicySlackURLs, "", nil, "A Slack webhook URL to send alerts to, for example, `https://hooks.slack.com/services/T1234567/AAAAAAAA/ZZZZZZ`.") + cmdAlertPolicyUpdate.Example = `The following example updates an alert policy's details: doctl monitoring alert update f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --type "v1/insights/droplet/memory_utilization_percent" --compare GreaterThan --value 80 --window 10m --entities 386734086,191669331 --emails admin@example.com` AlertPolicyGet := CmdBuilder(cmd, RunCmdAlertPolicyGet, "get ", "Retrieve information about an alert policy", `Retrieve an alert policy and its configuration.`, Writer, displayerType(&displayers.AlertPolicy{})) From 592436b354bc92b352f0916c4d8b97816a874c20 Mon Sep 17 00:00:00 2001 From: dbrian57 Date: Wed, 3 Jan 2024 13:28:23 -0500 Subject: [PATCH 3/5] additional clarifications for monitoring commands --- commands/monitoring.go | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/commands/monitoring.go b/commands/monitoring.go index 5bae8b591..b1af391aa 100644 --- a/commands/monitoring.go +++ b/commands/monitoring.go @@ -57,7 +57,11 @@ If you'd like to alert on the uptime of a specific URL or IP address, use ` + "` }, } - cmdAlertPolicyCreate := CmdBuilder(cmd, RunCmdAlertPolicyCreate, "create", "Create an alert policy", `Create a new alert policy.`, Writer) + cmdAlertPolicyCreate := CmdBuilder(cmd, RunCmdAlertPolicyCreate, "create", "Create an alert policy", `Creates a new alert policy. You can create policies that monitor various metrics of your Droplets and send you alerts when a metric exceeds a specified threshold. + + For example, you can create a policy that monitors a Droplet's CPU usage and triggers an alert when the Droplet's CPU usage exceeds more than 80% for more than 10 minutes. + + For a full list of policy types you can set up, see our API documentation: https://docs.digitalocean.com/reference/api/api-reference/#operation/monitoring_create_alertPolicy`, Writer) AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyDescription, "", "", "A description of the alert policy") AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyType, "", "", "The type of alert policy. For example,`v1/insights/droplet/memory_utilization_percent` alerts on the percent of memory utilization. For a full list of alert types, see https://docs.digitalocean.com/reference/api/api-reference/#operation/monitoring_create_alertPolicy") AddStringFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicyCompare, "", "", "The comparator of the alert policy. Possible values: `GreaterThan` or `LessThan`") @@ -71,7 +75,7 @@ If you'd like to alert on the uptime of a specific URL or IP address, use ` + "` AddStringSliceFlag(cmdAlertPolicyCreate, doctl.ArgAlertPolicySlackURLs, "", nil, "A Slack webhook URL to send alerts to, for example, `https://hooks.slack.com/services/T1234567/AAAAAAAA/ZZZZZZ`.") cmdAlertPolicyCreate.Example = `The following example creates an alert policy that sends an email to ` + "`" + `admin@example.com` + "`" + ` whenever the memory usage on the listed Droplets (entities) exceeds 80% for more than five minutes: doctl monitoring alert create --type "v1/insights/droplet/memory_utilization_percent" --compare GreaterThan --value 80 --window 5m --entities 386734086,191669331 --emails admin@example.com` - cmdAlertPolicyUpdate := CmdBuilder(cmd, RunCmdAlertPolicyUpdate, "update ...", "Update an alert policy", `Use this command to update an existing alert policy.`, Writer) + cmdAlertPolicyUpdate := CmdBuilder(cmd, RunCmdAlertPolicyUpdate, "update ...", "Update an alert policy", `Updates an existing alert policy.`, Writer) AddStringFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyDescription, "", "", "A description of the alert policy.") AddStringFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyType, "", "", "The type of alert policy. For example,`v1/insights/droplet/memory_utilization_percent` alerts on the percent of memory utilization. For a full list of alert types, see https://docs.digitalocean.com/reference/api/api-reference/#operation/monitoring_create_alertPolicy") AddStringFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicyCompare, "", "", "The comparator of the alert policy. Either `GreaterThan` or `LessThan`") @@ -85,7 +89,7 @@ If you'd like to alert on the uptime of a specific URL or IP address, use ` + "` AddStringSliceFlag(cmdAlertPolicyUpdate, doctl.ArgAlertPolicySlackURLs, "", nil, "A Slack webhook URL to send alerts to, for example, `https://hooks.slack.com/services/T1234567/AAAAAAAA/ZZZZZZ`.") cmdAlertPolicyUpdate.Example = `The following example updates an alert policy's details: doctl monitoring alert update f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --type "v1/insights/droplet/memory_utilization_percent" --compare GreaterThan --value 80 --window 10m --entities 386734086,191669331 --emails admin@example.com` - AlertPolicyGet := CmdBuilder(cmd, RunCmdAlertPolicyGet, "get ", "Retrieve information about an alert policy", `Retrieve an alert policy and its configuration.`, Writer, + AlertPolicyGet := CmdBuilder(cmd, RunCmdAlertPolicyGet, "get ", "Retrieve information about an alert policy", `Retrieves an alert policy and its configuration.`, Writer, displayerType(&displayers.AlertPolicy{})) AlertPolicyGet.Example = `The following example retrieves information about a policy with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl monitoring alert get f81d4fae-7dec-11d0-a765-00a0c91e6bf6` From 491608ecb98df9b35811f48c51fd3ab5218bd44b Mon Sep 17 00:00:00 2001 From: dbrian57 Date: Wed, 3 Jan 2024 17:56:32 -0500 Subject: [PATCH 4/5] clarifies doc strings and adds examples for Uptime Alert commands --- commands/uptime_alerts.go | 66 ++++++++++++++++++++++----------------- 1 file changed, 38 insertions(+), 28 deletions(-) diff --git a/commands/uptime_alerts.go b/commands/uptime_alerts.go index 0d156c171..1e745751a 100644 --- a/commands/uptime_alerts.go +++ b/commands/uptime_alerts.go @@ -35,45 +35,55 @@ func UptimeAlert() *Command { Long: `The sub-commands of ` + "`" + `doctl monitoring uptime alert` + "`" + ` manage your uptime alerts. DigitalOcean Uptime Alerts provide the ability to monitor your endpoints from around the world, -and alert you when they're slow, unavailable, or SSL certificates are expiring.`, +and alert you when they're slow, unavailable, or SSL certificates are expiring. + +In order to set up uptime alerts, you must first set up an uptime check. Uptime checks monitor and track the status of an endpoint while alerts notify you of status changes based on the thresholds you set.`, }, } - cmdUptimeAlertsCreate := CmdBuilder(cmd, RunUptimeAlertsCreate, "create ", "Create an uptime alert", `Use this command to create an uptime alert on your account. - -You can use flags to specify the uptime alert, type, threshold, comparison, notifications, and period.`, Writer, + cmdUptimeAlertsCreate := CmdBuilder(cmd, RunUptimeAlertsCreate, "create ", "Create an uptime alert", `Creates an alert policy for an uptime check. + + You can create an alert policy based on the following metrics: + + - `+"`"+`latency`+"`"+`: Alerts on the response latency. `+"`"+`--threshold`+"`"+` value is an integer representing milliseconds. + - `+"`"+`down`+"`"+`: Alerts on whether the endpoints registers as down from any of the configured regions. No `+"`"+`--threshold`+"`"+` value is necessary. + - `+"`"+`down_global`+"`"+`: Alerts on a target registering as down globally. No `+"`"+`--threshold`+"`"+` value is necessary. + - `+"`"+`ssl_expiry`+"`"+`: Alerts on an SSL certificate expiring within the set threshold of days. `+"`"+`--threshold`+"`"+` value is an integer representing days.`, Writer, aliasOpt("c"), displayerType(&displayers.UptimeAlert{}), overrideCmdNS("uptime-alert")) - AddStringFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertName, "", "", "Uptime alert name", requiredOpt()) - AddStringFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertType, "", "", "Uptime alert type, must be one of latency, down, down_global or ssl_expiry", requiredOpt()) - AddIntFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertThreshold, "", 0, "Uptime alert threshold at which the alert will enter a trigger state. The specific threshold is dependent on the alert type.") - AddStringFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertComparison, "", "", "Uptime alert comparison operator used against the alert's threshold. Must be either `greater_than` or `less_than`") - AddStringSliceFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertEmails, "", nil, "Emails to send uptime alerts to. Must be emails associated with the DigitalOcean account") - AddStringSliceFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertSlackChannels, "", nil, "Slack channels to send uptime alerts to.") - AddStringSliceFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertSlackURLs, "", nil, "Slack URLs to send uptime alerts to.") - AddStringFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertPeriod, "", "", "Uptime alert period of time the threshold must be exceeded to trigger the alert. Must be one of 2m, 3m, 5m, 10m, 15m, 30m or 1h", requiredOpt()) - - CmdBuilder(cmd, RunUptimeAlertsGet, "get ", "Get uptime alert", `Use this command to get an uptime alert on your account by ID.`, Writer, + AddStringFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertName, "", "", "The name of the alert", requiredOpt()) + AddStringFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertType, "", "", "The metric to alert on. Possible values: `latency`, `down`, `down_global`, `ssl_expiry`", requiredOpt()) + AddIntFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertThreshold, "", 0, "The threshold at which to trigger the alert. The specific threshold is dependent on the alert type.") + AddStringFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertComparison, "", "", "A comparison operator used against the alert's threshold. Possible values: `greater_than` or `less_than`") + AddStringSliceFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertEmails, "", nil, "Emails addresses to send alerts. The addresses must be associated with your DigitalOcean account") + AddStringSliceFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertSlackChannels, "", nil, "Slack channels to send alerts to, for example, `production-alerts`. Must be used with the `--slack-urls` flag.") + AddStringSliceFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertSlackURLs, "", nil, "A Slack webhook URL to send alerts to, for example, `https://hooks.slack.com/services/T1234567/AAAAAAAA/ZZZZZZ`.") + AddStringFlag(cmdUptimeAlertsCreate, doctl.ArgUptimeAlertPeriod, "", "", "The period of time the threshold must be exceeded to trigger an alert. Possible values: `2m`, `3m`, `5m`, `10m`, `15m`, `30m`, `1h`", requiredOpt()) + cmdUptimeAlertsCreate.Example = `The following example creates an alert for an uptime check with an ID of f81d4fae-7dec-11d0-a765-00a0c91e6bf6. The alert triggers if the endpoint's latency exceed 500ms for more than two minutes: doctl monitoring uptime alert create f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --name "Example Alert" --type latency --threshold 100 --comparison greater_than --period 2m --emails "admin@example.com"` + + cmdUptimeAlertsGet := CmdBuilder(cmd, RunUptimeAlertsGet, "get ", "Get uptime alert", `Retrieves information about an uptime alert policy.`, Writer, aliasOpt("g"), displayerType(&displayers.UptimeAlert{})) + cmdUptimeAlertsGet.Example = `The following example retrieves the configuration for an alert policy with the ID ` + "`" + `418b7972-fc67-41ea-ab4b-6f9477c4f7d8` + "`" + ` that is a policy of an uptime check with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl monitoring uptime alert get f81d4fae-7dec-11d0-a765-00a0c91e6bf6 418b7972-fc67-41ea-ab4b-6f9477c4f7d8` - CmdBuilder(cmd, RunUptimeAlertsList, "list ", "List uptime alerts", `Use this command to list all of the uptime alerts for an uptime check.`, Writer, + cmdUptimeAlertsList := CmdBuilder(cmd, RunUptimeAlertsList, "list ", "List uptime alerts", `Retrieves a list of the alert policies for an uptime check.`, Writer, aliasOpt("ls"), displayerType(&displayers.UptimeAlert{})) + cmdUptimeAlertsList.Example = `The following example lists the alert policies for an uptime check with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl monitoring uptime alert list f81d4fae-7dec-11d0-a765-00a0c91e6bf6` - cmdUptimeAlertsUpdate := CmdBuilder(cmd, RunUptimeAlertsUpdate, "update ", "Update an uptime alert", `Use this command to update an uptime alert on your account. - -You can use flags to specify the uptime alert, type, threshold, comparison, notifications, and period.`, Writer, + cmdUptimeAlertsUpdate := CmdBuilder(cmd, RunUptimeAlertsUpdate, "update ", "Update an uptime alert", `Updates an uptime alert configuration.`, Writer, aliasOpt("u"), displayerType(&displayers.UptimeAlert{}), overrideCmdNS("uptime-alert")) - AddStringFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertName, "", "", "Uptime alert name", requiredOpt()) - AddStringFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertType, "", "", "Uptime alert type, must be one of latency, down, down_global or ssl_expiry", requiredOpt()) - AddIntFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertThreshold, "", 0, "Uptime alert threshold at which the alert will enter a trigger state. The specific threshold is dependent on the alert type.") - AddStringFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertComparison, "", "", "Uptime alert comparison operator used against the alert's threshold. Must be either `greater_than` or `less_than`") - AddStringSliceFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertEmails, "", nil, "Emails to send uptime alerts to. Must be emails associated with the DigitalOcean account") - AddStringSliceFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertSlackChannels, "", nil, "Slack channels to send uptime alerts to.") - AddStringSliceFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertSlackURLs, "", nil, "Slack URLs to send uptime alerts to.") - AddStringFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertPeriod, "", "", "Uptime alert period of time the threshold must be exceeded to trigger the alert. Must be one of 2m, 3m, 5m, 10m, 15m, 30m or 1h", requiredOpt()) - - CmdBuilder(cmd, RunUptimeAlertsDelete, "delete ", "Delete an uptime alert", `Use this command to delete an uptime check on your account by ID.`, Writer, + AddStringFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertName, "", "", "The name of the alert", requiredOpt()) + AddStringFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertType, "", "", "The metric to alert on. Possible values: `latency`, `down`, `down_global`, `ssl_expiry`", requiredOpt()) + AddIntFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertThreshold, "", 0, "The threshold at which to trigger the alert. The specific threshold is dependent on the alert type.") + AddStringFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertComparison, "", "", "A comparison operator used against the alert's threshold. Possible values: `greater_than` or `less_than`") + AddStringSliceFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertEmails, "", nil, "Emails addresses to send alerts. The addresses must be associated with your DigitalOcean account") + AddStringSliceFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertSlackChannels, "", nil, "Slack channels to send uptime alerts to, for example, `production-alerts`. Must be used with the `--slack-urls` flag.") + AddStringSliceFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertSlackURLs, "", nil, "A Slack webhook URL to send alerts to, for example, `https://hooks.slack.com/services/T1234567/AAAAAAAA/ZZZZZZ`.") + AddStringFlag(cmdUptimeAlertsUpdate, doctl.ArgUptimeAlertPeriod, "", "", "The period of time the threshold must be exceeded to trigger an alert. Possible values: `2m`, `3m`, `5m`, `10m`, `15m`, `30m`, `1h`", requiredOpt()) + cmdUptimeAlertsUpdate.Example = `The following example updates an alert policy with the ID ` + "`" + `418b7972-fc67-41ea-ab4b-6f9477c4f7d8` + "`" + ` that is a policy of an uptime check with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl monitoring uptime alert update f81d4fae-7dec-11d0-a765-00a0c91e6bf6 418b7972-fc67-41ea-ab4b-6f9477c4f7d8 --name "Example Alert" --type latency --threshold 100 --comparison greater_than --period 2m --emails "admin@example.com"` + + cmdUptimeAlertsDelete := CmdBuilder(cmd, RunUptimeAlertsDelete, "delete ", "Delete an uptime alert", `Deletes an uptime check on your account by ID.`, Writer, aliasOpt("d", "del", "rm")) + cmdUptimeAlertsDelete.Example = `The following example deletes an alert policy with the ID ` + "`" + `418b7972-fc67-41ea-ab4b-6f9477c4f7d8` + "`" + ` that is a policy of an uptime check with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl monitoring uptime alert delete f81d4fae-7dec-11d0-a765-00a0c91e6bf6 418b7972-fc67-41ea-ab4b-6f9477c4f7d8` return cmd } From ff855b446731a2d8ed0611beed5d3df29cede46d Mon Sep 17 00:00:00 2001 From: dbrian57 Date: Wed, 3 Jan 2024 18:22:35 -0500 Subject: [PATCH 5/5] Clarifies doc strings and adds examples for Uptime check commands --- commands/uptime_checks.go | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/commands/uptime_checks.go b/commands/uptime_checks.go index d7037ad11..38aca8c25 100644 --- a/commands/uptime_checks.go +++ b/commands/uptime_checks.go @@ -37,32 +37,37 @@ and alert you when they're slow, unavailable, or SSL certificates are expiring.` }, } - cmdUptimeChecksCreate := CmdBuilder(cmd, RunUptimeChecksCreate, "create ", "Create an uptime check", `Use this command to create an uptime check on your account. - -You can use flags to specify the uptime check, target, type, regions, and whether or not the check is enabled.`, Writer, + cmdUptimeChecksCreate := CmdBuilder(cmd, RunUptimeChecksCreate, "create ", "Create an uptime check", `Creates an uptime check on your account. Uptime checks monitor any endpoint that is accessible over HTTP, HTTPS, ping (ICMP). + + You can use this check to set up an alert policy using the `+"`"+`doctl monitoring uptime alert`+"`"+` commands.`, Writer, aliasOpt("c"), displayerType(&displayers.UptimeCheck{})) - AddStringFlag(cmdUptimeChecksCreate, doctl.ArgUptimeCheckTarget, "", "", "Uptime check target, must be a valid URL", requiredOpt()) - AddStringFlag(cmdUptimeChecksCreate, doctl.ArgUptimeCheckType, "", "", "Uptime check type, must be one of ping, http, or https. Defaults to either http or https, depending on the URL target provided") - AddStringSliceFlag(cmdUptimeChecksCreate, doctl.ArgUptimeCheckRegions, "", []string{"us_east"}, "Uptime check regions, must be a comma-separated list from any of us_east, us_west, eu_west, or se_asia. Defaults to [us_east]") - AddBoolFlag(cmdUptimeChecksCreate, doctl.ArgUptimeCheckEnabled, "", true, "Whether or not the uptime check is enabled, defaults to true") + AddStringFlag(cmdUptimeChecksCreate, doctl.ArgUptimeCheckTarget, "", "", "A valid URL to monitor", requiredOpt()) + AddStringFlag(cmdUptimeChecksCreate, doctl.ArgUptimeCheckType, "", "", "The protocol to use to monitor the target URL. Possible values: `ping`, `http`, `https`. Defaults to either `http` or `https`, depending on the URL target provided") + AddStringSliceFlag(cmdUptimeChecksCreate, doctl.ArgUptimeCheckRegions, "", []string{"us_east"}, "A comma-separated list of regions to monitor the target from. Possible values: `us_east`, `us_west`, `eu_west`, `se_asia`. Defaults to `us_east`") + AddBoolFlag(cmdUptimeChecksCreate, doctl.ArgUptimeCheckEnabled, "", true, "Whether or not the uptime check is enabled. Defaults to true") + cmdUptimeChecksCreate.Example = `The following example creates an uptime check that monitors the URL, ` + "`" + `example.com` + "`" + ` from the eastern and western regions of the Unites States: doctl monitoring uptime create --target https://example.com --type https --regions us_east,us_west --enabled true` - CmdBuilder(cmd, RunUptimeChecksGet, "get ", "Get an uptime check", `Use this command to get an uptime check on your account by ID.`, Writer, + cmdUptimeChecksGet := CmdBuilder(cmd, RunUptimeChecksGet, "get ", "Get an uptime check", `Retrieves information about an uptime check on your account.`, Writer, aliasOpt("g"), displayerType(&displayers.UptimeCheck{})) + cmdUptimeChecksGet.Example = `The following example retrieves the ID, name, and target of an uptime check: doctl monitoring uptime get f81d4fae-7dec-11d0-a765-00a0c91e6bf6` - CmdBuilder(cmd, RunUptimeChecksList, "list", "List uptime checks", `Use this command to list all of the uptime checks on your account.`, Writer, + cmdUptimeChecksList := CmdBuilder(cmd, RunUptimeChecksList, "list", "List uptime checks", `Retrieves a list of all of the uptime checks on your account.`, Writer, aliasOpt("ls"), displayerType(&displayers.UptimeCheck{})) + cmdUptimeChecksList.Example = `The following example retrieves a list of all of the uptime checks on your account and uses the ` + "`" + `--format` + "`" + ` flag to return only the ID, name, and target of each check: doctl monitoring uptime list --format ID,Name,Target` - cmdUptimeCheckUpdate := CmdBuilder(cmd, RunUptimeChecksUpdate, "update ", "Update an uptime check", `Use this command to update an uptime check on your account. + cmdUptimeCheckUpdate := CmdBuilder(cmd, RunUptimeChecksUpdate, "update ", "Update an uptime check", `Updates an uptime check on your account. -You can use flags to specify an updated uptime check name, target, type, and regions. All of these flags are required. An uptime check cannot be disabled via doctl, you must do so through the Cloud control panel or through the public API directly`, Writer, +All of these flags are required. Uptime checks cannot be disabled via `+"`"+`doctl`+"`"+`. You can only disable them using the control panel or the public API.`, Writer, aliasOpt("u"), displayerType(&displayers.UptimeCheck{})) - AddStringFlag(cmdUptimeCheckUpdate, doctl.ArgUptimeCheckName, "", "", "Uptime check name", requiredOpt()) - AddStringFlag(cmdUptimeCheckUpdate, doctl.ArgUptimeCheckTarget, "", "", "Uptime check target, must be a valid URL", requiredOpt()) - AddStringFlag(cmdUptimeCheckUpdate, doctl.ArgUptimeCheckType, "", "", "Uptime check type, must be one of ping, http, or https", requiredOpt()) - AddStringSliceFlag(cmdUptimeCheckUpdate, doctl.ArgUptimeCheckRegions, "", []string{"us_east"}, "Uptime check regions, must be a comma-separated list from any of us_east, us_west, eu_west, or se_asia", requiredOpt()) + AddStringFlag(cmdUptimeCheckUpdate, doctl.ArgUptimeCheckName, "", "", "A name for the check", requiredOpt()) + AddStringFlag(cmdUptimeCheckUpdate, doctl.ArgUptimeCheckTarget, "", "", "A valid URL to monitor", requiredOpt()) + AddStringFlag(cmdUptimeCheckUpdate, doctl.ArgUptimeCheckType, "", "", "The protocol to use to monitor the target URL. Possible values: `ping`, `http`, `https`. Defaults to either `http` or `https`, depending on the URL target provided", requiredOpt()) + AddStringSliceFlag(cmdUptimeCheckUpdate, doctl.ArgUptimeCheckRegions, "", []string{"us_east"}, "A comma-separated list of regions to monitor the target from. Possible values: `us_east`, `us_west`, `eu_west`, `se_asia`. Defaults to `us_east`", requiredOpt()) + cmdUptimeCheckUpdate.Example = `The following example updates the name, target, type, and regions of an uptime check: doctl monitoring uptime update f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --name example --target https://example.com --type https --regions us_east,us_west` - CmdBuilder(cmd, RunUptimeChecksDelete, "delete ", "Delete an uptime check", `Use this command to delete an uptime check on your account by ID.`, Writer, + cmdUptimeChecksDelete := CmdBuilder(cmd, RunUptimeChecksDelete, "delete ", "Delete an uptime check", `Deletes an uptime check on your account.`, Writer, aliasOpt("d", "del", "rm")) + cmdUptimeChecksDelete.Example = `The following example deletes an uptime check with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl monitoring uptime delete f81d4fae-7dec-11d0-a765-00a0c91e6bf6` cmd.AddCommand(UptimeAlert())