@dynatrace-sdk/client-service-level-objectives

Management API for service-level objectives, templates and evaluating service-level objectives

Installation

npm install @dynatrace-sdk/client-service-level-objectives

Getting help

• Visit SDK for Typescript guide in the Dynatrace Developer
• Ask a question in the Dynatrace Community

License

This SDK is distributed under the Apache License, Version 2.0, see LICENSE for more information.

API reference

Full API reference for the latest version of the SDK is also available at the Dynatrace Developer.

objectiveTemplatesClient

import { objectiveTemplatesClient } from '@dynatrace-sdk/client-service-level-objectives';

getObjectiveTemplateById

Get an objective template by ID

One of the following scopes is required:

• slo:objective-templates:read
• slo:slos:read

Parameters

| Name | Type | Description | | --- | --- | --- | |config.id*required|string|objective template ID |

Returns

| Return type | Status code | Description | |---|---|---| |ObjectiveTemplate|200|A single objective template|

Throws

| Error Type | Error Message | |---|---| |BadRequest|Malformed request or invalid parameters.| |Unauthorized|API token or tenant missing or corrupt.| |Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.| |NotFound|Not found.| |TooManyRequests|The client has sent too many requests in a given amount of time and has been rate-limited.| |InternalServerError|Internal server error.|

import { objectiveTemplatesClient } from "@dynatrace-sdk/client-service-level-objectives";

const data =
  await objectiveTemplatesClient.getObjectiveTemplateById({
    id: "...",
  });

getObjectiveTemplates

List objective templates

One of the following scopes is required:

• slo:objective-templates:read
• slo:slos:read

Parameters

| Name | Type | Description | | --- | --- | --- | |config.filter|string|The filter parameter, as explained here. Filtering is supported on the following fields: id name builtIn deprecated applicableScope tag.key and tag.value | |config.page|number|The page number to retrieve, 1-indexed. Can't be used together with page-key. | |config.pageKey|string|Cursor for the next page of results, obtained from nextPageKey in the previous response. Can't be used together with page. | |config.pageSize|number|How many items to return at one time (max 500) | |config.sort|string|The sort parameter, as explained here. Sorting is supported on the following fields: name |

Returns

| Return type | Status code | Description | |---|---|---| |ObjectiveTemplateList|200|A paged array of objective templates|

Throws

| Error Type | Error Message | |---|---| |BadRequest|Malformed request or invalid parameters.| |Unauthorized|API token or tenant missing or corrupt.| |Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.| |TooManyRequests|The client has sent too many requests in a given amount of time and has been rate-limited.| |InternalServerError|Internal server error.|

import { objectiveTemplatesClient } from "@dynatrace-sdk/client-service-level-objectives";

const data =
  await objectiveTemplatesClient.getObjectiveTemplates();

serviceLevelObjectivesClient

import { serviceLevelObjectivesClient } from '@dynatrace-sdk/client-service-level-objectives';

createSlo

Add a new service-level objective

Required scope: slo:slos:write

Parameters

| Name | Type | | --- | --- | |config.body*required|SloConfig|

Returns

| Return type | Status code | Description | |---|---|---| |Slo|201|Created|

Throws

| Error Type | Error Message | |---|---| |BadRequest|Malformed request or invalid parameters.| |Unauthorized|API token or tenant missing or corrupt.| |Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.| |TooManyRequests|The client has sent too many requests in a given amount of time and has been rate-limited.| |InternalServerError|Internal server error.|

import { serviceLevelObjectivesClient } from "@dynatrace-sdk/client-service-level-objectives";

const data = await serviceLevelObjectivesClient.createSlo({
  body: {
    name: "New SLO",
    sliReference: {
      templateId: "...",
      variables: [
        {
          name: "hostIds",
          value: '"HOST-123456789ABCDEFG"',
        },
      ],
    },
    customSli: {
      indicator: "timeseries sli=avg(dt.host.cpu.idle)",
    },
    criteria: [{ timeframeFrom: "now-7d", target: 99.8 }],
  },
});

deleteSlo

Delete a service-level objective by ID

Required scope: slo:slos:write

Parameters

| Name | Type | Description | | --- | --- | --- | |config.id*required|string|service-level objective ID | |config.optimisticLockingVersion*required|string|The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users. It's generated upon retrieval (GET requests). If set on update (PUT request) or deletion, the update/deletion will be allowed only if there wasn't any change between the retrieval and the update. |

Returns

| Return type | Status code | Description | |---|---|---| |void|204|No Content|

Throws

