opensource/sim
3
0
Fork 0
mirror of https://github.com/simstudioai/sim.git synced 2026-09-24 15:45:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(dynatrace): add the write and configuration surfaces (#6398)

Browse Source 
* feat(dynatrace): add the write and configuration surfaces

Takes the block from 22 operations to 47. The original PR shipped the read
paths plus a few ingests; this closes the gaps that made those reads
dead-end.

The one that was a real defect: security was read-only. The audit-vulnerabilities
skill promised "a remediation queue" and then gave you no way to act on it,
even though muting is the single most common triage action. Adds mute and
unmute, singly and in bulk, plus the remediation items behind a third-party
finding, plus the Attacks API so an exploited vulnerability can be traced to
the request that exploited it.

The rest, by how much they unblock:

- Custom tags (read/add/delete). Entity tags already drive every selector in
  the block; being able to write them closes a loop that was half open.
- Settings objects (schemas, list, get, create, update, delete). This is how
  maintenance windows, alerting profiles, and management zones are configured
  in modern Dynatrace, so "open a maintenance window before the deploy" was
  simply unreachable before. The value is a schema-defined blob, so the tool
  is honestly opaque rather than falsely typed; the docs tell you to mirror an
  existing object. Update and delete carry the updateToken so a concurrent
  change fails instead of being overwritten.
- Synthetic monitors and on-demand batch execution, which pairs with the
  deploy-marker tool to gate a release on a smoke test.
- Problem comment get/update/delete, and SLO create/update/delete, completing
  CRUD that was previously half-built.

Two structural notes. Synthetic monitors are the only endpoints still on
Environment API v1, so `buildDynatraceUrl` grew a v1 sibling and the shared
base-URL normalizer now strips either version; the query builder also learned
to repeat a param per value, which Synthetic's `tag` needs. And creating an
SLO returns 201 with an empty body and the new ID in the Location header, so
that tool reads the header rather than parsing nothing.

Deliberately excluded: the Grail/DQL query API. It is the long-term successor
to the deprecated logs/search endpoint, but it authenticates with a platform
token rather than an Api-Token, so it is a second auth path and belongs in
its own change.

* fix(dynatrace): drill the documented JSON shapes, and require the tag selector

Two problems, one found in review and one worth more than it was given.

The tag operations could run without an entity selector. All three tag tools
declare `entitySelector` required, but the shared block field was only marked
required for List Entities, so the block let a workflow reach those tools with
an invalid configuration and let Dynatrace do the rejecting. My own structural
auditor missed it because it only checked that *some* visible subBlock existed
for a required param, not that the specific one was required — that check is
now precise, and it confirms these three were the only instances across all 47
operations.

The larger one: outputs were declaring `type: 'json'` for shapes the API
reference documents in full. Thirty-five of them. The top-level entities were
mapped properly, but nested payloads — a problem's evidence and impact
analysis, a vulnerability's risk assessment and global counts, an attack's
attacker, request, entry point and exploited vulnerability, a remediation
item's assessment and mute state, the synthetic execution and failure records,
the metric ingest error envelope, the DQL translation — were passed through as
anonymous blobs. A downstream block could not reference `attacker.sourceIp`
without knowing to guess it. All of those now carry their fields.

What stays opaque is now only what genuinely is, and each says why in its
description: a settings object's schema-defined value, an entity's
type-dependent property bag and relationship keys, caller-supplied synthetic
metadata, an audit log's JSON patch, the undocumented partial-success body of
log ingestion, and the handful of security-detail shapes the reference names
without expanding.

* fix(dynatrace): make the synthetic enabled filter tri-state

Review catch. `enabled` on List Synthetic Monitors is a three-way filter —
enabled, disabled, or either — and I had it as a switch. The URL builder
deliberately serializes `false` (there is a test pinning that `evaluate=false`
survives), so leaving "Enabled Only" unchecked sent `enabled=false` and
returned only the disabled monitors: exactly backwards.

Made it a dropdown with Any / Enabled only / Disabled only, matching the
monitorType field directly above it, which had the same shape and already used
an empty-id "Any" option. The params mapper sends nothing for "Any".

