Skip to main content

    Grail - Storage Management

    Overview Dynatrace Bucket Management API for Grail

    This API allows you to manage storage for Grail. Data is organizied in buckets. To get familiar with the data model within Grail check the Grail data model documentation.

    Access Management

    Entpoint permissions

    There are 4 permissions that are enabling the management of the Grail bucket storage. More about Grail storage permissions can be read in the documentation.

    • storage:bucket-definitions:read

    • storage:bucket-definitions:write

    • storage:bucket-definitions:delete

    • storage:bucket-definitions:truncate

    Storage Object Modification

    Optimistic Locking Version

    Operations which modify buckets use mandatory optimistic locking. When such operations are executed, the user must provide the version upon which they operate. The version can be found in the JSON within the response of GET bucket definitions or GET bucket definition.

    If the document version in the service doesn't match, because the document has been modified in the meantime, then the operation gets rejected.

    Storage Object creation

    Creating a custom storage bucket can have benefits in terms of data management. Read more about custom buckets.

    Bucket creation can take up to 1 minute.

    To create a new custom Grail bucket with Storage Management you need to specify:

    • A unique bucket name
      • It has to be between 3-100 characters long and start with a letter.
      • The bucket name can only contain
        • lowercase alphanumeric characters [ a - z ]
        • underscores [ _ ] and
        • hyphens [ - ].
    • Bucket name can not start with
      • default_
      • dt_.

    The bucket name can't be edited or changed at a later time.

    • Display name. You can use this field to describe your bucket.

    • Retention period in days between 1 day - 3657 days (10 years).

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

    Bucket creation can take up to 1 minute.

    Required permission: storage:bucket-definitions:write

    To create a new custom Grail bucket with Storage Management you need to specify the following values:

    Allowed JSON values

    • bucketName defines the name of the bucket. The bucket name can't be edited or changed at a later time.

      • must be unique

      • has to be between 3-100 characters long and has to start with a letter

      • can only contain

        • lowercase alphanumeric characters [ a - z ]

        • underscores [ _ ] and

        • hyphens [ - ].

      • must not start with

        • default_

        • dt_

    • table name of the table this bucket is assigned to. Currently allowed one of [logs, events, bizevents].

    • retentionDays describes the data retention period in days between 1 day - 3657 days (10 years + 1 week).

    • displayName Optional field that can be used to describe the bucket. Length of the field is limited to 200 characters.

    Parameters

    NameType
    config.body*requiredCreateBucket

    Returns

    Return typeStatus codeDescription
    Bucket201Successfully created bucket definition

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorbad 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

    ATTENTION - This operation is irreversible

    Delete can be used to delete a bucket. This operation will remove the content of a given bucket and then delete the bucket itself.

    Delete is an asynchronous task. Runtime will depend on the amount of data that has to be removed.

    The status of this operation can be tracked via the status field within the [GET bucket definitions] (#operations-Bucket_Definitions-getDefinitions) or GET bucket definition. Status will show deleting as long as data will be drained and finally the bucket will be deleted. Afterwards the bucket will cease to exist.

    Operation can be executed on all types of buckets except buckets where bucketName starts with dt_ or default_.

    Required permission: storage:bucket-definitions:delete

    Parameters

    NameTypeDescription
    config.bucketName*requiredstringBucket name to delete.

    Returns

    Return typeStatus codeDescription
    Bucket202accepted delete bucket

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorbad 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 a bucket definition by name.

    Newly created buckets aren't shown immediately, this can take up to one minute.

    Required permission: storage:bucket-definitions:read

    Parameters

    NameTypeDescription
    config.addFieldsArray<"estimatedUncompressedBytes" | "records">

    add-fields: 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.

    Note: Hold down STRG on Windows/Linux or Command on Mac to select multiple values in the box below.

    config.bucketName*requiredstringBucket name to get definition for.

    Returns

    Return typeStatus codeDescription
    Bucket200Successfully retrieved bucket definition.

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorbad 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 aren't shown immediately, this can take up to one minute.

    Required permission: storage:bucket-definitions:read

    Parameters

    NameTypeDescription
    config.addFieldsArray<"estimatedUncompressedBytes" | "records">

    add-fields: 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.

    Note: Hold down STRG on Windows/Linux or Command on Mac to select multiple values in the box below.

    Returns

    Return typeStatus codeDescription
    Buckets200Successfully retrieved all bucket definitions

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorbad 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

    ATTENTION - This operation is irreversibly

    Truncate can be used to empty a bucket. This operation will remove the content of a given bucket.

    Truncate is an asyncronous task. Runtime will depend on the amount of data that has to be removed.

    Operation can be executed on all types of buckets.

    Required permission: storage:bucket-definitions:truncate

    Parameters

    NameTypeDescription
    config.bucketName*requiredstringBucket name to truncate.

    Returns

    Return typeStatus codeDescription
    void202Accepted truncate bucket

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorbad 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 definition.

    The following fields can be changed:

    • displayName can be used to describe your bucket (up to 200 characters)
    • retentionDays defines how long the data in the bucket will be retained

    Warning: changing the 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 permission: storage:bucket-definitions:write

    Parameters

    NameTypeDescription
    config.body*requiredUpdateBucket
    config.bucketName*requiredstringBucket name to update
    config.optimisticLockingVersion*requirednumber

    optimistic-locking-version defines the base version that this update applies to. You can get the current version of a bucket definition by checking the version field in the JSON response of GET bucket definitions or GET bucket definition.

    ATTENTION: this optimistic-locking-version and the version value in the JSON body must match.

    Returns

    Return typeStatus codeDescription
    void200Successfully updated bucket definition
    void202Accepted update bucket definition

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorbad 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 definition.

    There are to fields that can be changed

    • displayName can be used to describe your bucket (up to 200 characters)
    • retentionDays defines the period in days

    Warning: changing the 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 permission: storage:bucket-definitions:write

    Parameters

    NameTypeDescription
    config.body*requiredPartialUpdateBucket
    config.bucketName*requiredstringBucket name to update.
    config.optimisticLockingVersion*requirednumber

    optimistic-locking-version defines the base version that this update applies to. You can get the current version of a bucket definition by checking the version field in the JSON response of GET bucket definitions or GET bucket definition.

    Returns

    Return typeStatus codeDescription
    void200Successfully updated bucket definition
    void202Accepted update bucket definition

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorbad 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

    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.

    estimatedUncompressedBytesnumberEstimated uncompressed size of the bucket in bytes.
    includedQueryLimitDays*requirednumberThe 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.
    recordsnumberAmount of records in the bucket.
    retentionDays*requirednumberThe 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*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>

    CreateBucket

    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.

    includedQueryLimitDays*requirednumberThe 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*requirednumberThe retention period in days of the data in the bucket.
    table*requiredstring

    Name of the table the bucket is assigned to. One of [logs, events, bizevents, spans, security.events]

    CustomValidationErrorInfo

    NameType
    messagestring

    ErrorEnvelope

    NameType
    errorExceptionalReturn

    ErrorInfo

    NameType
    messagestring

    ExceptionalReturn

    NameType
    codenumber
    errorDetailsArray<CustomValidationErrorInfo | InvalidAuditEventsErrorInfo | MediaTypeErrorInfo | ParameterErrorInfo | ProxyErrorInfo | QueryFrontendRawErrorInfo | RequestBodyErrorInfo>
    messagestring

    InvalidAuditEventsErrorInfo

    NameType
    invalidAuditEventIndicesArray<number>
    invalidEventIndicesArray<number>
    messagestring

    MediaTypeErrorInfo

    NameType
    messagestring
    supportedMediaTypesArray<string>

    ParameterErrorInfo

    NameType
    messagestring
    parameterDescriptorstring

    PartialUpdateBucket

    NameTypeDescription
    displayNamestring

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

    includedQueryLimitDaysnumberThe period in days in which queries from the bucket are included in the pricing model.
    retentionDaysnumberThe 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

    NameType
    messagestring

    QueryFrontendRawErrorInfo

    NameType
    messagestring
    rawQueryFrontendResponsestring

    RequestBodyErrorInfo

    NameType
    bodyDescriptorstring
    messagestring

    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.

    includedQueryLimitDays*requirednumberThe 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*requirednumberThe 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*requiredstringName of the table the bucket is assigned to.
    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

    CreateBucketMetricInterval

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

    Enum keys

    Pt15M | Pt1H | Pt1M | Pt5M

    GetDefinitionQueryAddFieldsItem

    Enum keys

    EstimatedUncompressedBytes | Records

    GetDefinitionsQueryAddFieldsItem

    Enum keys

    EstimatedUncompressedBytes | Records

    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

    Still have questions?
    Find answers in the Dynatrace Community