Use CloudKit Console to monitor and optimize database activity

Hello, I'm Christopher Ward, and I'm an engineer on the iCloud developer experience team.

The CloudKit Console's Database application is a tool enabling you to inspect data and manage your database schema in your CloudKit Containers. I'm pleased to share new and improved features so you stay up to date with important changes to your CloudKit containers, as well as powerful debugging tools, to understand how your app is using CloudKit.

I'll demonstrate how Developer Notifications let you know about changes happening in your CloudKit containers.

You will learn how configuring notification settings keep notifications tailored to your team's usage of CloudKit.

Then I'll explain how powerful features within the CloudKit Console's Telemetry tools, let you understand your app's usage of CloudKit.

I'll set out how CloudKit Console Logs further allow you to explore how your app interacts with your CloudKit containers, in a privacy preserving way.

Lastly, I'll demonstrate how to create custom alerts based on your app's telemetry data.

You will have the power to be notified when criteria that you specify are detected in your CloudKit containers.

Notifications make it clear when key events happen in your CloudKit containers. They are sent with important contextual information.

This makes it easier than ever for you to recognise and resolve issues with your app.

I'm working on an app with members of my team. Our app uses CloudKit to sync data to iCloud. We use the CloudKit Console to manage our schema and work with data stored in CloudKit.

I'll show you notifications in the CloudKit Console. The notification bell, located in the top header, is home to CloudKit Developer Notifications.

When I click the bell, I am presented with a list of notifications I have been sent. They come in automatically and are the fastest way to receive updates on the status and activity in CloudKit containers. CloudKit Developer Notifications are available for a range of events. They keep you up to date with database alerts, schema changes, promotions, resets, and authorization token status. Clicking on a notification takes you to the relevant section of the Console, where the necessary context is provided.

Clicking on a schema change notification, takes you to the Schema History page. This new page in the Console details your team's changes to your container's schema over time. We also give you the ability to tailor which notifications you receive, and how you are notified.

I will demonstrate how notifications settings are configured in the Console. I open the user menu and click on Settings.

When I click on the notifications section, I'm presented with the list of configuration options for notifications. When a notification is checked on for the web category, notifications are automatically displayed within the CloudKit Console. I'm enabling email notifications for Service Updates and Database Alerts, by clicking on the checkboxes next to each heading, as these are alerts I want to know about when I'm away from the Console. This way, I'm confident I can take action as soon as I need to. It is important to keep my notifications limited to containers relevant to the apps I'm working on.

Notifications can be enabled or disabled for individual containers. When I toggle on manage containers, and explicitly select which containers I want to be notified about, in this case my example container, I will only receive notifications for containers selected in the list and not ones I used when testing a previous app. Telemetry in the CloudKit Console visualises your app's interactions with your CloudKit containers.

You will use Telemetry to understand current CloudKit activity, and observe trends across metrics including requests, errors, latency and bandwidth.

I'm going back to the CloudKit Console, the notification bell has an updated badge, alerting me I have received a new notification.

I click on the bell to open the notifications panel.

The notification in the list, informs me that a database alert has been triggered for my container.

This alert is configured to notify me when the total number of CloudKit errors for my container exceeds a threshold. Clicking on the notification takes me to the alert details page, where I start to investigate what caused the increase in errors. Navigating to this page from the notification has narrowed the timeframe to be relevant and indicated the specific point in time when the alert criteria was met.

My app runs on multiple Apple platforms. I'm clicking on the Group By selector and changing the Group By to platform. Making this change modified the graph to breakdown errors into groups based on platform. This is a quick way to identify differences in data between platforms. My app produces a lot more CloudKit traffic on iPhone and iPad, than Apple Watch, so I expect there to always be more errors for those devices. It's clear from the chart, that there is a larger number of watch errors than I would expect. So I'm changing to the Error Rate metric by clicking on the telemetry link in the side navigation and clicking on the Error Rate chart.

The Error Rate chart displays errors as a percentage of the total requests sent.

I'm changing my Group By back to platform which makes it clear that the Watch app is the source of a disproportionate number of errors. To further investigate the issue, in the query builder above the chart I'm entering a filter to restrict the data shown, to be when the platform is Watch.

Now I change the Group By to operation so I know which specific operations are affected.

Viewing the telemetry graph, it's clear which operations are triggering errors.

Narrowing down a view of telemetry data makes it easier to understand what has happened in an app and who it affects. Telemetry is not limited to Errors and Error Rate. The same filtering tools are available for you to explore your app's Requests, Bandwidth and Latency.

