@dynatrace-sdk/client-bucket-management NPM

@dynatrace-sdk/client-bucket-management

Here you can find the

The Dynatrace Bucket Management API for Grail. Get more information about use cases and examples from the Dynatrace Documentation

Installation

npm install @dynatrace-sdk/client-bucket-management

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.

bucketDefinitionsClient

import { bucketDefinitionsClient } from '@dynatrace-sdk/client-bucket-management';

createBucket

Create a new bucket

Create a new bucket. Bucket creation can take up to 1 minute.

Required scope: storage:bucket-definitions:write

Parameters

Name	Type
config.body*required	NewBucket

Returns

Successfully created bucket definition

Throws

Error Type	Error Message
ErrorEnvelopeError	bad request \| unauthorized \| missing permissions \| Bucket already exists

import { bucketDefinitionsClient } from "@dynatrace-sdk/client-bucket-management";

const data = await bucketDefinitionsClient.createBucket({
  body: {
    bucketName: "custom_logs",
    table: "logs",
    displayName: "Custom logs bucket",
    retentionDays: 35,
  },
});

deleteBucket

Delete a bucket

Starts deleting a bucket.

Deletes the bucket and all data stored in the bucket. This operation can not be undone.

Required scope: storage:bucket-definitions:delete

Parameters

Name	Type
config.bucketName*required	string

Returns

accepted delete bucket

Throws

Error Type	Error Message
ErrorEnvelopeError	bad request \| unauthorized \| Forbidden \| bucket not found \| another operation is still in progress that prevents deletion.

import { bucketDefinitionsClient } from "@dynatrace-sdk/client-bucket-management";

const data = await bucketDefinitionsClient.deleteBucket({
  bucketName: "...",
});

getDefinition

Get bucket definition by name

Get bucket definition by name.

Newly created buckets are not shown immediately, this can take up to a minute.

Required scope: storage:bucket-definitions:read

Parameters

Name	Type	Description
config.addFields	Array<string>	Define additional fields added to the response. Depending on the field this may result in longer response times. records: Request number of records stored in a bucket. estimatedUncompressedBytes: Request estimated uncompressed size of a bucket.
config.bucketName*required	string

Returns

Successfully retrieved bucket definition.

Throws

Error Type	Error Message
ErrorEnvelopeError	bad request \| unauthorized \| missing permissions \| Bucket with provided name was not found.

import { bucketDefinitionsClient } from "@dynatrace-sdk/client-bucket-management";

const data = await bucketDefinitionsClient.getDefinition({
  bucketName: "...",
});

getDefinitions

Get all bucket definitions

Get all bucket definitions.

Newly created buckets are not shown immediately, this can take up to a minute.

Required scope: storage:bucket-definitions:read

Parameters

Name	Type	Description
config.addFields	Array<string>	Define additional fields added to the response. Depending on the field this may result in longer response times. records: Request number of records stored in a bucket. estimatedUncompressedBytes: Request estimated uncompressed size of a bucket.

Returns

Successfully retrieved all bucket definitions

Throws

Error Type	Error Message
ErrorEnvelopeError	bad request \| unauthorized \| missing permissions

import { bucketDefinitionsClient } from "@dynatrace-sdk/client-bucket-management";

const data = await bucketDefinitionsClient.getDefinitions();

truncateBucket

Truncate a bucket

Truncate a specific bucket. Removes the content of the given bucket. Operation can be executed with all types of buckets.

Required scope: storage:bucket-definitions:truncate

Parameters

Name	Type
config.bucketName*required	string

Throws

Error Type	Error Message
ErrorEnvelopeError	bad request \| unauthorized \| Forbidden \| Bucket not found \| Server not ready

import { bucketDefinitionsClient } from "@dynatrace-sdk/client-bucket-management";

const data = await bucketDefinitionsClient.truncateBucket({
  bucketName: "...",
});

updateBucket

Update a bucket

Update a bucket. Update one of the following fields or both:

