Creating New Runtime Alert Policies

See below how to set up a policy for runtime monitoring and notifications.

Options:

How to create a new policy

If you prefer, you can follow along with the steps in the video.

  1. Click on the + NEW POLICY button located in the top right corner of the Runtime Alerts page.
    list of policies and the button new policy

  2. On the POLICY screen, provide the essential details for the policy (such as name, classification), set up monitoring parameters (type, limits, periods), and choose how often it should run.
    policy information

  3. Define the items to be monitored (MONITORED ITEMS), selecting APIs, environments, resources, and operations.
    Once you’ve defined everything you want to monitor, click on ADD ITEM.
    You can always come back later to add or remove APIs/events from this policy.

  4. You can include multiple APIs for each policy. Simply repeat step 3 as needed.

    • See details about the fields to be filled.

    • Understand how the fixed and dynamic settings (any and all) work.

    • While there’s no limit to the number of APIs a policy can monitor, we suggest keeping it to a maximum of 50 for better notification management.

  5. On the ACTIONS screen, choose and configure one or more communication channels, which can be:

  6. Review your settings and click SAVE.

    Remember to click SAVE to complete the policy creation. Unsaved settings will be lost.

Also read about the concept of policies and the definitions and specifics of each field mentioned in the steps above.



Detailed Description

Click on the links above to see the details of each field outlined in the policy creation steps.


horizontal line with four circles

1 POLICY

  • Policy info

    • Policy name: Assign a name to the policy;

    • Classification: Choose a classification (Neutral, Success, Warning, or Critical), and

    • Tag: Optionally, define a tag. Tags help organize your policies and facilitate finding alerts.


  • Monitored Event Details:

    • Type: Specify the parameter to monitor, which can be:

      • Total Calls: Monitor the total number of calls within a specified period;

      • Availability: availability of a given operation for a resource.
        An API is considered available if it does not return a 5xx error;

      • Latency: average latency in a given period; or

      • HTTP Response Status: returned status code of a call. You can specify the code (e.g., 504) or family (e.g., 5xx).
        The response code must be between 100 and 599 or equal to 1xx, 2xx, 3xx, 4xx, 5xx.

        You can include multiple families (e.g., 5xx, 4xx) or codes (e.g., 401, 403).
        If a family is specified, it overrides the specific code (e.g., 5xx will be considered instead of 504).

    • Threshold: set the monitoring thresholds. Choose a comparison operator, which can be "more than" or "less than," and specify the value (Amount):

      • Total Calls: total number of calls;

      • Availability: percentage of availability;

      • Latency: total in milliseconds;

      • HTTP Response Status: define the value and indicate whether the value is a percentage or a number of calls.

    • Period: time interval to be considered for the value entered.

      • Amount: define a value between 1 and 1440 (for minutes) or between 1 and 2 (for hours);

      • Unit: choose between minutes and hours;

      • Past period: to enable this field, select the "Compare with past period" checkbox and provide the past interval for comparison.

        COMPARE WITH PAST PERIOD allows you to compare the recorded reference values for monitoring with past periods for notification triggering. In this scenario, the values entered in the fields of the MONITORED OPERATION section will not trigger a notification upon reaching an absolute manner but will trigger relative to past performance.performance.

        Example

        Let’s consider an alert for total calls (Total Calls) that sends a notification when there are more than 100 requests using a specific operation on a particular resource within a one-minute period. If you do not enable comparison with a past period, the notification will be sent whenever more than 100 requests occur in one minute.

        However, if we configure a comparison with the same period last week, the notification will only be sent when more than 100 requests per minute are observed relative to the same period last week.

        This means that if there are 120 requests recorded in a given minute, but during the same period last week, there were 80 requests per minute, no notification will be triggered because the comparison of requests reveals an increase of 40, which is less than the configured reference value (which is 100 requests).

        There are three period options available for comparison, in this order:
        1. previous <period> <unit> (if the configured period is 2 and the reference unit is minutes, it will be last 2 minutes, if the period is 5 and the unit is hours, last 5 hours);
        2. same period on the previous day; and
        3. same period in the previous week.

    • Minimum amount of requests to trigger actions:

      • Indicate how many calls with the specified settings must happen to trigger the actions (alerts).

      • This field is only valid for the 'Availability' and 'Latency' types.
        For 'Total Calls' and 'HTTP Response Status', the number of calls is defined Threshold, by selecting 'Calls' under 'Unit'.


  • Schedule
    This determines how often the system checks for conditions to trigger notifications. Choose:

    • Predefined: to select from preset intervals (1, 5, 10, or 30 minutes; 1 hour; or every day at 00:00) or

    • Cron Expression: to input a Cron-type scheduling expression (refer to the table below).

      A Cron Expression is a string that defines a periodic schedule according to a specific format. The Cron Expression field accepts schedules composed of five fields:

      <minute> <hour> <day of the month> <month> <day of the week>

      To complete the fields, you can use numbers and certain special characters:

      • * means "every";

      • ? means "any" and are used in month and day of the week;

      • L means "last" and are used in month and day of the week;

      • three-letter initials of days of the week in English (such as MON and TUE);

      • , and - represent ranges (the former includes only the specified points, while the latter covers the entire range between them).

      Some examples:

      30 10 ? * *: check every day at 10:30 AM.
      0 14 ? * MON-FRI: check from Monday to Friday at 2:00 PM.
      0 14 ? * MON,FRI: check at 2:00 PM, only on Mondays and Fridays.
      0 8 * JUN ?: check at 8:00 AM every day in the month of June.
      10 17 L * ?: check at 5:10 PM on the last day of each month.

    • Silent interval

      It is possible to silence a notification for a predetermined time by enabling the SILENT INTERVAL option. This is useful, for example, when you know that there is an unavailability issue with your API and you want to temporarily disable a notification. See also how to permanently disable alerts.

      To configure the silence time, fill in with the desired interval, informing a number and a unit (minutes or hours).

      The maximum time that can be configured is 24 hours (or 1440 minutes).

      If the option remains enabled, the alert will be reactivated after the configured interval. Then, the next notification triggered by an event will be sent normally and it will trigger a new silence period.

      Example

      Imagine that you set a silence period of 4 hours for an alert that sends a notification when more than 20% of the requests to a given API return an HTTP error status. During 4 hours, your alert will not generate notifications. Imagine that after 5 hours, the SILENT INTERVAL field remains enabled and 30% of requests result in an error status. In this case, a notification will be sent, and this notification will trigger a new 4-hour silence period (starting from this last notification).