| Error Type | Error Message | |---|---| |BadRequest|Malformed request or invalid parameters.| |Unauthorized|API token or tenant missing or corrupt.| |Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.| |NotFound|Not found.| |TooManyRequests|The client has sent too many requests in a given amount of time and has been rate-limited.| |InternalServerError|Internal server error.|

import { serviceLevelObjectivesClient } from "@dynatrace-sdk/client-service-level-objectives";

const data = await serviceLevelObjectivesClient.deleteSlo({
  id: "...",
  optimisticLockingVersion: "...",
});

getSloById

Get a service-level objective by ID

Required scope: slo:slos:read

Parameters

| Name | Type | | --- | --- | |config.id*required|string|

Returns

| Return type | Status code | Description | |---|---|---| |Slo|200|A single service-level objective|

Throws

| Error Type | Error Message | |---|---| |BadRequest|Malformed request or invalid parameters.| |Unauthorized|API token or tenant missing or corrupt.| |Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.| |NotFound|Not found.| |TooManyRequests|The client has sent too many requests in a given amount of time and has been rate-limited.| |InternalServerError|Internal server error.|

import { serviceLevelObjectivesClient } from "@dynatrace-sdk/client-service-level-objectives";

const data = await serviceLevelObjectivesClient.getSloById({
  id: "...",
});

getSlos

List service-level objectives

Required scope: slo:slos:read

Parameters

| Name | Type | Description | | --- | --- | --- | |config.filter|string|The filter parameter, as explained here. Filtering is supported on the following fields: id name tag.key and tag.value | |config.page|number|The page number to retrieve, 1-indexed. Can't be used together with page-key. | |config.pageKey|string|Cursor for the next page of results, obtained from nextPageKey in the previous response. Can't be used together with page. | |config.pageSize|number|How many items to return at one time (max 500) | |config.sort|string|The sort parameter, as explained here. Sorting is supported on the following fields: name |

Returns

| Return type | Status code | Description | |---|---|---| |SloObjectsList|200|A paged array of service-level objectives|

Throws

| Error Type | Error Message | |---|---| |BadRequest|Malformed request or invalid parameters.| |Unauthorized|API token or tenant missing or corrupt.| |Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.| |TooManyRequests|The client has sent too many requests in a given amount of time and has been rate-limited.| |InternalServerError|Internal server error.|

import { serviceLevelObjectivesClient } from "@dynatrace-sdk/client-service-level-objectives";

const data = await serviceLevelObjectivesClient.getSlos();

updateSlo

Update a service-level objective by ID

Required scope: slo:slos:write

Parameters

| Name | Type | Description | | --- | --- | --- | |config.body*required|SloConfig| | |config.id*required|string|service-level objective ID | |config.optimisticLockingVersion*required|string|The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users. It's generated upon retrieval (GET requests). If set on update (PUT request) or deletion, the update/deletion will be allowed only if there wasn't any change between the retrieval and the update. |

Returns

| Return type | Status code | Description | |---|---|---| |void|200|Updated|

Throws

| Error Type | Error Message | |---|---| |BadRequest|Malformed request or invalid parameters.| |Unauthorized|API token or tenant missing or corrupt.| |Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.| |NotFound|Not found.| |Conflict|Optimistic locking failed, or the document is actively locked\ \ by another user, or some other conflict.| |TooManyRequests|The client has sent too many requests in a given amount of time and has been rate-limited.| |InternalServerError|Internal server error.|

import { serviceLevelObjectivesClient } from "@dynatrace-sdk/client-service-level-objectives";

const data = await serviceLevelObjectivesClient.updateSlo({
  id: "...",
  optimisticLockingVersion: "...",
  body: {
    name: "New SLO",
    sliReference: {
      templateId: "...",
      variables: [
        {
          name: "hostIds",
          value: '"HOST-123456789ABCDEFG"',
        },
      ],
    },
    customSli: {
      indicator: "timeseries sli=avg(dt.host.cpu.idle)",
    },
    criteria: [{ timeframeFrom: "now-7d", target: 99.8 }],
  },
});

serviceLevelObjectivesEvaluationClient

import { serviceLevelObjectivesEvaluationClient } from '@dynatrace-sdk/client-service-level-objectives';

cancelSloEvaluation

Cancels the SLO evaluation and returns the result if the evaluation was already finished, otherwise discards it.

Required scope: slo:slos:read

For information about the required Grail permissions, see the Bucket and table permissions in Grail documentation.

Parameters

| Name | Type | | --- | --- | |config.evaluationToken*required|string|

Returns

