Custom SLAs

Custom SLAs allow you to track how your group is performing relative to configurable thresholds for metrics not already available with standard SLAs. By providing your own SQL query, you can create agreements on how you want to work and monitor how your team is performing against them. Custom SLAs follow the same edit permissions as standard SLAs. See Who can edit SLAs.

Note: Custom SLAs are not supported for groups with more than 500 members.

Create a custom SLA

To create a custom SLA for your group:

  1. Go to DX → Dashboard → SLAs.
  2. Click the + Custom SLA button at the end of the list.
  3. Configure the options in the Create custom SLA modal.
  4. Click Create.

Options

Fill out the fields in the Create custom SLA modal. To change these options later, update the same fields in the Edit custom SLA modal.

Note: Configure the Goal and Threshold in the modal, not in the SQL query. The query should return the items and values for DX to evaluate. If the query filters results using the target goal or threshold, it may return no rows for DX to evaluate.

  • SLA name: The display name for the custom SLA.
  • SQL query: The query that returns the SLA items to check. Click Open SQL editor to add or update the query. See SQL query format.
  • Goal: How the SLA should compare metric values against the threshold to determine whether they meet the target.
  • Threshold: The baseline value to compare metric values to.
  • Unit label: The unit label to display with metric values.
  • Item name: The name to display for items.
  • Send alerts: Whether DX sends alerts for this SLA through your configured messaging integration.

SQL query format

Your SQL query must return results in the exact format below. Queries that don’t match this structure will display an error.

Each row represents an SLA item to check (e.g., a PR, issue, etc.) and must include the following columns:

Column Type Description
id string or numeric A unique identifier for the item.
title string A readable name for the item.
value numeric The metric value to compare against the SLA target.
resolution_date datetime When the item was resolved, or NULL if still unresolved.
external_url string (Optional) A URL to follow when clicking on items.
user_id integer (Optional) The id of the corresponding user row in dx_users. If provided, the value will be used to automatically scope data to your members of your group. If not provided, your query must be pre-scoped to your group.

Query limits: To maintain dashboard performance, SQL queries are limited to a maximum of 2,000 items. Results exceeding this limit will be truncated.

SQL query example

The following example is based on the pre-built PR cycle time SLA. It returns open pull requests and pull requests merged within the last 90 days, with cycle time measured in days from when each pull request became ready for review. If a ready-for-review timestamp is unavailable, the query uses the pull request creation time.

SELECT
  pull_requests.id,
  pull_requests.title,
  ROUND(
    (
      EXTRACT(
        EPOCH FROM (
          COALESCE(pull_requests.merged, CURRENT_TIMESTAMP)
          - COALESCE(
              pull_requests.ready_for_review_at,
              pull_requests.created
            )
        )
      ) / 86400
    )::numeric,
    1
  ) AS value,
  pull_requests.merged AS resolution_date,
  pull_requests.external_url,
  pull_requests.dx_user_id AS user_id
FROM pull_requests
JOIN repos ON repos.id = pull_requests.repo_id
WHERE pull_requests.dx_user_id IN ($user_ids)
  AND (
    (
      pull_requests.closed IS NULL
      AND pull_requests.merged IS NULL
    )
    OR pull_requests.merged >= CURRENT_DATE - INTERVAL '90 days'
  )
  AND pull_requests.draft IS NOT TRUE
  AND pull_requests.deleted IS NOT TRUE
  AND repos.api_accessible IS NOT FALSE
  AND repos.archived IS NOT TRUE

The $user_ids variable limits the query to members of the current group. For this example, set Goal to Less than or equal (≤), enter the maximum acceptable cycle time under Threshold, and enter days under Unit label.

Edit/delete custom SLAs

To edit or delete a custom SLA for your group:

  1. Go to DX → Dashboard → SLAs.
  2. Locate the custom SLA you wish to edit or delete and click the ••• button on its right.
  3. Click either Edit or Delete.