Check out what’s new from Firebase at Google I/O 2022. Learn more

Monitor Cloud Firestore activity

This page describes how you can monitor your Cloud Firestore usage and spot potential problems in your app. Looking at your app's usage can also give you an idea of what to expect on your bill. Additionally, if something seems off, getting a clear picture of your database's operations can be a helpful troubleshooting tool.

Usage dashboard

The Google Cloud Platform Console and the Firebase console include a Cloud Firestore usage dashboard that shows document reads, writes, and deletes over time.

GCP Console

Go to the Cloud Firestore usage page (GCP Console)

The Cloud Firestore usage dashboard in the GCP Console.

Access control

The usage dashboard requires the monitoring.timeSeries.list Cloud IAM permission. The Project Owner, Editor, and Viewer roles grant this permission. You can also grant this permission through a Cloud Monitoring role or a custom role.

Firebase console

Go to the Cloud Firestore usage page (Firebase console)

The Cloud Firestore usage dashboard in the Firebase console.

Usage dashboard and billing reports

The Cloud Firestore usage dashboards in the Firebase and Cloud consoles provide an estimate of usage. They can help you identify spikes in usage. However, the dashboard is not an exact view of billed operations. Billed usage is likely higher. In all cases of discrepancy, the billing report takes precedence over the usage dashboard.

Operations that cause discrepancies between the usage dashboard and billed usage include:

  • Import and export operations. Reads and writes performed by these operations do not show up in the usage dashboard.
  • No-op writes. Operations that do not result in a change to the database, such as an update that does not change field values or a write to a deleted document, contribute to billed operations. However, the usage dashboard does not count these operations.
  • Collapsed writes. In cases with multiple writes to the same document in quick succession, the usage dashboard might collapse multiple writes together and count them as one. When billing usage, each write is still counted separately.

    The usage dashboard also collapses writes for field transforms like server timestamps, numeric increments, and array union operations. For field transforms, the usage dashboard might count multiple operations as a single operation.

  • Queries that return zero results. Queries with zero results incur a cost of one read operation. This usage is billed but does not appear in the usage dashboard.

Security rule usage

Additionally, the Firebase console provides a Security Rules evaluation dashboard, a useful, at-a-glance view of rules invocations. You can supplement this dashboard with detailed analysis in Cloud Monitoring.

Go to the Rules page

Cloud Firestore Rules
monitoring dashboard in the Firebase console.

Daily quotas

When you create a Firebase project, you're also creating a project in the Google Cloud. The App Engine Quotas page in the GCP Console tracks daily Cloud Firestore usage information including reads, writes, index writes, deletes, stored data, and network egress.

Go to the Quotas page

Cloud Firestore usage in the App Engine Quotas page.

Cloud Monitoring

Cloud Monitoring collects metrics, events, and metadata from Google Cloud products. The usage dashboard in the Cloud Firestore console reports the same metrics data. To set up custom dashboards and usage alerts, use Cloud Monitoring.

Cloud Monitoring includes the following Cloud Firestore metrics:

Metric Name Description
Document Reads

The number of successful document reads. You can break this metric down by the type of read: LOOKUP or QUERY.

This metric does not include reads from managed export operations.

Document Writes

The number of successful document writes. You can break the metric down by the type of write: CREATE or UPDATE.

This metric does not include writes from managed import operations.

Document Deletes The number of successful document deletes.
Active Connections

The number of active connections to your database.

Each active mobile and web SDK maintains a single connection, which can be shared across multiple snapshot listeners. The server client libraries create one connection per snapshot listener.

Snapshot Listeners

The number of snapshot listeners across all active connections.

Rule evaluations

The number of Cloud Firestore Rules evaluations performed in response to write or read requests. You can break this metric down by the result of the request (ALLOW, DENY, or ERROR).

Realtime updates usage

Use the active connections and snapshot listeners metrics to measure your usage of realtime updates.

Let's say a user opens your app on their phone. The app then connects to Cloud Firestore and subscribes to 10 queries. This increases your metrics by 1 active connection and 10 snapshot listeners.

Sampling rate

The Cloud Firestore metrics are sampled every minute, but updates may take up to 4 minutes to show up in your dashboards.

Using these metrics, you can set up a Cloud Firestore dashboard like the following:

Cloud Firestore usage in a Cloud Monitoring dashboard.

Complete the steps below to start monitoring Cloud Firestore with Cloud Monitoring.

Create a Cloud Monitoring workspace

To monitor Cloud Firestore with Cloud Monitoring, you must set up a workspace for your project. A workspace organizes monitoring information from one or more projects. After setting up a workspace, you can create custom dashboards and alerting policies.

  1. Open the Cloud Monitoring Page

    If your project is already part of a workspace, the Cloud Monitoring Page opens. Otherwise, select a workspace for your project.

  2. Select the New Workspace option or select an existing workspace.

  3. Click Add. After your workspace builds, the Cloud Monitoring Page opens.

Create a dashboard and add a chart

Display the Cloud Firestore metrics collected from Cloud Monitoring in your own charts and dashboards.

Before you proceed, make sure your project is part of a Cloud Monitoring workspace.

  1. In the Cloud Monitoring Page, open your workspace and go to the Dashboards page.

    Go to the Dashboards page

  2. Click Create Dashboard and enter a dashboard name.

  3. In the upper-right hand corner, click Add Chart.

  4. In the Add Chart window, enter a chart title. Click the Metric tab.

  5. In the Find resource type and metric field, enter Cloud Firestore. From the auto-populated dropdown, select one of the Cloud Firestore metrics..

  6. To add more metrics to the same chart, click Add Metric and repeat the previous step.

  7. Optionally, tailor your chart as needed. For example, in the Filter field, click + Add a filter. Scroll down, then select a value or range for the metric of interest you wish to filter the chart on.

  8. Click Save.

For more on Cloud Monitoring charts, see Working with charts.

Create an alerting policy

You can create an alerting policy based on the Cloud Firestore metrics. Follow the steps below can create an alerting policy that emails you whenever a specific Cloud Firestore metric meets a certain threshold.

Before you proceed, make sure your project is part of a Cloud Monitoring workspace.

  1. In the Cloud Monitoring Page, open your workspace, and go to the Alerting page.

    Go to the Create New Alerting Policy page

  2. Click Create Policy.

  3. Enter a name for your alerting policy.

  4. Add an alerting condition based on one of the Cloud Firestore metrics. Click Add Condition.

  5. Select a Target. In the Find resource type and metric field, enter Cloud Firestore. From the auto-populated dropdown, select one of the Cloud Firestore metrics.

  6. Under Policy triggers, use the dropdown fields to define your alerting condition.

  7. Add a notification channel to your alerting policy. Under Notifications, Click Add Notification Channel. Select Email from the dropdown menu.

  8. Enter your email in the Email address field. Click Add.

  9. Optionally, fill out the documentation field to include additional information in your email notification.

  10. Click Save.

If your Cloud Firestore usage exceeds the configured threshold, you will receive an email alert: An example Cloud Firestore alert email.

For more on alerting policies, see Introduction to alerting.

What's next