| Return type | Status code | Description | |---|---|---| |SloEvaluationCancelResponse|200|SLO evaluation result| |void|202|The SLO evaluation was still running and is now cancelled.|

Throws

| Error Type | Error Message | |---|---| |BadRequest|Malformed request or invalid parameters.| |Unauthorized|API token or tenant missing or corrupt.| |Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.| |Gone|The SLO Evaluation for the given evaluationToken isn't available anymore.| |TooManyRequests|The client has sent too many requests in a given amount of time and has been rate-limited.| |InternalServerError|Internal server error.|

import { serviceLevelObjectivesEvaluationClient } from "@dynatrace-sdk/client-service-level-objectives";

const data =
  await serviceLevelObjectivesEvaluationClient.cancelSloEvaluation(
    { evaluationToken: "FQ5aVZERXZNMjR1SzVnPT0ifQ==" },
  );

pollSloEvaluation

Polls an SLO evaluation

Required scope: slo:slos:read

For information about the required Grail permissions, see the Bucket and table permissions in Grail documentation.

Parameters

| Name | Type | Description | | --- | --- | --- | |config.evaluationToken*required|string| | |config.requestTimeoutMilliseconds|number|How long to wait for the evaluation result before returning in milliseconds. If the evaluation finishes within this time, the result is returned directly (200). If not, the response contains the evaluationToken for further polling. |

Returns

| Return type | Status code | Description | |---|---|---| |SloEvaluationResponse|200|SLO evaluation result|

Throws

| Error Type | Error Message | |---|---| |BadRequest|Malformed request or invalid parameters.| |Unauthorized|API token or tenant missing or corrupt.| |Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.| |Gone|The SLO Evaluation for the given evaluationToken isn't available anymore.| |TooManyRequests|The client has sent too many requests in a given amount of time and has been rate-limited.| |InternalServerError|Internal server error.|

import { serviceLevelObjectivesEvaluationClient } from "@dynatrace-sdk/client-service-level-objectives";

const data =
  await serviceLevelObjectivesEvaluationClient.pollSloEvaluation(
    { evaluationToken: "FQ5aVZERXZNMjR1SzVnPT0ifQ==" },
  );

startSloEvaluation

Starts an SLO evaluation

Required scope: slo:slos:read

For information about the required Grail permissions, see the Bucket and table permissions in Grail documentation.

Parameters

| Name | Type | | --- | --- | |config.body*required|SloEvaluationRequest|

Returns

| Return type | Status code | Description | |---|---|---| |SloEvaluationResponse|200|SLO evaluation result| |SloEvaluationResponse|202|SLO evaluation started|

Throws

| Error Type | Error Message | |---|---| |BadRequest|Malformed request or invalid parameters.| |Unauthorized|API token or tenant missing or corrupt.| |Forbidden|Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity isn't accessible to the user.| |TooManyRequests|The client has sent too many requests in a given amount of time and has been rate-limited.| |InternalServerError|Internal server error.|

import { serviceLevelObjectivesEvaluationClient } from "@dynatrace-sdk/client-service-level-objectives";

const data =
  await serviceLevelObjectivesEvaluationClient.startSloEvaluation(
    {
      body: {
        id: "A5LTU5YTVjNTcxODI5OL7vVN4V2t6t",
        customTimeframe: { timeframeFrom: "now-7d" },
      },
    },
  );

Types

ConstraintViolation

Contains information about a constraint violation caused by invalid input.

| Name | Type | Description | | --- | --- | --- | |message*required|string|The constraint violation description message | |path|string|The path of the parameter that caused the constraint violation |

Criteria

| Name | Type | Description | | --- | --- | --- | |target*required|number| | |timeframeFrom*required|string|The start of the timeframe. Supports relative time expressions (e.g. now-7d) and ISO 8601 timestamps. | |timeframeTo|string|The end of the timeframe. Supports relative time expressions (e.g. now-7d) and ISO 8601 timestamps. Defaults to now if omitted. | |warning|number| |

CustomSli

| Name | Type | Description | | --- | --- | --- | |filterSegments|FilterSegments|Represents a collection of filter segments. | |indicator*required|string| |

Deprecation

| Name | Type | Description | | --- | --- | --- | |deprecated*required|boolean|True if this template is deprecated and shouldn't be used for new SLOs. | |replacementTemplateId|string|If deprecated=true, this field may contain the ID of the template to use instead. |

Error

An error response as defined here.

| Name | Type | Description | | --- | --- | --- | |code*required|number| | |details|ErrorDetails|Optional details of the error | |message*required|string| |

ErrorDetails

Optional details of the error

