CreateDashboard - Amazon CloudTrail
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

CreateDashboard

Creates a custom dashboard or the Highlights dashboard.

  • Custom dashboards - Custom dashboards allow you to query events in any event data store type. You can add up to 10 widgets to a custom dashboard. You can manually refresh a custom dashboard, or you can set a refresh schedule.

  • Highlights dashboard - You can create the Highlights dashboard to see a summary of key user activities and API usage across all your event data stores. CloudTrail Lake manages the Highlights dashboard and refreshes the dashboard every 6 hours. To create the Highlights dashboard, you must set and enable a refresh schedule.

CloudTrail runs queries to populate the dashboard's widgets during a manual or scheduled refresh. CloudTrail must be granted permissions to run the StartQuery operation on your behalf. To provide permissions, run the PutResourcePolicy operation to attach a resource-based policy to each event data store. For more information, see Example: Allow CloudTrail to run queries to populate a dashboard in the Amazon CloudTrail User Guide.

To set a refresh schedule, CloudTrail must be granted permissions to run the StartDashboardRefresh operation to refresh the dashboard on your behalf. To provide permissions, run the PutResourcePolicy operation to attach a resource-based policy to the dashboard. For more information, see Resource-based policy example for a dashboard in the Amazon CloudTrail User Guide.

For more information about dashboards, see CloudTrail Lake dashboards in the Amazon CloudTrail User Guide.

Request Syntax

{ "Name": "string", "RefreshSchedule": { "Frequency": { "Unit": "string", "Value": number }, "Status": "string", "TimeOfDay": "string" }, "TagsList": [ { "Key": "string", "Value": "string" } ], "TerminationProtectionEnabled": boolean, "Widgets": [ { "QueryParameters": [ "string" ], "QueryStatement": "string", "ViewProperties": { "string" : "string" } } ] }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

Name

The name of the dashboard. The name must be unique to your account.

To create the Highlights dashboard, the name must be AWSCloudTrail-Highlights.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 128.

Pattern: ^[a-zA-Z0-9_\-]+$

Required: Yes

RefreshSchedule

The refresh schedule configuration for the dashboard.

To create the Highlights dashboard, you must set a refresh schedule and set the Status to ENABLED. The Unit for the refresh schedule must be HOURS and the Value must be 6.

Type: RefreshSchedule object

Required: No

TagsList

A list of tags.

Type: Array of Tag objects

Array Members: Maximum number of 200 items.

Required: No

TerminationProtectionEnabled

Specifies whether termination protection is enabled for the dashboard. If termination protection is enabled, you cannot delete the dashboard until termination protection is disabled.

Type: Boolean

Required: No

Widgets

An array of widgets for a custom dashboard. A custom dashboard can have a maximum of ten widgets.

You do not need to specify widgets for the Highlights dashboard.

Type: Array of RequestWidget objects

Required: No

Response Syntax

{ "DashboardArn": "string", "Name": "string", "RefreshSchedule": { "Frequency": { "Unit": "string", "Value": number }, "Status": "string", "TimeOfDay": "string" }, "TagsList": [ { "Key": "string", "Value": "string" } ], "TerminationProtectionEnabled": boolean, "Type": "string", "Widgets": [ { "QueryAlias": "string", "QueryParameters": [ "string" ], "QueryStatement": "string", "ViewProperties": { "string" : "string" } } ] }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

DashboardArn

The ARN for the dashboard.

Type: String

Pattern: ^[a-zA-Z0-9._/\-:]+$

Name

The name of the dashboard.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 128.

Pattern: ^[a-zA-Z0-9_\-]+$

RefreshSchedule

The refresh schedule for the dashboard, if configured.

Type: RefreshSchedule object

TagsList

A list of tags.

Type: Array of Tag objects

Array Members: Maximum number of 200 items.

TerminationProtectionEnabled

Indicates whether termination protection is enabled for the dashboard.

Type: Boolean

Type

The dashboard type.

Type: String

Valid Values: MANAGED | CUSTOM

Widgets

An array of widgets for the dashboard.

Type: Array of Widget objects

Errors

For information about the errors that are common to all actions, see Common Errors.

ConflictException

This exception is thrown when the specified resource is not ready for an operation. This can occur when you try to run an operation on a resource before CloudTrail has time to fully load the resource, or because another operation is modifying the resource. If this exception occurs, wait a few minutes, and then try the operation again.

HTTP Status Code: 400