displayName: descriptive name of the bucket
retentionDays: retention period in days (important note: the new retention days will also apply to existing records. Shortening the retention period could result in data deletion!)

Define the full bucket definition with updated field(s) in the request body.

Required scope: storage:bucket-definitions:write.

Parameters

Name	Type	Description
config.body*required	UpdateBucket
config.bucketName*required	string
config.optimisticLockingVersion*required	number	Define on which version the updated data is based on.

Throws

Error Type	Error Message
ErrorEnvelopeError	bad request \| unauthorized \| Forbidden \| Bucket with provided name was not found \| Attempt to update an old version or an operation is currently in progress that prevents current modifications (creating, deleting, updating)

import { bucketDefinitionsClient } from "@dynatrace-sdk/client-bucket-management";

const data = await bucketDefinitionsClient.updateBucket({
  bucketName: "...",
  optimisticLockingVersion: 10,
  body: {
    bucketName: "custom_logs",
    table: "logs",
    displayName: "Custom logs bucket (updated)",
    status: "active",
    retentionDays: 10,
    version: 1,
  },
});

updateBucketPartially

Update a bucket partially

Update a bucket. Update one of the following fields or both:

displayName: descriptive name of the bucket
retentionDays: retention period in days (important note: the new retention days will also apply to existing records. Shortening the retention period could result in data deletion!)

Add the field(s) to be updated to the request body.

Required scope: storage:bucket-definitions:write

Parameters

Name	Type	Description
config.body*required	PartialUpdateBucket
config.bucketName*required	string
config.optimisticLockingVersion*required	number	Define on which version the updated data is based on.

Throws

Error Type	Error Message
ErrorEnvelopeError	bad request \| unauthorized \| Forbidden \| Bucket with provided name was not found \| Attempt to update an old version or an operation is currently in progress that prevents current modifications (creating, deleting, updating)

import { bucketDefinitionsClient } from "@dynatrace-sdk/client-bucket-management";

const data =
  await bucketDefinitionsClient.updateBucketPartially({
    bucketName: "...",
    optimisticLockingVersion: 10,
    body: {
      displayName: "Custom logs bucket (updated)",
      retentionDays: 10,
    },
  });

Types

ApiClientError

Base error for all client SDKs. All other errors extend this class.

Name	Type	Description
cause	any
errorType*required	ErrorType
isApiClientError*required	true
message*required	string
name*required	string
stack	string
prepareStackTrace	Object	Optional override for formatting stack traces
stackTraceLimit*required	number

ApiGatewayError

Dedicated error response class for errors thrown by API Gateway. Autogenerated SDK Clients have built-in handler for API Gateway errors that throws this error.

Name	Type	Description
body*required	ApiGatewayErrorResponseBody
cause	any
code*required	number
errorType*required	ErrorType
isApiClientError*required	true
isApiGatewayError*required	true
isClientRequestError*required	true
message*required	string
name*required	string
response*required	HttpClientResponse
retryAfterSeconds*required	undefined \| number
stack	string
prepareStackTrace	Object	Optional override for formatting stack traces
stackTraceLimit*required	number

ClientRequestError

Generic error class for service errors, used to handle both expected and unexpected service-level errors.

Name	Type	Description
body*required	DTO
cause	any
errorType*required	ErrorType
isApiClientError*required	true
isClientRequestError*required	true
message*required	string
name*required	string
response*required	HttpClientResponse
stack	string
prepareStackTrace	Object	Optional override for formatting stack traces
stackTraceLimit*required	number

ErrorEnvelopeError

Generic error class for service errors, used to handle both expected and unexpected service-level errors.

Name	Type	Description
body*required	ErrorEnvelope
cause	any
errorType*required	ErrorType
isApiClientError*required	true
isClientRequestError*required	true
isErrorEnvelopeError*required	true
message*required	string
name*required	string
response*required	HttpClientResponse
stack	string
prepareStackTrace	Object	Optional override for formatting stack traces
stackTraceLimit*required	number

InvalidResponseError

