@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

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

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

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

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

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

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

| Return type | Status code | Description | |---|---|---| |Buckets|200|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|

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|

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

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

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

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

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. | |estimatedUncompressedBytes|number|Estimated uncompressed size of the bucket in bytes. | |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>|

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

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|"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|"logs" | "events" | "bizevents"|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

NewBucketMetricInterval

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

UpdateBucketTable

Name of the table the bucket is assigned to.

Enum keys

Bizevents | Events | Logs