Try it free

Create a maintenance window

  • Latest Dynatrace
  • How-to guide
  • 3-min read
  • Published Jun 23, 2026
  • Preview

Create a maintenance window to tell Dynatrace when you expect planned, non-standard operation. Dynatrace enriches telemetry with maintenance metadata during the window. Use maintenance windows to share maintenance context with your team, suppress notifications, avoid automated actions, and keep availability calculations accurate.

Prerequisites

  • You have an IAM policy that allows write access to the builtin:maintenance-windows schema:

    ALLOW settings:objects:read, settings:objects:write, settings:schemas:read
    WHERE settings:schemaId = "builtin:maintenance-windows";

  • If you plan to use custom scheduling rules or calendars, create them before configuring the maintenance window:

    • Set up a scheduling rule
    • Set up a calendar

Create a maintenance window

You can create a maintenance window either in the Dynatrace web UI or via API.

Via web UI

  1. Go to Settings > General > Maintenance windows.

  2. Select New maintenance window.

  3. Enter the basic details such as the maintenance window Name and Description.

  4. Select Next.

  5. Configure the schedule. Your options depend on whether the window repeats.

    • For a One time window, enter a Start date and time, Duration, and Timezone. Select or clear Automatic deletion depending on your needs.
    • For a Recurring window, enter a Start time, Duration, and Recurrence rule. To add or modify rules, select Manage rules. Select or clear Automatic deletion depending on your needs.

  6. Select Next.

  7. Enter the Scope filter criteria so only matching telemetry is marked as under maintenance in the Maintenance Scope field. Start entering text in the field to get suggestions. Select Preview to preview the data. Under Preview results, you can find a list of event types you can enrich with metadata.

  8. Select Save to save the maintenance window and verify that it appears in the Maintenance windows table as Active.

If you create a recurring maintenance window, ensure that the required scheduling rule and calendar are already available.

Via API

  1. Send a POST request to api/v2/settings/objects.

  2. In the request body, set:

    • schemaId to builtin:maintenance-windows
    • scope to environment

  3. In value, define the basic details, schedule configuration, and filter criteria.

  4. Submit the request and store the returned object ID for updates.

  5. Verify that the new maintenance window is in the table under Settings > General > Maintenance windows. The window is set to Active by default.

If you create a recurring maintenance window, use the same shared scheduling rules and calendars as in the web UI flow.

Deactivate or delete a maintenance window

You can pause a maintenance window without losing its configuration, or remove it entirely. Neither action stops a window that is already running; it continues until its configured end time.

Via web UI

  1. Go to Settings > General > Maintenance windows.

  2. Find the maintenance window in the list.

  3. Choose one of the following:

    • To pause the window, set the toggle to Inactive. The configuration is preserved and you can re-activate it later by setting the toggle to Active.
    • To remove the window permanently, open the menu, select Delete, and select Delete permanently.

Via API

  • To pause the window without deleting it, update the window's state via the Settings API.

  • To delete a maintenance window, send a DELETE request to api/v2/settings/objects/{objectId}.

Use filter criteria

Apply the filter criteria to target the telemetry you want to mark as maintenance. Use common Grail primary fields and Grail primary tags so your filter criteria work consistently.

The UI provides a filter field that converts your input to DQL matcher syntax automatically. For the API and configuration as code, use the DQL matcher syntax directly.

Filter criteria examples

The examples below show common filter patterns that you can adapt to scope a maintenance window to specific entities, tags, or Grail primary fields.

Filter criteria examples

Define filter criteria for a specific Kubernetes cluster (Grail primary fields):

k8s.cluster.name = k8s-02
k8s.cluster.name == "k8s-02"

Define filter criteria for an Azure resource group (Grail primary fields):

azure.resource.group = my-resource-group
azure.resource.group == "my-resource-group"

Define filter criteria by environment (using Grail primary tags):

primary_tags.environment = staging
primary_tags.environment == "staging"

Define filter criteria for a host:

host.name = HOST-CWS-4-IG-1-HG-200001
host.name == "HOST-CWS-4-IG-1-HG-200001"

Define filter criteria for a host group (Grail primary fields):

dt.host_group.id = host-group-1234
dt.host_group.id == "host-group-1234"

Define filter criteria for a process:

dt.smartscape.process = PROCESS-00970A58C3D6A4AE
dt.smartscape.process == "PROCESS-00970A58C3D6A4AE"

Define filter criteria for a service:

dt.smartscape.service = SERVICE-01B5009DAFF92605
dt.smartscape.service == "SERVICE-01B5009DAFF92605"

Define filter criteria for an HTTP check:

dt.entity.http_check = HTTP_CHECK-0A77C3D2E1F82B5A
dt.entity.http_check == "HTTP_CHECK-0A77C3D2E1F82B5A"

Define filter criteria for a Synthetic test:

dt.entity.synthetic_test = SYNTHETIC_TEST-0B44D7A3C2E91F67
dt.entity.synthetic_test == "SYNTHETIC_TEST-0B44D7A3C2E91F67"

Define filter criteria for a frontend:

frontend.name = easytravel-frontend
frontend.name == "easytravel-frontend"

Define filter criteria for data coming from an extension:

device = mysql-postgresql:5432:DemoDatabase
device == "mysql-postgresql:5432:DemoDatabase"

Combined example using AND:

k8s.cluster.name = k8s-02 AND primary_tags.environment = staging
k8s.cluster.name == "k8s-02" AND primary_tags.environment == "staging"

Combined example using OR:

k8s.cluster.name = k8s-01 OR k8s.cluster.name = k8s-02
k8s.cluster.name == "k8s-01" OR k8s.cluster.name == "k8s-02"

Filter multiple values using IN:

primary_tags.environment IN (staging, production, testing)
matchesValue(primary_tags.environment, {"staging", "production", "testing"})

Next steps

  • See Use maintenance window data to query maintenance data, manage problems, and configure workflow triggers.
  • See Maintenance window lifecycle to understand the maintenance window lifecycle, Grail events, and OpenPipeline enrichment.
Related tags
Dynatrace Platform