Checked the other nine switches rather than assuming. None share the bug: for
each of them off genuinely means false, and false is Dynatrace's own default,
so serializing it is correct. A test now pins that list so the trap cannot be
re-introduced by converting one of them, alongside a test covering all three
states of the filter.
This commit is contained in:
Waleed
2026-08-07 19:39:55 -07:00
committed by GitHub
parent 2e7e5ae804
commit d317607d2c
41 changed files with 6098 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/content/docs/en/integrations/dynatrace.mdx
+645 -9
View File
@@ -1,6 +1,6 @@
---
title: Dynatrace
description: Query Dynatrace problems, metrics, entities, logs, SLOs, and vulnerabilities
description: Manage Dynatrace problems, metrics, entities, logs, SLOs, settings, and security
---
import { BlockInfoCard } from "@/components/ui/block-info-card"
@@ -15,13 +15,16 @@ import { BlockInfoCard } from "@/components/ui/block-info-card"
**What you can reach from Sim**
- **Problems** — list and inspect Davis problems, read their root cause and affected entities, close them, and add comments.
- **Problems** — list and inspect Davis problems, read their root cause and affected entities, close them, and manage their comments.
- **Metrics** — query time series with a metric selector, discover which metrics exist, read a metric's descriptor, and push your own data points.
- **Entities** — list and inspect monitored hosts, services, applications, and Kubernetes workloads, and enumerate the entity types available for building selectors.
- **Tags** — read, add, and remove the custom tags that drive selectors, management zones, and alerting.
- **Events** — read deployments, availability changes, and annotations, and ingest your own.
- **Logs** — search log records and ingest new ones.
- **SLOs** — read service-level objectives with their attainment, error budget, and burn rate.
- **Application Security** — list and inspect vulnerabilities with risk assessment and remediation guidance.
- **SLOs** — read, create, update, and delete service-level objectives, with their attainment, error budget, and burn rate.
- **Application Security** — list and inspect vulnerabilities with risk assessment and remediation guidance, walk their remediation items, mute and unmute them singly or in bulk, and review the runtime attacks that exploited them.
- **Settings** — browse schemas and read, create, update, and delete settings objects. This is how maintenance windows, alerting profiles, management zones, and anomaly-detection thresholds are configured.
- **Synthetic** — list monitors, trigger an on-demand batch execution, and poll the batch for its result.
- **Audit log** — read who changed which configuration, and when.
**Setup**
@@ -35,7 +38,23 @@ The environment URL is the base address of your Dynatrace environment, without t
| SaaS | `https://abc12345.live.dynatrace.com` |
| Managed / environment ActiveGate | `https://your-activegate:9999/e/abc12345` |
Create the token under **Access tokens** in Dynatrace, and grant only the scopes for the operations you plan to call. Each action's `apiToken` description names the scope it needs — `problems.read`, `metrics.read`, `entities.read`, `events.read`, `logs.read`, `slo.read`, `securityProblems.read`, `auditLogs.read` for reads, and `problems.write`, `metrics.ingest`, `events.ingest`, `logs.ingest` for writes.
Create the token under **Access tokens** in Dynatrace, and grant only the scopes for the operations you plan to call. Each action's `apiToken` description names the scope it needs:
| Area | Read | Write |
| --- | --- | --- |
| Problems | `problems.read` | `problems.write` |
| Metrics | `metrics.read` | `metrics.ingest` |
| Entities and tags | `entities.read` | `entities.write` |
| Events | `events.read` | `events.ingest` |
| Logs | `logs.read` | `logs.ingest` |
| SLOs | `slo.read` | `slo.write` |
| Vulnerabilities | `securityProblems.read` | `securityProblems.write` |
| Attacks | `attacks.read` | — |
| Settings | `settings.read` | `settings.write` |
| Synthetic | `syntheticExecutions.read`, `ReadSyntheticData` | `syntheticExecutions.write` |
| Audit log | `auditLogs.read` | — |
Note that **Synthetic monitors are the one part of this integration on Environment API v1** — Sim handles the path difference, but the token scopes differ from the v2 endpoints.
**Selectors**
@@ -50,6 +69,10 @@ securityProblemSelector: status("OPEN"),riskLevel("CRITICAL")
Every selector field in the block has a wand — describe what you want in plain language and Sim writes the selector for you.
**Settings objects**
Most Dynatrace configuration is a *settings object*: a JSON `value` whose shape is defined by a *schema* such as `builtin:alerting.maintenance-window`. There is no fixed structure Sim can validate for you, so the reliable way to write one is to read an existing object of the same schema first and mirror its `value`. Get Settings Object also returns an `updateToken` — pass it back on update or delete and the call fails rather than overwriting a change someone else made in the meantime.
**Pagination**
List operations return a `nextPageKey` (a `nextSliceKey` for log search). Feed it back into the next call to read the following page. Dynatrace encodes the original filters into the cursor, so Sim sends the cursor alone and ignores the other filters on that call — which is what the API requires.
@@ -58,7 +81,7 @@ List operations return a `nextPageKey` (a `nextSliceKey` for log search). Feed i
## Usage Instructions
Integrate Dynatrace into workflows. Investigate and close Davis problems, query metrics and monitored entities, search and ingest logs, push deployment events, track SLO burn rates, review Application Security vulnerabilities, and read the audit log.
Integrate Dynatrace into workflows. Investigate and close Davis problems, query metrics and monitored entities, search and ingest logs, push deployment events, manage SLOs and their burn rates, triage and mute Application Security vulnerabilities, review runtime attacks, tag entities, manage settings objects such as maintenance windows and alerting profiles, run synthetic monitors on demand, and read the audit log.
@@ -199,6 +222,8 @@ Read metric data points from Dynatrace using a metric selector, with optional en
| ↳ `dimensionCountRatio` | number | Queried dimension tuples relative to the query limit |
| ↳ `appliedOptionalFilters` | array | Optional filters Dynatrace applied to the query |
| ↳ `dql` | json | DQL translation of the query, when available |
| ↳ `status` | string | Whether the translation succeeded |
| ↳ `query` | string | The equivalent DQL query |
| ↳ `warnings` | array | Warnings for this metric |
| ↳ `data` | array | Series of the metric, one per dimension tuple |
| ↳ `dimensions` | array | Dimension values of the series |
@@ -268,8 +293,17 @@ Push custom metric data points into Dynatrace using the metric line protocol, on
| --------- | ---- | ----------- |
| `linesOk` | number | Number of accepted data points |
| `linesInvalid` | number | Number of rejected data points |
| `ingestError` | json | Details of the invalid lines, with the line number and reason for each |
| `ingestError` | json | Details of the invalid lines |
| ↳ `code` | number | Error code |
| ↳ `message` | string | Error message |
| ↳ `invalidLines` | array | The rejected lines |
| ↳ `line` | number | Line number in the payload |
| ↳ `error` | string | Why the line was rejected |
| `warnings` | json | Warnings raised during ingestion, such as changed metric keys |
| ↳ `message` | string | Warning message |
| ↳ `changedMetricKeys` | array | Lines whose metric key Dynatrace rewrote |
| ↳ `line` | number | Line number in the payload |
| ↳ `warning` | string | What was changed |
### Dynatrace List Entities
@@ -462,7 +496,7 @@ Push log events into Dynatrace. Accepts a single log event object or an array of
| --------- | ---- | ----------- |
| `accepted` | boolean | True when Dynatrace accepted every log event \(HTTP 204\) |
| `statusCode` | number | HTTP status Dynatrace returned. 204 is full success, 200 is partial success |
| `details` | json | Partial-success details, present only when some events were rejected |
| `details` | json | Partial-success body, present only when some events were rejected. The reference does not document its shape, so it is passed through as-is |
### Dynatrace List SLOs
@@ -590,7 +624,7 @@ Read the Dynatrace audit log — who changed which configuration, when, and whet
| ↳ `timestamp` | number | Change timestamp in UTC milliseconds |
| ↳ `success` | boolean | Whether the change succeeded |
| ↳ `message` | string | Description of the change |
| ↳ `patch` | json | JSON patch of the change |
| ↳ `patch` | json | JSON patch describing the change. Its shape follows whatever settings object was edited, so it is dynamic |
| ↳ `settingsSchemaId` | string | Settings schema ID \(dt.settings.schema_id\) |
| ↳ `settingsScopeId` | string | Settings scope ID \(dt.settings.scope_id\) |
| ↳ `settingsKey` | string | Settings key \(dt.settings.key\) |
@@ -598,4 +632,606 @@ Read the Dynatrace audit log — who changed which configuration, when, and whet
| ↳ `settingsObjectSummary` | string | Settings object summary \(dt.settings.object_summary\) |
| ↳ `settingsScopeName` | string | Settings scope name \(dt.settings.scope_name\) |
### Dynatrace Mute Security Problem
Mute a single Dynatrace vulnerability with a reason, for triaging false positives or accepted risk.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the securityProblems.write scope |
| `securityProblemId` | string | Yes | ID of the security problem to mute |
| `reason` | string | Yes | One of CONFIGURATION_NOT_AFFECTED, FALSE_POSITIVE, IGNORE, OTHER, VULNERABLE_CODE_NOT_IN_USE |
| `comment` | string | No | Explanation recorded alongside the mute |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `securityProblemId` | string | ID of the muted security problem |
| `reason` | string | Reason recorded for the mute |
| `comment` | string | Comment recorded for the mute |
| `alreadyInState` | boolean | True when Dynatrace reported the problem was already muted \(HTTP 204\) |
### Dynatrace Unmute Security Problem
Unmute a single Dynatrace vulnerability, returning it to the active triage queue.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the securityProblems.write scope |
| `securityProblemId` | string | Yes | ID of the security problem to unmute |
| `reason` | string | Yes | Reason for unmuting. AFFECTED is the only value the API accepts |
| `comment` | string | No | Explanation recorded alongside the unmute |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `securityProblemId` | string | ID of the unmuted security problem |
| `reason` | string | Reason recorded for the unmute |
| `comment` | string | Comment recorded for the unmute |
| `alreadyInState` | boolean | True when Dynatrace reported the problem was already unmuted \(HTTP 204\) |
### Dynatrace Mute Security Problems
Mute several Dynatrace vulnerabilities at once with a shared reason, for bulk triage.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the securityProblems.write scope |
| `securityProblemIds` | string | Yes | Security problem IDs to mute, comma-separated or as a JSON array |
| `reason` | string | Yes | One of CONFIGURATION_NOT_AFFECTED, FALSE_POSITIVE, IGNORE, OTHER, VULNERABLE_CODE_NOT_IN_USE |
| `comment` | string | No | Explanation recorded against every muted problem |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `changedCount` | number | How many problems actually changed state, excluding those already muted |
### Dynatrace Unmute Security Problems
Unmute several Dynatrace vulnerabilities at once, returning them to active triage.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the securityProblems.write scope |
| `securityProblemIds` | string | Yes | Security problem IDs to unmute, comma-separated or as a JSON array |
| `reason` | string | Yes | Reason for unmuting. AFFECTED is the only value the API accepts |
| `comment` | string | No | Explanation recorded against every unmuted problem |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `changedCount` | number | How many problems actually changed state, excluding those already unmuted |
### Dynatrace List Remediation Items
List the remediation items of a third-party vulnerability — the components to upgrade, their affected entities, and their mute state.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the securityProblems.read scope |
| `securityProblemId` | string | Yes | ID of the third-party security problem |
| `remediationItemSelector` | string | No | Remediation item selector, e.g. vulnerabilityState\("VULNERABLE"\),muted\("false"\),exposure\("PUBLIC_NETWORK"\) |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `remediationItems` | array | Remediation items of the vulnerability. This endpoint returns no total count |
### Dynatrace List Attacks
List runtime attacks Dynatrace Application Protection detected — injection attempts, their source, and whether they were blocked.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the attacks.read scope |
| `attackSelector` | string | No | Attack selector, e.g. state\("EXPLOITED"\),attackType\("SQL_INJECTION"\),technology\("JAVA"\) |
| `from` | string | No | Start of the timeframe as UTC milliseconds, ISO 8601, or a relative expression such as now-7d. Defaults to now-30d |
| `to` | string | No | End of the timeframe in the same formats as From. Defaults to now |
| `fields` | string | No | Comma-separated optional properties to include: +attackTarget, +request, +entrypoint, +vulnerability, +securityProblem, +attacker, +managementZones, +affectedEntities |
| `sort` | string | No | Sort by displayId, displayName, attackType, state, sourceIp, requestPath, or timestamp with a + or - prefix |
| `pageSize` | number | No | Attacks per page \(max 500, default 100\) |
| `nextPageKey` | string | No | Cursor for the next page. All other filters are ignored when it is set |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `attacks` | array | Matching attacks |
### Dynatrace Get Attack
Get a single attack with its entry point, payload, attacker, and the vulnerability it exploited.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the attacks.read scope |
| `attackId` | string | Yes | ID of the attack |
| `fields` | string | No | Comma-separated optional properties to include: +attackTarget, +request, +entrypoint, +vulnerability, +securityProblem, +attacker, +managementZones |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `attack` | object | The requested attack |
### Dynatrace List Tags
List the custom tags applied to the monitored entities an entity selector matches.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the entities.read scope |
| `entitySelector` | string | Yes | Entity selector for the entities to read tags from, e.g. type\("HOST"\) |
| `from` | string | No | Start of the timeframe as UTC milliseconds, ISO 8601, or a relative expression. Defaults to now-24h |
| `to` | string | No | End of the timeframe in the same formats as From. Defaults to now |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `tags` | array | Custom tags on the matched entities |
### Dynatrace Add Tags
Add custom tags to every monitored entity an entity selector matches. Tags drive selectors, management zones, and alerting.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the entities.write scope |
| `entitySelector` | string | Yes | Entity selector for the entities to tag, e.g. type\("HOST"\),tag\("env:staging"\) |
| `tags` | json | Yes | Tags to add, as an array of objects with a key and an optional value \(e.g. \[\{"key":"owner","value":"platform"\},\{"key":"reviewed"\}\]\) |
| `from` | string | No | Start of the timeframe as UTC milliseconds, ISO 8601, or a relative expression. Defaults to now-24h |
| `to` | string | No | End of the timeframe in the same formats as From. Defaults to now |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `appliedTags` | array | Tags that were applied |
| `matchedEntitiesCount` | number | How many entities the selector matched and were tagged |
### Dynatrace Delete Tag
Remove a custom tag from every monitored entity an entity selector matches. Deletes one key-value pair, or every tag with the key.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the entities.write scope |
| `entitySelector` | string | Yes | Entity selector for the entities to untag, e.g. type\("HOST"\),tag\("owner:old"\) |
| `key` | string | Yes | Key of the tag to delete |
| `value` | string | No | Value of the tag to delete. Omit it and set Delete All With Key to remove every value of the key |
| `deleteAllWithKey` | boolean | No | Delete every tag carrying the key, regardless of value |
| `from` | string | No | Start of the timeframe as UTC milliseconds, ISO 8601, or a relative expression. Defaults to now-24h |
| `to` | string | No | End of the timeframe in the same formats as From. Defaults to now |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `matchedEntitiesCount` | number | How many entities the selector matched and had the tag removed from |
### Dynatrace List Settings Schemas
List the settings schemas available in the environment. Use it to find the schema ID for a configuration type such as builtin:alerting.profile.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the settings.read scope |
| `fields` | string | No | Comma-separated fields to include: schemaId, displayName, maturity, latestSchemaVersion, multiObject, ordered, ownerBasedAccessControl |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `schemas` | array | Available settings schemas |
### Dynatrace List Settings Objects
List settings objects — the configuration behind maintenance windows, alerting profiles, management zones, and anomaly detection.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the settings.read scope |
| `schemaIds` | string | No | Comma-separated schema IDs, e.g. builtin:alerting.profile |
| `scopes` | string | No | Comma-separated scopes, e.g. environment or HOST-06F288EE2A930951 |
| `externalIds` | string | No | Comma-separated external IDs |
| `fields` | string | No | Comma-separated fields to include: objectId, value, schemaId, schemaVersion, scope, author, modified, updateToken, created, externalId, summary, searchSummary |
| `filter` | string | No | Filter expression over created, modified, createdBy, modifiedBy, or value |
| `sort` | string | No | Sort expression, e.g. -modified |
| `pageSize` | number | No | Objects per page \(max 500, default 100\) |
| `nextPageKey` | string | No | Cursor for the next page. All other filters are ignored when it is set |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `items` | array | Matching settings objects |
### Dynatrace Get Settings Object
Get a single settings object with its value and its update token. Read it before updating so the token can guard against a concurrent change.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the settings.read scope |
| `objectId` | string | Yes | ID of the settings object |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `object` | object | The requested settings object |
### Dynatrace Create Settings Object
Create a settings object — a maintenance window, alerting profile, management zone, or any other schema-backed configuration.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the settings.write scope |
| `schemaId` | string | Yes | Schema of the object to create, e.g. builtin:alerting.maintenance-window. List Settings Schemas returns the available IDs |
| `scope` | string | Yes | Scope the object applies to, e.g. environment or an entity ID such as HOST-06F288EE2A930951 |
| `value` | json | Yes | The configuration itself. Its shape is defined by the schema — read an existing object of the same schema to see the expected fields |
| `schemaVersion` | string | No | Schema version to validate against. Defaults to the latest |
| `externalId` | string | No | External ID to correlate the object with a system outside Dynatrace |
| `validateOnly` | boolean | No | Validate the payload without creating anything |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `results` | array | One result per submitted object |
| ↳ `code` | number | Per-object HTTP status |
| ↳ `objectId` | string | ID of the created object |
| ↳ `writeError` | json | Validation error for this object, when it failed |
| ↳ `code` | number | Error code |
| ↳ `message` | string | Error message |
| ↳ `constraintViolations` | array | Which part of the value failed validation |
| ↳ `location` | string | Where the violation was found |
| ↳ `message` | string | What is wrong |
| ↳ `parameterLocation` | string | HEADER, PATH, PAYLOAD_BODY, or QUERY |
| ↳ `path` | string | Path to the offending field |
| ↳ `invalidValue` | json | The value that was rejected. Mirrors the submitted schema-defined value, so the shape is dynamic |
| `objectId` | string | ID of the created object, lifted from the first result |
### Dynatrace Update Settings Object
Update an existing settings object. Pass the update token from Get Settings Object to fail rather than overwrite a concurrent change.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the settings.write scope |
| `objectId` | string | Yes | ID of the settings object to update |
| `value` | json | Yes | The full replacement configuration. Its shape is defined by the object schema — this replaces the value rather than merging into it |
| `schemaVersion` | string | No | Schema version to validate against |
| `updateToken` | string | No | Token from Get Settings Object. When set, the update fails if the object changed in the meantime. Omit it to overwrite unconditionally |
| `validateOnly` | boolean | No | Validate the payload without saving anything |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `objectId` | string | ID of the updated object |
| `code` | number | Status Dynatrace reported for the update |
### Dynatrace Delete Settings Object
Delete a settings object. Dynatrace cannot undo this.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the settings.write scope |
| `objectId` | string | Yes | ID of the settings object to delete |
| `updateToken` | string | No | Token from Get Settings Object. When set, the delete fails if the object changed in the meantime |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `objectId` | string | ID of the deleted settings object |
| `deleted` | boolean | Always true — a failed delete raises instead |
### Dynatrace List Synthetic Monitors
List synthetic monitors and their IDs. Use it to find the monitor IDs to feed into an on-demand execution.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with one of ReadSyntheticData, DataExport, or ExternalSyntheticIntegration |
| `type` | string | No | Filter by monitor type: BROWSER or HTTP |
| `enabled` | boolean | No | Filter to enabled \(true\) or disabled \(false\) monitors |
| `location` | string | No | Filter to monitors assigned to a synthetic location |
| `tag` | string | No | Filter by tag. Comma-separate to require several tags |
| `managementZone` | number | No | Filter to monitors in a management zone, by numeric zone ID |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `monitors` | array | Matching synthetic monitors |
### Dynatrace Execute Synthetic Monitors
Trigger an on-demand batch execution of synthetic monitors, for gating a deploy on a smoke test. Returns a batch ID to poll.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with syntheticExecutions.write or ExternalSyntheticIntegration |
| `monitors` | json | Yes | Monitors to run, as an array of objects with monitorId and optional locations and executionCount \(e.g. \[\{"monitorId":"SYNTHETIC_TEST-123","executionCount":1\}\]\). Execution count caps at 10 |
| `processingMode` | string | No | STANDARD, DISABLE_PROBLEM_DETECTION, or EXECUTIONS_DETAILS_ONLY |
| `failOnPerformanceIssue` | boolean | No | Treat a performance threshold breach as a failure |
| `stopOnProblem` | boolean | No | Stop the batch as soon as one monitor reports a problem |
| `takeScreenshotsOnSuccess` | boolean | No | Capture screenshots for successful browser executions too |
| `metadata` | json | No | Key-value metadata to attach to the batch, e.g. the release version. Max 64 pairs, 1024 characters each |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `batchId` | string | ID of the batch, to poll with Get Synthetic Batch |
| `triggeredCount` | number | How many executions were triggered |
| `triggeringProblemsCount` | number | How many executions could not be triggered |
| `triggered` | array | Triggered executions, grouped by monitor |
| ↳ `monitorId` | string | Monitor that was triggered |
| ↳ `executions` | array | One entry per location the monitor ran from |
| ↳ `executionId` | string | Execution ID |
| ↳ `locationId` | string | Location the execution ran from |
| `triggeringProblemsDetails` | array | Why each untriggered execution failed to start |
| ↳ `cause` | string | Why the execution could not be triggered |
| ↳ `details` | string | Detail behind the cause |
| ↳ `entityId` | string | Entity the problem relates to |
| ↳ `executionId` | string | Execution ID, when one was assigned |
| ↳ `locationId` | string | Location the execution targeted |
### Dynatrace Get Synthetic Batch
Get the status and failures of an on-demand synthetic batch execution. Poll it after triggering to gate a deploy on the result.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with syntheticExecutions.read, ReadSyntheticData, or ExternalSyntheticIntegration |
| `batchId` | string | Yes | Batch ID returned by Execute Synthetic Monitors |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `batchId` | string | ID of the batch |
| `batchStatus` | string | RUNNING, SUCCESS, FAILED, FAILED_TO_EXECUTE, or NOT_TRIGGERED |
| `executedCount` | number | Executions completed |
| `failedCount` | number | Executions that failed |
| `failedToExecuteCount` | number | Executions that never ran |
| `triggeredCount` | number | Executions triggered |
| `triggeringProblemsCount` | number | Executions that could not be triggered |
| `failedExecutions` | array | Executions that ran and failed |
| ↳ `errorCode` | string | Error code Dynatrace reported |
| ↳ `executionId` | string | Execution ID |
| ↳ `executionStage` | string | DATA_RETRIEVED, EXECUTED, NOT_TRIGGERED, TIMED_OUT, TRIGGERED, or WAITING |
| ↳ `executionTimestamp` | number | Execution time in UTC ms |
| ↳ `failureMessage` | string | Why the execution failed |
| ↳ `locationId` | string | Location the execution ran from |
| ↳ `monitorId` | string | Monitor that was executed |
| `failedToExecute` | array | Executions that never started |
| ↳ `errorCode` | string | Error code Dynatrace reported |
| ↳ `executionId` | string | Execution ID |
| ↳ `executionStage` | string | DATA_RETRIEVED, EXECUTED, NOT_TRIGGERED, TIMED_OUT, TRIGGERED, or WAITING |
| ↳ `executionTimestamp` | number | Execution time in UTC ms |
| ↳ `failureMessage` | string | Why the execution failed |
| ↳ `locationId` | string | Location the execution ran from |
| ↳ `monitorId` | string | Monitor that was executed |
| `triggeringProblems` | array | Reasons executions could not be triggered |
| ↳ `cause` | string | Why the execution could not be triggered |
| ↳ `details` | string | Detail behind the cause |
| ↳ `entityId` | string | Entity the problem relates to |
| ↳ `executionId` | string | Execution ID, when one was assigned |
| ↳ `locationId` | string | Location the execution targeted |
| `metadata` | json | Key-value metadata supplied when the batch was triggered. Keys are caller-defined, so the shape is dynamic |
| `userId` | string | Who triggered the batch |
### Dynatrace Get Problem Comment
Get a single comment on a Dynatrace problem.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the problems.read scope |
| `problemId` | string | Yes | ID of the problem the comment belongs to |
| `commentId` | string | Yes | ID of the comment |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `comment` | object | The requested comment |
### Dynatrace Update Problem Comment
Replace the text of an existing comment on a Dynatrace problem.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the problems.write scope |
| `problemId` | string | Yes | ID of the problem the comment belongs to |
| `commentId` | string | Yes | ID of the comment to update |
| `message` | string | Yes | Replacement text of the comment |
| `context` | string | No | Context of the comment, shown alongside the author |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `problemId` | string | ID of the problem |
| `commentId` | string | ID of the updated comment |
| `message` | string | Text the comment now carries |
| `context` | string | Context of the comment |
### Dynatrace Delete Problem Comment
Delete a comment from a Dynatrace problem.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the problems.write scope |
| `problemId` | string | Yes | ID of the problem the comment belongs to |
| `commentId` | string | Yes | ID of the comment to delete |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `problemId` | string | ID of the problem |
| `commentId` | string | ID of the deleted comment |
| `deleted` | boolean | Always true — a failed delete raises instead |
### Dynatrace Create SLO
Create a service-level objective from a metric expression, target, and evaluation timeframe.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the slo.write scope |
| `name` | string | Yes | Name of the SLO |
| `target` | number | Yes | Target success rate as a percentage, e.g. 99.5 |
| `warning` | number | Yes | Warning threshold as a percentage. Must sit above the target, e.g. 99.8 |
| `timeframe` | string | Yes | Evaluation timeframe in Dynatrace notation, e.g. -1d, -1w, or now-30d |
| `evaluationType` | string | Yes | Evaluation type. AGGREGATE is the only value the API accepts |
| `description` | string | No | Description of the SLO |
| `enabled` | boolean | No | Whether the SLO is evaluated. Dynatrace defaults it to false |
| `filter` | string | No | Entity filter scoping the SLO, e.g. type\("SERVICE"\),tag\("env:prod"\) |
| `metricExpression` | string | No | Metric expression the SLO evaluates, e.g. \(100\)*\(builtin:service.errors.total.successCount:splitBy\(\)\)/\(builtin:service.requestCount.total:splitBy\(\)\) |
| `metricName` | string | No | Display name for the SLO metric |
| `burnRateVisualizationEnabled` | boolean | No | Show the error-budget burn rate on the SLO |
| `fastBurnThreshold` | number | No | Burn rate above which the SLO is considered fast-burning |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `sloId` | string | ID of the created SLO, read from the Location header |
| `name` | string | Name the SLO was created with |
### Dynatrace Update SLO
Update an existing service-level objective. Every field is replaced, so send the complete definition.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the slo.write scope |
| `sloId` | string | Yes | ID of the SLO to update |
| `name` | string | Yes | Name of the SLO |
| `target` | number | Yes | Target success rate as a percentage, e.g. 99.5 |
| `warning` | number | Yes | Warning threshold as a percentage. Must sit above the target, e.g. 99.8 |
| `timeframe` | string | Yes | Evaluation timeframe in Dynatrace notation, e.g. -1d, -1w, or now-30d |
| `evaluationType` | string | Yes | Evaluation type. AGGREGATE is the only value the API accepts |
| `description` | string | No | Description of the SLO |
| `enabled` | boolean | No | Whether the SLO is evaluated. Dynatrace defaults it to false |
| `filter` | string | No | Entity filter scoping the SLO, e.g. type\("SERVICE"\),tag\("env:prod"\) |
| `metricExpression` | string | No | Metric expression the SLO evaluates, e.g. \(100\)*\(builtin:service.errors.total.successCount:splitBy\(\)\)/\(builtin:service.requestCount.total:splitBy\(\)\) |
| `metricName` | string | No | Display name for the SLO metric |
| `burnRateVisualizationEnabled` | boolean | No | Show the error-budget burn rate on the SLO |
| `fastBurnThreshold` | number | No | Burn rate above which the SLO is considered fast-burning |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `sloId` | string | ID of the updated SLO |
| `name` | string | Name the SLO now carries |
### Dynatrace Delete SLO
Delete a service-level objective.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `environmentUrl` | string | Yes | Dynatrace environment URL \(e.g., https://abc12345.live.dynatrace.com, or https://your-activegate:9999/e/abc12345 for Managed\) |
| `apiToken` | string | Yes | Dynatrace access token \(dt0c01...\) with the slo.write scope |
| `sloId` | string | Yes | ID of the SLO to delete |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `sloId` | string | ID of the deleted SLO |
| `deleted` | boolean | Always true — a failed delete raises instead |