Permissions in Grail

• Latest Dynatrace
• How-to guide
• 10-min read
• Updated on Sep 17, 2025

Permissions can be assigned at the bucket, table, record, and field level. Without permissions, your users can't query data from Grail.

Set up permissions

To set up the bucket and table-level permissions

Bucket permissions

All bucket permissions need to start with storage:buckets:read. Their scope can be limited by a WHERE clause that includes one of the following operators:

After the WHERE clause, you can filter your results by specifying buckets or tables:

The example below shows how to include only buckets prefixed with default_ or the common_logs bucket.

ALLOW storage:buckets:read WHERE storage:bucket-name MATCH ("default_*", "common_logs");

For more information, see IAM policy reference.

Included queries

Bucket permissions let you define user group access to

To define access, you use the storage:query-consumption condition. This condition has two possible values.

This can be combined with the storage:bucket-name condition to restrict access on a per-bucket level.

Table permissions

Besides granting access to buckets, you also need to configure table permissions.

For more information, see IAM policy reference.

Bucket level permissions

You can restrict table permissions to certain buckets using the WHERE clause. For example:

ALLOW storage:logs:read WHERE storage:bucket-name="default_logs";

Record level permissions

You can define fine-grained permissions for records that are stored in Grail. The permissions are added to the existing table permissions by adding the WHERE clause. For example:

ALLOW storage:logs:read WHERE storage:dt.security_context="TeamA";

Supported fields:

For details that are not available as a dedicated field, set the dt.security_context field either at the data source or in the processing pipeline.

Combining bucket and record level permissions

You can combine both bucket and record level in your table permissions. For example this statement will provide access to all logs in the unrestricted_logs bucket and only specific records in the default_logs bucket:

ALLOW storage:logs:read WHERE storage:bucket-name="unrestricted_logs";
ALLOW storage:logs:read WHERE storage:bucket-name="default_logs" AND storage:dt.security_context="TeamA";

Support for multiple values with MATCH operator

For efficiency reasons, record filters using the =, IN or STARTSWITH operators apply to fields holding a single string. You might have cases where the fields you want to use for filtering contain multiple values, in conjunction with a "for any value" set semantic. Such case is possible with the MATCH operator.

For example, the following statement will return results for records with dt.security_context holding either a crn-70400- prefixed string, or an array with a crn-70400- prefixed string as one of its elements.

// will match both "crn-70400-alpha" and ["crn-70131", "crn-70400-beta", "crn-70500"]
ALLOW storage:logs:read WHERE storage:dt.security_context MATCH ("crn-70400-*");

Note that you must use the MATCH operator to get "for any value" set semantic. Using =, STARTSWITH or IN when the field holds an array will always return false. If you expect your record filters might contain an array, use the MATCH operator in your IAM statements.

ALLOW storage:buckets:read WHERE … // Ensure that the user has access to all relevant buckets
ALLOW storage:logs:read WHERE storage:k8s.namespace.name="namespace1";
ALLOW storage:logs:read WHERE storage:dt.host_group.id MATCH ("shared_host_*");

ALLOW storage:buckets:read WHERE … // Ensure that the user has access to all relevant buckets
ALLOW storage:bizevents:read WHERE storage:event.kind="Opportunity Field History";

ALLOW storage:buckets:read WHERE storage:bucket-name="dt_system_events"
ALLOW storage:system:read WHERE storage:event.kind="BILLING_EVENT"

Record permission limits

The following configuration limitations apply to record permissions:

Permissions for entities

Permissions for entities allow you to define IAM policies that control data access on entities.

In contrast to monitoring data, entity permissions only allow filtering for the dt.security_context field.

For more information, see Grant access to entities with security context.

Field permissions

You can use field permissions to hide fields that might contain sensitive data. For this purpose, we provide fieldsets. A field is considered sensitive when it's part of a fieldset. Once a field is part of a fieldset, only users with the right permissions can use it in DQL queries for filtering and grouping. For other users, it won't show up in the query results.

You require permission to access fieldsets in order to use sensitive fields. For example, if you want to use builtin-sensitive-spans fields in DQL queries, you need the following permission:

ALLOW storage:fieldsets:read WHERE storage:fieldset-name="builtin-sensitive-spans"

The two predefined fieldsets are:

Define custom fieldsets via API

You can manage your custom fieldsets via REST API

Example

This call creates the fieldset sensitive-fields-retail, removing the credit_card and DOB fields from DQL query results in the logs_retail bucket.

Request URL

POST https://myapps.mydomain.com/platform/storage/fieldsets/v1/fieldsets

Request body

{
  "name": "sensitive-fields-retail",
  "description": "Sensitive fields retail",
  "enabled": true,
  "scope": "BUCKET",
  "fields": [
    "credit_card",
    "DOB"
  ],
  "buckets": [
    "logs_retail"
  ]
}

To unmask the credit_card and DOB fields, you need the following permission:

ALLOW storage:fieldsets:read WHERE storage:fieldset-name="sensitive-fields-retail"

File permissions

Preview

To manage your lookup data stored in Grail, you require the following permissions:

All of these permissions support the storage:file-path condition using one of the following operators:

The following example shows how to provide full access to lookup data stored in /lookups/.

ALLOW storage:files:read WHERE storage:file-path startsWith "/lookups/";
ALLOW storage:files:write WHERE storage:file-path startsWith "/lookups/";
ALLOW storage:files:delete WHERE storage:file-path startsWith "/lookups/";

You can use the folder-like structure to manage access to different subsets of your lookup files with permissions, as in the following example.

ALLOW storage:files:read WHERE storage:file-path startsWith "/lookups/public/";

To give read-only access to a specific file, you could also use a permission similar to the following.

ALLOW storage:files:read WHERE storage:file-path startsWith "/lookups/http_status_codes";

For more information, see IAM policy reference.

Predefined global policies

There are several predefined global policies, each set per table (logs, events, bizevents, security events, metrics, entities, spans), and three additional, general policies:

Access to all logs

This policy provides access to all logs from Grail, and narrows the bucket permission with a WHERE condition that limits the results to the log table.

ALLOW storage:buckets:read WHERE storage:table-name= "logs";
ALLOW storage:logs:read;

Read all data

This permission statement gives you access to all tables and all buckets, therefore it needs to be used only in justified cases.

ALLOW storage:buckets:read;
ALLOW storage:system:read,
      storage:events:read,
      storage:security.events:read,
      storage:logs:read,
      storage:metrics:read,
      storage:entities:read,
      storage:bizevents:read,
      storage:spans:read;

Read all default monitoring data

This policy retrieves all default monitoring data.

In the first line, this policy statement gives access to all default buckets. The WHERE condition narrows the search to buckets whose name starts with default. Subsequently, the next lines list all the needed table permissions.

ALLOW storage:buckets:read WHERE storage:bucket-name MATCH ("default_*");
ALLOW storage:events:read,
      storage:logs:read,
      storage:metrics:read,
      storage:entities:read,
      storage:bizevents:read,
      storage:spans:read;

Read all system data

This permission statement first narrows the results to system buckets, whose name starts with dt. Then, it gives you access to all tables that contain system data, for example audit events, billing events, and query execution events. It can be useful for system admins.

ALLOW storage:buckets:read WHERE storage:bucket-name MATCH ("dt_*");
ALLOW storage:system:read;

Best practices