Service-Level objectives

• Reference

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

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

v1.0.0

Latest (V1)

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

objectiveTemplatesClient

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

getObjectiveTemplateById

objectiveTemplatesClient.getObjectiveTemplateById(config): Promise<ObjectiveTemplate>

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.

Code example

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

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

getObjectiveTemplates

objectiveTemplatesClient.getObjectiveTemplates(config): Promise<ObjectiveTemplateList>

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.

Code example

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

serviceLevelObjectivesClient.createSlo(config): Promise<Slo>

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.

Code example

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

serviceLevelObjectivesClient.deleteSlo(config): Promise<void>

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.

Code example

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

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

getSloById

serviceLevelObjectivesClient.getSloById(config): Promise<Slo>

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.

Code example

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

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

getSlos

serviceLevelObjectivesClient.getSlos(config): Promise<SloObjectsList>

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.

Code example

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

const data = await serviceLevelObjectivesClient.getSlos();

updateSlo

serviceLevelObjectivesClient.updateSlo(config): Promise<void>

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.

Code example

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

serviceLevelObjectivesEvaluationClient.cancelSloEvaluation(config): Promise<void | SloEvaluationCancelResponse>

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.

Code example

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

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

pollSloEvaluation

serviceLevelObjectivesEvaluationClient.pollSloEvaluation(config): Promise<SloEvaluationResponse>

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.

Code example

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

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

startSloEvaluation

serviceLevelObjectivesEvaluationClient.startSloEvaluation(config): Promise<SloEvaluationResponse>

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.

Code example

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