EventDataStoreNotFoundException

The specified event data store was not found.

HTTP Status Code: 400

InactiveEventDataStoreException

The event data store is inactive.

HTTP Status Code: 400

InsufficientEncryptionPolicyException

For the CreateTrail PutInsightSelectors, UpdateTrail, StartQuery, and StartImport operations, this exception is thrown when the policy on the S3 bucket or Amazon KMS key does not have sufficient permissions for the operation.

For all other operations, this exception is thrown when the policy for the Amazon KMS key does not have sufficient permissions for the operation.

HTTP Status Code: 400

InvalidQueryStatementException

The query that was submitted has validation errors, or uses incorrect syntax or unsupported keywords. For more information about writing a query, see Create or edit a query in the Amazon CloudTrail User Guide.

HTTP Status Code: 400

InvalidTagParameterException

This exception is thrown when the specified tag key or values are not valid. It can also occur if there are duplicate tags or too many tags on the resource.

HTTP Status Code: 400

ServiceQuotaExceededException

This exception is thrown when the quota is exceeded. For information about CloudTrail quotas, see Service quotas in the Amazon General Reference.

HTTP Status Code: 400

UnsupportedOperationException

This exception is thrown when the requested operation is not supported.

HTTP Status Code: 400

Examples

Example

The following example creates a custom dashboard named AccountActivityDashboard with four widgets and a refresh schedule of every 12 hours. This example enables termination protection to prevent the dashboard from being accidentally deleted.

{ "Name": "AccountActivityDashboard", "RefreshSchedule": { "Frequency": { "Unit": "HOURS", "Value": 12 }, "Status": "ENABLED", "TimeOfDay": "00:00" }, "TerminationProtectionEnabled": true, "Widgets": [ { "ViewProperties": { "Height": "2", "Width": "4", "Title": "TopErrors", "View": "Table" }, "QueryStatement": "SELECT errorCode, COUNT(*) AS eventCount FROM eds WHERE eventTime > '?' AND eventTime < '?' AND (errorCode is not null) GROUP BY errorCode ORDER BY eventCount DESC LIMIT 100", "QueryParameters": ["$StartTime$", "$EndTime$"] }, { "ViewProperties": { "Height": "2", "Width": "4", "Title": "MostActiveRegions", "View": "PieChart", "LabelColumn": "awsRegion", "ValueColumn": "eventCount", "FilterColumn": "awsRegion" }, "QueryStatement": "SELECT awsRegion, COUNT(*) AS eventCount FROM eds where eventTime > '?' and eventTime < '?' GROUP BY awsRegion ORDER BY eventCount LIMIT 100", "QueryParameters": ["$StartTime$", "$EndTime$"] }, { "ViewProperties": { "Height": "2", "Width": "4", "Title": "AccountActivity", "View": "LineChart", "YAxisColumn": "eventCount", "XAxisColumn": "eventDate", "FilterColumn": "readOnly" }, "QueryStatement": "SELECT DATE_TRUNC('?', eventTime) AS eventDate, IF(readOnly, 'read', 'write') AS readOnly, COUNT(*) as eventCount FROM eds WHERE eventTime > '?' AND eventTime < '?' GROUP BY DATE_TRUNC('?', eventTime), readOnly ORDER BY DATE_TRUNC('?', eventTime), readOnly", "QueryParameters": ["$Period$", "$StartTime$", "$EndTime$", "$Period$", "$Period$"] }, { "ViewProperties": { "Height": "2", "Width": "4", "Title": "TopServices", "View": "BarChart", "LabelColumn": "service", "ValueColumn": "eventCount", "FilterColumn": "service", "Orientation": "Horizontal" }, "QueryStatement": "SELECT REPLACE(eventSource, '.amazonaws.com') AS service, COUNT(*) AS eventCount FROM eds WHERE eventTime > '?' AND eventTime < '?' GROUP BY eventSource ORDER BY eventCount DESC LIMIT 100", "QueryParameters": ["$StartTime$", "$EndTime$"] } ] }

Example

The following example creates the Highlights dashboard. The Highlights dashboard requires that you set and enable a refresh schedule for every 6 hours.

{ "Name": "AWSCloudTrail-Highlights", "RefreshSchedule": { "Frequency": { "Unit": "HOURS", "Value": 6 }, "Status": "ENABLED" }, "TerminationProtectionEnabled": true }

See Also

For more information about using this API in one of the language-specific Amazon SDKs, see the following: