Bucket Management

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

@dynatrace-sdk/client-bucket-management

v2.1.0

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

Name	Type
config.body*required	NewBucket

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

Name	Type
config.bucketName*required	string

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

Name	Type
config.bucketName*required	string

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

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

Name	Type
config.bucketName*required	string

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

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.

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

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.

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

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	BucketMetricInterval
retentionDays*required	number	The retention period in days of the data in the bucket.
status*required	BucketStatus
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>

ErrorEnvelope

Name	Type
error	ExceptionalReturn

ErrorInfo

Name	Type
message	string

ExceptionalReturn

Name	Type
code	number
errorDetails	Array<ErrorInfo>
message	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
retentionDays*required	number	The retention period in days of the data in the bucket.
table*required	NewBucketTable

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.

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
retentionDays*required	number	The retention period in days of the data in the bucket.
status*required	UpdateBucketStatus
table*required	UpdateBucketTable
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.

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