| Name | Type | Description | | --- | --- | --- | |constraintViolations|Array<ConstraintViolation>|A list of constraint violations of input parameters (path, query, request body) | |errorRef|string|reference to the error occurrence in the internal self-monitoring, logging, etc. |

ErrorEnvelope

| Name | Type | Description | | --- | --- | --- | |error*required|Error|An error response as defined here. |

FilterSegment

A filter segment is identified by an ID.

| Name | Type | Description | | --- | --- | --- | |id*required|string|The identifier of the filter segment. | |variables|Array<FilterSegmentVariable>| |

FilterSegmentVariable

Defines a variable with a name and a list of values.

| Name | Type | Description | | --- | --- | --- | |name*required|string|The name of the variable. | |values*required|Array<string>|The list of values for this variable. |

FilterSegments

Represents a collection of filter segments.

type: Array<FilterSegment>

Metadata

| Name | Type | Description | | --- | --- | --- | |evaluatedSliQuery*required|string|The resolved DQL query that was actually executed for this evaluation. |

MetadataResponse

| Name | Type | | --- | --- | |metadata*required|Metadata|

ObjectiveTemplate

| Name | Type | Description | | --- | --- | --- | |applicableScope*required|"SERVICE" | "HOST" | "APPLICATION" | "CLOUD_APPLICATION" | "KUBERNETES_CLUSTER" | "CLOUD_APPLICATION_NAMESPACE" | "ALL"| | |builtIn*required|boolean| | |deprecation|Deprecation| | |description|string| | |externalId|string|An optional user-provided external identifier for the objective template. Must be unique across all objective templates. | |id*required|string| | |indicator*required|string| | |name*required|string| | |tags|Array<string>|A list of tags for this objective template. Tags can be plain strings (e.g. myTag) or key-value pairs separated by a colon (e.g. Stage:DEV). To include a literal colon in a tag, escape it with a backslash (e.g. key\:value). | |variables*required|Array<TemplateVariable>| | |version|string|The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users. It's generated upon retrieval (GET requests). If set on update (PUT request) or deletion, the update/deletion will be allowed only if there wasn't any change between the retrieval and the update. |

ObjectiveTemplateConfig

| Name | Type | Description | | --- | --- | --- | |applicableScope*required|"SERVICE" | "HOST" | "APPLICATION" | "CLOUD_APPLICATION" | "KUBERNETES_CLUSTER" | "CLOUD_APPLICATION_NAMESPACE" | "ALL"| | |description|string| | |externalId|string|An optional user-provided external identifier for the objective template. Must be unique across all objective templates. | |indicator*required|string| | |name*required|string| | |tags|Array<string>|A list of tags for this objective template. Tags can be plain strings (e.g. myTag) or key-value pairs separated by a colon (e.g. Stage:DEV). To include a literal colon in a tag, escape it with a backslash (e.g. key\:value). | |variables*required|Array<TemplateVariable>| |

ObjectiveTemplateList

| Name | Type | Description | | --- | --- | --- | |items*required|Array<ObjectiveTemplate>| | |nextPageKey|string|The cursor for the next page of results. Has the value of null on the last page. Use it in the page-key query parameter to obtain subsequent pages of the result. | |totalCount*required|number|The total number of entries in the result. |

SliReference

| Name | Type | Description | | --- | --- | --- | |templateId*required|string|The id of the objective template to use as the SLI definition. | |variables*required|Array<SliReferenceVariable>| |

SliReferenceVariable

| Name | Type | | --- | --- | |name*required|string| |value*required|string|

Slo

Configuration for a service-level objective. Exactly one of sliReference or customSli must be provided. Providing both or neither results in a 400 Bad Request.

| Name | Type | Description | | --- | --- | --- | |criteria*required|Array<Criteria>| | |customSli|CustomSli| | |description|string| | |externalId|string|An optional user-provided external identifier for the SLO. Must be unique across all SLOs. | |id*required|string| | |name*required|string| | |sliReference|SliReference| | |tags|Array<string>|A list of tags for this SLO. Tags can be plain strings (e.g. myTag) or key-value pairs separated by a colon (e.g. Stage:DEV). To include a literal colon in a tag, escape it with a backslash (e.g. key\:value). | |version*required|string|The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users. It's generated upon retrieval (GET requests). If set on update (PUT request) or deletion, the update/deletion will be allowed only if there wasn't any change between the retrieval and the update. |

SloConfig

Configuration for a service-level objective. Exactly one of sliReference or customSli must be provided. Providing both or neither results in a 400 Bad Request.