Dedicated error class for errors related to response serialization. Thrown when received service response can't be deserialized.

Name	Type	Description
cause	any
errorType*required	ErrorType
expectedType	string
isApiClientError*required	true
isInvalidResponseError*required	true
message*required	string
name*required	string
nestedError	Error
response*required	any
responseBody*required	any
stack	string
prepareStackTrace	Object	Optional override for formatting stack traces
stackTraceLimit*required	number

Bucket

Name	Type	Description
bucketName*required	string	The unique identifier of the bucket within the tenant.
displayName	string	Descriptive name of the bucket. No restriction regarding unique naming or valid characters.
estimatedUncompressedBytes	number	Estimated uncompressed size of the bucket in bytes.
metricInterval	BucketMetricInterval	Interval of aggregated metric data. Only applies to metric buckets.
records	number	Amount of records in the bucket.
retentionDays*required	number	The retention period in days of the data in the bucket.
status*required	BucketStatus	The current status of the bucket, depending on bucket lifecycle.
table*required	string	Name of the table the bucket is assigned to.
updatable*required	boolean	A flag indicating whether a bucket can be updated or not.
version*required	number	Optimistic locking version. Update requests define with this on which version the data updated is based on. This must match with the version stored, otherwise the update will fail due to concurrent modification.

Buckets

Name	Type
buckets*required	Array<Bucket>

CustomValidationErrorInfo

Name	Type
message	string

ErrorEnvelope

Name	Type
error	ExceptionalReturn

ErrorInfo

Name	Type
message	string

ExceptionalReturn

Name	Type
code	number
errorDetails	Array<CustomValidationErrorInfo \| InvalidAuditEventsErrorInfo \| MediaTypeErrorInfo \| ParameterErrorInfo \| ProxyErrorInfo \| QueryFrontendRawErrorInfo \| RequestBodyErrorInfo>
message	string

InvalidAuditEventsErrorInfo

Name	Type
invalidAuditEventIndices	Array<number>
invalidEventIndices	Array<number>
message	string

MediaTypeErrorInfo

Name	Type
message	string
supportedMediaTypes	Array<string>

NewBucket

Name	Type	Description
bucketName*required	string	The unique identifier of the bucket within the tenant.
displayName	string	Descriptive name of the bucket. No restriction regarding unique naming or valid characters.
metricInterval	NewBucketMetricInterval	Interval of aggregated metric data. Only applies to metric buckets.
retentionDays*required	number	The retention period in days of the data in the bucket.
table*required	string	Name of the table the bucket is assigned to. One of logs, events, bizevents

ParameterErrorInfo

Name	Type
message	string
parameterDescriptor	string

PartialUpdateBucket

Name	Type	Description
displayName	string	Descriptive name of the bucket. No restriction regarding unique naming or valid characters.
retentionDays	number	The retention period in days of the data in the bucket. Important note: the new retention days will also apply to existing records. Shortening the retention period could result in data deletion!

ProxyErrorInfo

Name	Type
message	string

QueryFrontendRawErrorInfo

Name	Type
message	string
rawQueryFrontendResponse	string

RequestBodyErrorInfo

Name	Type
bodyDescriptor	string
message	string

UpdateBucket

Name	Type	Description
bucketName*required	string	The unique identifier of the bucket within the tenant.
displayName	string	Descriptive name of the bucket. No restriction regarding unique naming or valid characters.
metricInterval	UpdateBucketMetricInterval	Metric interval for metric buckets. Will be ignored for other buckets.
retentionDays*required	number	The retention period in days of the data in the bucket. Important note: the new retention days will also apply to existing records. Shortening the retention period could result in data deletion!
status*required	UpdateBucketStatus	The current status of the bucket, depending on bucket lifecycle.
table*required	UpdateBucketTable	Name of the table the bucket is assigned to.
version*required	number	Optimistic locking version. Update requests define with this on which version the data updated is based on. This must match with the version stored, otherwise the update will fail due to concurrent modification.