Telemetry queries can be shared with your team, allowing you to collaborate on analysis and solutions. Usage gives you an understanding of whether data being stored consists mostly of records or assets, how many active users you have, and which devices are being used the most. These graphs can be all be generated with custom time ranges, where you can monitor their trends over time. When issues are identified within your app, you need as much detail as possible to resolve the problem.

Individual operations your app triggers, can be explored in CloudKit Console's Database Logs.

The granularity of information available makes it easier to confirm hypothesis about issues in your app, and resolve them swiftly.

Moving back to the Console to continue my investigation.

Logs are accessed from the side navigation pane or by clicking the Query in Logs button on the Telemetry page.

I'm navigating to Logs by clicking the Query in Logs button. All of the searching and querying done on the Telemetry page has been preserved in the initial logs query. This means that the logs being displayed are already relevant to debugging and exploring CloudKit events. I'm modifying the time range by selecting the 2 day time window from the time window picker above the query bar. Narrowing the time range removes noise from the results. I'm interested in a number of different fields within each event. By clicking the table view button, the logs are displayed in a customisable table. Adding specific columns I'm interested in lets me easily compare values between events. I'm clicking on the customizable table column's control and selecting userId from the list of possible columns, so I can see which users this issue is affecting. By adding this extra column, I immediately see that a single user is triggering a large number of Quota Exceeded errors, which means I'm not handling that scenario properly in my Watch app. When I expand a log I'm interested in, I'm presented with a complete view of the data sent in a particular event. The results of Log queries can be exported in different formats. Exported logs are useful for comparing historical results, and working with Log data outside of the CloudKit Console.

I export logs by clicking the export data button and selecting to either Download CSV or Download JSON.

To test for regressions in fixed bugs, log queries can be saved. They are also shareable, by clicking the copy log link button, which enables a whole team to debug the same issue.

Creating custom alerts gives you the ability to react to important changes in your apps usage of CloudKit.

Alerts are triggered when values exceed or fall bellow specified thresholds or averages.

Further customization lets you restrict notifications based on telemetry filters and repetition criteria.

I want to make sure the error condition I identified earlier doesn't happen again. In case it does, I want to be alerted proactively.

I will create an alert so that I am notified of this condition occurring in the future.

I'm going back to the console to view the error rate chart from my previous investigation.

I click the create alert button underneath the telemetry chart. This opens the alert creation dialog, which guides me through the process of creating an alert. The alert preview chart, makes it clear when the alert I am configuring would be triggered. The highlighted area represents the alert's threshold. Any intersection with this area is when an alert would have been triggered.

The filters I entered when pinpointing my error, are automatically included to specifically target if this criteria is met again in the future. It's important to me that if this problem occurs again, I'm notified as soon as possible. I do this by clicking on the time period selector and changing the alert to be configured to monitor Error Rate per hour. By default the alerts are populated with an alert threshold based on average usage of the container. I'm modifying my threshold slightly by increasing the threshold as I only want to be alerted when there is a significant spike.

The updated preview chart helps me visualise the effects of the changes I've made to my alerts criteria. A sensible default alert name is provided based on the alert's criteria. I'm going to use the default name, but you can enter whatever makes the most sense to you.

As I click Create, the alert criteria is saved and will now be evaluated against usage of my CloudKit container. I'm taken to the the details page for my newly created alert. Any instances where the criteria is met will be displayed on the chart, as well as notifying me based on the settings I configured earlier. Alerts can be created against Requests, Errors, and Error Rate telemetry metrics.

I showed an example alert for Error Rate. Two other example alerts using different metrics could be: When your app ships on a new platform, configuring an alert for the number of errors would provide visibility into the success of your new endeavor, or help you to act fast on any mistakes. When you have perfected the syncing logic in your app, an alert can be used to detect future regressions.

For instance, an alert checking that the expected number of data synchronization operations don't exceed an average-based threshold, would let you know if any syncing bugs are introduced. Alerts are managed through the new Alerts page, available under the monitor section of the side navigation. This page summarizes all of your alerts in one place, and allows them to be enabled, disabled, or deleted.

Now you have this new set of CloudKit Console tools! Configure your notification preferences, and select notifications to also be sent by email. Explore the Telemetry graphs to visualise how your app interacts with CloudKit.

Check your app's CloudKit usage statistics to see trends in active users, devices, and storage. Save important Logs and Telemetry queries, and share them with your team. Most importantly, create custom alerts to be notified of key activity in your CloudKit containers. Cheers!