| Name | Type | Description | | --- | --- | --- | |criteria*required|Array<Criteria>| | |customSli|CustomSli| | |description|string| | |externalId|string|An optional user-provided external identifier for the SLO. Must be unique across all SLOs. | |name*required|string| | |sliReference|SliReference| | |tags|Array<string>|A list of tags for this SLO. Tags can be plain strings (e.g. myTag) or key-value pairs separated by a colon (e.g. Stage:DEV). To include a literal colon in a tag, escape it with a backslash (e.g. key\:value). |

SloEvaluationBaseResponse

| Name | Type | | --- | --- | |evaluationResults|Array<SloEvaluationResult>| |metadata*required|Metadata|

SloEvaluationCancelResponse

| Name | Type | | --- | --- | |definition*required|Slo| |evaluationResults|Array<SloEvaluationResult>| |metadata*required|Metadata|

SloEvaluationRequest

| Name | Type | Description | | --- | --- | --- | |customTimeframe|Timeframe| | |filterSegments|Array<FilterSegment>|Filter segments to apply during this evaluation. The effective filter for each segment is the intersection of the segment defined on the SLO and the segment provided here. If only one side defines a segment, that segment is used as-is. | |id*required|string| | |requestTimeoutMilliseconds|number|How long to wait for the evaluation result before returning in milliseconds. If the evaluation finishes within this time, the result is returned directly (200). If not, a 202 is returned with an evaluationToken that can be used to poll for the result. default: 1000|

SloEvaluationResponse

| Name | Type | Description | | --- | --- | --- | |definition*required|Slo| | |evaluationResults|Array<SloEvaluationResult>| | |evaluationToken|string|Token to pass to evaluation:poll or evaluation:cancel to retrieve or discard the evaluation result. | |metadata*required|Metadata| | |ttlSeconds|number| |

SloEvaluationResult

| Name | Type | Description | | --- | --- | --- | |criteria*required|string| | |errorBudget|number| | |message|string| | |status*required|"SUCCESS" | "WARNING" | "FAILURE" | "ERROR"|The status of an SLO evaluation. SUCCESS and WARNING indicate the SLO was evaluated successfully (target met or warning threshold breached respectively). FAILURE means the SLO target wasn't met. ERROR means the evaluation couldn't be completed due to a system or query error. | |value|number|The evaluated SLO compliance as a percentage (0–100). |

SloObjectsList

| Name | Type | Description | | --- | --- | --- | |nextPageKey|string|The cursor for the next page of results. Has the value of null on the last page. Use it in the page-key query parameter to obtain subsequent pages of the result. | |slos*required|Array<Slo>| | |totalCount*required|number|The total number of entries in the result. |

TemplateVariable

| Name | Type | Description | | --- | --- | --- | |name*required|string| | |scope*required|"CUSTOM" | "SERVICE" | "SMARTSCAPE_SERVICE" | "HOST" | "SMARTSCAPE_HOST" | "APPLICATION" | "CLOUD_APPLICATION" | "KUBERNETES_CLUSTER" | "SMARTSCAPE_K8S_CLUSTER" | "CLOUD_APPLICATION_NAMESPACE" | "SMARTSCAPE_K8S_NAMESPACE"|The scope of a template variable. Use SMARTSCAPE_* variants when referencing Smartscape objective templates. |

Timeframe

| Name | Type | Description | | --- | --- | --- | |timeframeFrom*required|string|The start of the timeframe. Supports relative time expressions (e.g. now-7d) and ISO 8601 timestamps. | |timeframeTo|string|The end of the timeframe. Supports relative time expressions (e.g. now-7d) and ISO 8601 timestamps. Defaults to now if omitted. |

Enums

~~EvaluationStatus~~

⚠️ Deprecated Use literal values.

The status of an SLO evaluation. SUCCESS and WARNING indicate the SLO was evaluated successfully (target met or warning threshold breached respectively). FAILURE means the SLO target wasn't met. ERROR means the evaluation couldn't be completed due to a system or query error.

Enum keys

Error | Failure | Success | Warning

~~TemplateScope~~

⚠️ Deprecated Use literal values.

Enum keys

All | Application | CloudApplication | CloudApplicationNamespace | Host | KubernetesCluster | Service

~~VariableScope~~

⚠️ Deprecated Use literal values.

The scope of a template variable. Use SMARTSCAPE_* variants when referencing Smartscape objective templates.

Enum keys

Application | CloudApplication | CloudApplicationNamespace | Custom | Host | KubernetesCluster | Service | SmartscapeHost | SmartscapeK8SCluster | SmartscapeK8SNamespace | SmartscapeService