Skip to main content

Bucket Management

Documentation of the Dynatrace Bucket Management API for Grail. To read about use cases and examples, see

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

bucketDefinitionsClient

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

createBucket

bucketDefinitionsClient.createBucket(config): Promise<Bucket>

Create a new bucket

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

Required scope: storage:bucket-definitions:write

Parameters

NameType
config.body*requiredNewBucket

Returns

Successfully created bucket definition

Code example
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

bucketDefinitionsClient.deleteBucket(config): Promise<Bucket>

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

NameType
config.bucketName*requiredstring

Returns

accepted delete bucket

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

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

getDefinition

bucketDefinitionsClient.getDefinition(config): Promise<Bucket>

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

NameType
config.bucketName*requiredstring

Returns

Successfully retrieved bucket definition.

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

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

getDefinitions

bucketDefinitionsClient.getDefinitions(abortSignal?): Promise<Buckets>

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

{/ no parameters /}

Returns

Successfully retrieved all bucket definitions

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

const data = await bucketDefinitionsClient.getDefinitions();

truncateBucket

bucketDefinitionsClient.truncateBucket(config): Promise<void>

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

NameType
config.bucketName*requiredstring

{/ no returns /}

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

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

updateBucket

bucketDefinitionsClient.updateBucket(config): Promise<void>

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

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

Required scope: storage:bucket-definitions:write.

Parameters

NameTypeDescription
config.body*requiredUpdateBucket
config.bucketName*requiredstring
config.optimisticLockingVersion*requirednumberDefine on which version the updated data is based on.

{/ no returns /}

Code example
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

bucketDefinitionsClient.updateBucketPartially(config): Promise<void>

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

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

Required scope: storage:bucket-definitions:write

Parameters

NameTypeDescription
config.body*requiredPartialUpdateBucket
config.bucketName*requiredstring
config.optimisticLockingVersion*requirednumberDefine on which version the updated data is based on.

{/ no returns /}

Code example
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

Bucket

NameTypeDescription
bucketName*requiredstringThe unique identifier of the bucket within the tenant.
displayNamestring

Descriptive name of the bucket. No restriction regarding unique naming or valid characters.

metricIntervalBucketMetricInterval
retentionDays*requirednumberThe retention period in days of the data in the bucket.
status*requiredBucketStatus
table*requiredstringName of the table the bucket is assigned to.
updatable*requiredbooleanA flag indicating whether a bucket can be updated or not.
version*requirednumberOptimistic 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

NameType
buckets*requiredArray<Bucket>

ErrorEnvelope

NameType
errorExceptionalReturn

ErrorInfo

NameType
messagestring

ExceptionalReturn

NameType
codenumber
errorDetailsArray<ErrorInfo>
messagestring

NewBucket

NameTypeDescription
bucketName*requiredstringThe unique identifier of the bucket within the tenant.
displayNamestring

Descriptive name of the bucket. No restriction regarding unique naming or valid characters.

metricIntervalNewBucketMetricInterval
retentionDays*requirednumberThe retention period in days of the data in the bucket.
table*requiredNewBucketTable

PartialUpdateBucket

NameTypeDescription
displayNamestring

Descriptive name of the bucket. No restriction regarding unique naming or valid characters.

retentionDaysnumberThe retention period in days of the data in the bucket.

UpdateBucket

NameTypeDescription
bucketName*requiredstringThe unique identifier of the bucket within the tenant.
displayNamestring

Descriptive name of the bucket. No restriction regarding unique naming or valid characters.

metricIntervalUpdateBucketMetricInterval
retentionDays*requirednumberThe retention period in days of the data in the bucket.
status*requiredUpdateBucketStatus
table*requiredUpdateBucketTable
version*requirednumberOptimistic 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.

Enums

BucketMetricInterval

Interval of aggregated metric data. Only applies to metric buckets.

Enum keys

Pt10S | Pt15M | Pt1H | Pt1M | Pt1S | Pt5M | Pt5S

BucketStatus

The current status of the bucket, depending on bucket lifecycle.

Enum keys

Active | Creating | Deleting | Updating

NewBucketMetricInterval

Interval of aggregated metric data. Only applies to metric buckets.

Enum keys

Pt15M | Pt1H | Pt1M | Pt5M

NewBucketTable

Name of the table the bucket is assigned to.

Enum keys

Bizevents | Events | Logs | Spans

UpdateBucketMetricInterval

Metric interval for metric buckets. Will be ignored for other buckets.

Enum keys

Pt15M | Pt1H | Pt1M | Pt5M

UpdateBucketStatus

The current status of the bucket, depending on bucket lifecycle.

Enum keys

Active | Creating | Deleting | Updating

UpdateBucketTable

Name of the table the bucket is assigned to.

Enum keys

Bizevents | Events | Logs | Spans

Still have questions?
Find answers in the Dynatrace Community