Grail - Storage 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

@dynatrace-sdk/client-bucket-management

v3.2.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	CreateBucket

Returns

Return type	Status code	Description
Bucket	201	Successfully created bucket definition

Throws

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

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,
    includedQueryLimitDays: 0,
  },
});

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

Return type	Status code	Description
Bucket	202	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.

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

Return type	Status code	Description
Bucket	200	Successfully retrieved bucket definition.

Throws

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

Code example

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

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

getDefinitions

bucketDefinitionsClient.getDefinitions(config): 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

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

Return type	Status code	Description
Buckets	200	Successfully retrieved all bucket definitions

Throws

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

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

Returns

Return type	Status code	Description
void	202	Accepted truncate bucket

Throws

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

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 (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.

Returns

Return type	Status code	Description
void	200	Successfully updated bucket definition
void	202	Accepted update bucket definition

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)

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,
    includedQueryLimitDays: 0,
    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 (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.

Returns

Return type	Status code	Description
void	200	Successfully updated bucket definition
void	202	Accepted update bucket definition

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)

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,
      includedQueryLimitDays: 0,
    },
  });

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.
estimatedUncompressedBytes	number	Estimated uncompressed size of the bucket in bytes.
includedQueryLimitDays*required	number	The period in days in which queries from the bucket are included in the pricing model.
metricInterval	"PT1S" | "PT5S" | "PT10S" | "PT1M" | "PT5M" | "PT15M" | "PT1H"	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	"creating" | "active" | "updating" | "deleting"	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>

CreateBucket

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.
includedQueryLimitDays*required	number	The period in days in which queries from the bucket are included in the pricing model.
metricInterval	"PT1M" | "PT5M" | "PT15M" | "PT1H"	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, spans, security.events]

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>

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.
includedQueryLimitDays	number	The period in days in which queries from the bucket are included in the pricing model.
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.
includedQueryLimitDays*required	number	The period in days in which queries from the bucket are included in the pricing model.
metricInterval	"PT1M" | "PT5M" | "PT15M" | "PT1H"	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	"creating" | "active" | "updating" | "deleting"	The current status of the bucket, depending on bucket lifecycle.
table*required	string	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.

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

CreateBucketMetricInterval

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

Enum keys

Pt15M | Pt1H | Pt1M | Pt5M

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