horizontal line with four circles

2 MONITORED ITEMS

  • Add API
    Define the items to be monitored.
    Select:

    • API Name: an API. Here you will find the APIs available in the API Platform catalog;

    • Environment: one or more available environments for the selected API;

    • Resources: one or more resources;

    • Operation: one or more operations.

      For Environment, Resources, and Operation, you can also choose: Select All: to consider all environments for monitoring (fixed monitoring: the monitored items are always the ones specified at the moment of the policy creation) or Any: to consider any item for monitoring (dynamic monitoring: updates to the API will be automatically added to the policy). See the difference between All and Any.

  • List of policies
    The items added to the policy will be available in this list, which has the following columns:

    • API Name: the name of the API;

    • Summary: the number of selected environments, resources, and operations for monitoring. The quantity is not displayed for items with dynamic monitoring — they are described as "any". Items with fixed monitoring are presented with the number representing the total available quantity (of environment, resource, or operation) at the time of policy creation.

    • Actions: actions to edit or delete the item.


horizontal line with four circles

3 ACTIONS

The action of sending a notification can be configured and customized in this step of the setup.

Follow the steps below to configure an action. Click the links for more details.

  1. Click on +, next to an action.

  2. Fill in the indicated fields.
    Click to see more details about the configuration of:

  3. Optionally, enable "Add Custom Message" and personalize the message to be sent with the notification.
    Available for: email, Slack, Microsoft Teams, and Webhook.

  4. Click SAVE.
    At least one action must be configured.

    Saving the action does not save the policy. To save the policy, click SAVE at the end of the setup process (step 4 REVIEW).

  5. You can configure more than one action per policy.
    To configure additional actions, repeat steps 1 to 4.

  6. Click NEXT to proceed to the next step of the policy setup.

