Create a custom Grail bucket in Dynatrace with the Storage Management API by setting the bucket name, table, retention, and optional display name or class.
| POST | SaaS | https://{your-environment-id}.apps.dynatrace.com/platform/storage/management/v1/bucket-definitions |
Create a new custom bucket.
Bucket creation can take up to 1 minute.
To create a new custom Grail bucket with Storage Management you need to specify the following 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, spans, security.events, user.sessions, user.events].
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.
bucketClass Optional field that can be used to specify the bucket class.
Allowed values are live and historic. If not specified, the bucket class will be set to live by default.
To execute this request, you need a platform token or OAuth access token with storage:bucket-definitions:write scope. To learn how to obtain and use it, see Tokens and authentication.
| Parameter | Type | Description | In | Required |
|---|---|---|---|---|
| body | Create | New Bucket | body | Required |
CreateBucket object| Element | Type | Description | Required |
|---|---|---|---|
| bucketClass | string | Classification of the bucket. Determines the ingest mode. Allowed values: live, historic. Defaults to live if not specified. Historic buckets are only supported for table 'logs'. The element can hold these values
| Optional |
| bucketName | string | The unique identifier of the bucket within the tenant. | Required |
| displayName | string | Descriptive name of the bucket. No restriction regarding unique naming or valid characters. | Optional |
| includedQueryLimitDays | integer | The period in days in which queries from the bucket are included in the pricing model. | Optional |
| includedQueryLimitDaysOrDefault | integer | - | Optional |
| metricInterval | string | Interval of aggregated metric data. Only applies to metric buckets. The element can hold these values
| Optional |
| retentionDays | integer | The retention period in days of the data in the bucket. | Optional |
| retentionDaysOrDefault | integer | - | Optional |
| table | string | Name of the table the bucket is assigned to. One of [logs, events, bizevents, spans, security.events, user.sessions, user.events] | Required |
This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.
{"bucketName": "custom_logs","table": "logs","displayName": "Custom logs bucket","retentionDays": 35,"includedQueryLimitDays": 0}
| Code | Type | Description |
|---|---|---|
| 201 | Bucket | Successfully created bucket definition |
| 400 | Error | bad request |
| 401 | Error | unauthorized |
| 403 | Error | missing permissions |
| 409 | Error | Bucket already exists |
Bucket object| Element | Type | Description |
|---|---|---|
| bucketClass | string | The class of the bucket. Read-only after creation. The element can hold these values
|
| bucketName | 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 | integer | Estimated uncompressed size of the bucket in bytes. |
| estimatedUncompressedBytesOnDemand | integer | Estimated uncompressed size of on-demand data in the bucket in bytes. |
| estimatedUncompressedBytesQueryIncluded | integer | Estimated uncompressed size of query-included data in the bucket in bytes. |
| includedQueryLimitDays | integer | The period in days in which queries from the bucket are included in the pricing model. |
| metricInterval | string | Interval of aggregated metric data. Only applies to metric buckets. The element can hold these values
|
| records | integer | Amount of records in the bucket. |
| retentionDays | integer | The retention period in days of the data in the bucket. |
| status | string | The current status of the bucket, depending on bucket lifecycle. The element can hold these values
|
| table | string | Name of the table the bucket is assigned to. |
| updatable | boolean | A flag indicating whether a bucket can be updated or not. |
| version | integer | 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. |
ErrorEnvelope object| Element | Type | Description |
|---|---|---|
| error | Exceptional | - |
ExceptionalReturn object| Element | Type | Description |
|---|---|---|
| code | integer | - |
| errorDetails | (Custom | - |
| message | string | - |
CustomValidationErrorInfo objectErrorInfo object| Element | Type | Description |
|---|---|---|
| message | string | - |
InvalidAuditEventsErrorInfo objectMediaTypeErrorInfo objectParameterErrorInfo objectProxyErrorInfo objectQueryFrontendRawErrorInfo objectRequestBodyErrorInfo object{"bucketName": "custom_logs","table": "logs","displayName": "Custom logs bucket","status": "creating","retentionDays": 35,"includedQueryLimitDays": 0,"version": 1,"updatable": true}
{"error": {"code": 400,"message": "Missing request header","errorDetails": [{"type": "parameter","parameterDescriptor": "Dt-Tenant","message": "is required"}]}}