Email

When this action is configured, a notification email is sent whenever an event that triggers an alert occurs.

Follow the steps below to configure the action of sending an email:

  1. Click + and enter one or more email addresses in the Emails field.

    Use commas to separate the emails.

  2. If desired, include an additional custom message by clicking ADD CUSTOM MESSAGE.

    The message can be written in plain text or HTML format.

  3. Click SAVE.

After a recipient has been added, they will receive an email to authorize the receipt of notifications. The confirmation link in the email will be valid for 24 hours.

Only one notification email will be sent per policy (and not per operation).

Slack

When this action is configured, a notification is sent to a Slack channel whenever an event that triggers an alert occurs.

Follow the steps below to configure the action of sending a notification to Slack:

  1. Click ] and select the Slack workspace to be used or add a new one by clicking btn:[ ADD WORKSPACE.
    See more details on how to add a new workspace.

  2. Choose a channel.
    By default, only public channels will be displayed.
    See how to add a private channel.

    Only one channel can be chosen per alert.

  3. If desired, include an additional custom message (click toggle button next to ADD CUSTOM MESSAGE to enable the field).

  4. Click SAVE.

  5. If you want to send a test message: click indication of expand option next to "Slack" to expand it and click SEND TEST MESSAGE.

Microsoft Teams

When this action is configured, a notification is sent to Microsoft Teams whenever an event that triggers an alert occurs.

Follow the steps below to configure the action of sending a notification to Microsoft Teams:

  1. In Microsoft Teams, create an incoming webhook.
    See the Microsoft Teams documentation.

  2. Click + in the "Incoming Webhook URL" field and enter the URL you received from Microsoft Teams when creating the incoming webhook.

  3. If desired, include an additional custom message (click toggle button next to ADD CUSTOM MESSAGE to enable the field).

  4. Click SAVE.

  5. If you want to send a test message: click indication of expand option next to "Microsoft Teams" to expand it and click SEND TEST MESSAGE.

Webhook

When this action is configured, an HTTP POST request is sent to an endpoint whenever an event that triggers an alert occurs.

With this alert you can trigger a specific API. The payload of this request will include the monitored parameters of the alert and, optionally, an additional message.

Follow these steps to configure a webhook:

  1. Click + and enter the URL of the endpoint.

  2. If desired, select a credential or create a new one by clicking + NEW CREDENTIAL.
    See details on how to create a webhook.

  3. If desired, include an additional custom message (click toggle button next to ADD CUSTOM MESSAGE to enable the field).

    The message will be included in the request payload, identified by "customMessage".

  4. Click SAVE.

  5. If needed, see an example of JSON or JSON schema. Click {…​} VIEW SAMPLE and select a tab.

WhatsApp

When this action is configured, a message is sent via WhatsApp to one or more numbers whenever an event that triggers an alert occurs.

Follow the steps below to configure the action of sending a notification to WhatsApp:

  1. Click + and select one or more contacts.
    The contacts are in the Phone Catalog.
    Click to see how to add a new contact.

  2. Click SAVE.

  3. If you want to send a test message: next to "WhatsApp", click indication of expand option to expand it and click SEND TEST MESSAGE.

To use WhatsApp as a notification method, you need to activate it for your environment. Contact us for more details.


horizontal line with four circles representing each step of the process

4 REVIEW

Check the details and parameters for your policy.

If you need to edit it, go back to previous steps by clicking the breadcrumb navigation at the top of the page or the button BACK, at the bottom of the page.

When finished, click SAVE.

You must click SAVE for the settings to be saved.

The created policy will be displayed in the policy list — click to see details of the columns and actions available.


How it works

After a policy has been created, the monitoring event will be executed according to the indicated parameters for all selected items (APIs/Operations), and if it is detected that a certain API/operation fits this event, the chosen notification in the policy will be triggered individually for each API/operation.

Here is an example. Watch the video or read the text below.


I created a policy to be executed every 5 minutes for the following APIs/Operations (Monitored Items):

  • 1. API Orders 1.0, Environment Production, Resource Orders, Operation GE T/list and GET /items

  • 2. API Delivery 1.0, Environment Any, Resource Any, Operation Any

  • 3. API Tokens 1.0, Environment All, Resource Tokens, Operation All

This policy will monitor if the number of calls exceeds 10 with a status code of 200 within the last 5 minutes.

Imagine the following scenarios:

1. API Orders 1.0, Environment Production, Resource Orders, Operation GET /list and GET /items

Suppose that:

  • for the Operation GET /list, the condition is true, that is, it had more than 10 calls with status code 200 in the last 5 minutes at the time of verification, and

  • for the Operation GET /items, the condition is false.

→ Then the notification will be sent only regarding the GET /list operation. Note that only the API deployed to the Production Environment will be monitored.

2. API Delivery 1.0, Environment Any, Resource Any, Operation Any

Suppose that:

  • for Operation (Any), some operations exceeded 10 calls with status code 200 in the last 5 minutes at the time of verification.

→ Then a notification will be triggered regarding each individual operation. Note that, as the verification is performed in any Environment, the notifications will also be sent individually for each Environment and Operation.

3. API Tokens 1.0, Environment All, Resource Tokens, Operation All

Suppose that:

  • Some operations of the Tokens Resource exceeded 10 calls with status code 200 in the last 5 minutes at the time of verification.

→ Then the policy will be triggered and a notification will be sent for each operation that meets the policy’s condition.

→ The operations for this resource that did not exceed 10 calls with status code 200 will not trigger the policy and therefore notifications will not be sent.

→ By choosing "All" for environments and operations, only those existing at the time of policy creation or editing will be considered. Any new environments or operations created afterward will not be monitored.

On the other hand, by choosing "Any" for an API criteria (Environments, Resources, Operations), all options of that item will be considered in the monitoring, even those created after the policy’s creation or editing. See more details in Fixed or Dynamic Settings.


Example situations

Condition: number of calls exceeds 10 AND status code 200 AND last 5 minutes

Monitored Items

Condition is True?

Number of Notifications

1. API Orders 1.0, Environment Production, Resource Orders, Operation GET /list and GET /items

GET /list: Yes
GET /items: No

Only 1 for GET /list that is in the production environment. Even if this operation exists in another environment, it will not be monitored.

2. API Delivery 1.0, Environment Any, Resource Any, Operation Any

Yes for any operation

One notification per operation and per environment
E.g., every 5 minutes, if 4 environments with 5 operations each meet the condition, a total of 20 notifications will be sent.

3. API Tokens 1.0, Environment All, Resource Tokens, Operation All

Yes for all operations of the Tokens Resource in all existing environments at the time of policy creation

One notification per operation and per environment, for items existing at the time of policy creation
E.g., every 5 minutes, if 4 environments with 5 operations each (that already existed at the time of policy creation) meet the condition, a total of 20 notifications will be sent.

Fixed or Dynamic Settings (all or any)

The All and Any options define whether the policy is fixed (the parameters that trigger the alert are always the same as you configured/edited) or dynamic (the parameters are automatically updated with the API).

  • All: by selecting all items (in Environment, Resource, and Operation) to be monitored by a policy, all items of the API selected at the time of policy creation or editing will be considered for triggering the alert. Items created after this definition will not enter the monitoring.

  • Any: by selecting any item (in Environment, Resource, and Operation) to be monitored by a policy, any item of the API will be considered for monitoring, including additions to the API that occur after the policy definition.

Using the Any option provides greater dynamism to monitoring, as it will be automatically updated when new operations are added to the API.

On the other hand, the All option allows you to keep the monitoring parameters fixed as initially configured. New additions to the APIs must be manually configured to be included in the alert triggers.

See an example of how these options work in an API monitoring scenario in the video (at 02:10).

Temporarily unavailable:

  • warning icon indication that informs when an API operation is not deployed in the environment selected for monitoring.

  • copy icon option to clone a policy.

These features will return in future releases.

example of monitoring from the previous version with the indications
Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]