Customize crash reports for Web

Select platform:

iOS+ Android Web Flutter Unity

In the Firebase console (DevOps & Engagement > Crashlytics dashboard), you can click into an issue and get a detailed event report. You can customize those reports and manage your telemetry collection to help you better understand what is happening in your web app:

Report handled exceptions programmatically
Add custom keys
Force flush telemetry records for short-lived routines
Configure sampling rate
Disable or enable telemetry collection

Report handled exceptions programmatically

You can record handled exceptions manually using recordError. Routing errors and uncaught exceptions are captured automatically by your framework error boundaries.

Here's how to track the failure prevalence and diagnostic attributes across your users:

import { recordError, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase';

const crashlytics = getCrashlytics(app);

async function submitPaymentForm() {
  try {
    await api.processTransaction();
  } catch (error) {
    // Manually record handled exceptions with diagnostic context
    recordError(crashlytics, error, {
      userTier: 'Premium Gold',
      checkoutStage: 'BillingAddressVerification',
      transactionCode: 'tx_8412_err',
      retryAttempts: 2
    });
    showFallbackBanner(error);
  }
}

Add custom keys

Custom metadata keys help you understand the specific app state or user workflow leading up to a crash.

You can log user activities, session states, and diagnostic details directly as key-value custom attributes using the optional metadata parameter when calling recordError:

import { recordError, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

const crashlytics = getCrashlytics(app);

// Pass custom key-value diagnostic metadata within recordError
recordError(crashlytics, error, {
  userTier: 'Premium Gold',
  checkoutStage: 'BillingAddressVerification',
  transactionCode: 'tx_8412_err',
  retryAttempts: 2,
  breadcrumb: 'User opened shopping cart',
  lastAction: 'Click Checkout Button'
});

These custom attributes are kept in the exception report and appear under the Keys tab in the Crashlytics dashboard issue view.

Force flush telemetry records

By default, the web telemetry engine batches logs into memory segments to preserve battery life, CPU performance, and network bandwidth. However, for short-lived execution environments, logs must be uploaded immediately before the execution context is destroyed.

You can use the asynchronous flush command to send all queued errors to the backend immediately:

import { recordError, flush, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase';

const crashlytics = getCrashlytics(app);

async function handleApplicationCrash(error: Error) {
  // Capture the error with immediate priority
  recordError(crashlytics, error, { priority: 'IMMEDIATE' });

  // Force an immediate upload before the process terminates or reloads
  await flush(crashlytics);

  // Safe to terminate or refresh the current execution context
  window.location.reload();
}

Configure sampling rate

If you sample a proportion of your user sessions to control telemetry volume and cost, you can configure sampling using any of the following options:

Option 1 (recommended): Configure sampling rate in the Firebase console
Option 2: Set sampling rate using the Firebase Telemetry Admin API

Option 1 (recommended): Configure sampling rate in the Firebase console

In the Firebase console, go to the DevOps & Engagement > Crashlytics dashboard.
Select your web app from the drop-down selector at the top of the page.
Click Configure sampling in the top-right corner of the dashboard.
Set the Sampling rate percentage (between 0% and 100%) to control the percentage of events and sessions collected from clients.

Option 2: Set sampling rate using the Firebase Telemetry Admin API

You can use the Firebase Telemetry Admin API (firebasetelemetryadmin.googleapis.com/v1alpha) to manage telemetry collection settings for your Firebase apps.

Configure the following required variables in your terminal:

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"  # for example, global
APP_ID="FIREBASE_APP_ID"  # for example, 1:1234567890:web:abcdef123456
TOKEN=$(gcloud auth application-default print-access-token)

Find your CONFIG_NAME and then configure it as a variable in your terminal:

Telemetry settings are managed using a Config resource, so you need to find the specific CONFIG_NAME for your web app.
1. List the configs in your project and filter by your FIREBASE_APP_ID. The curl -G and --data-urlencode flags ensure the AIP-160 filter string is correctly URL-encoded:
```
curl -G \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "filter=app_id=\"${APP_ID}\"" \
  "https://firebasetelemetryadmin.googleapis.com/v1alpha/projects/${PROJECT_ID}/locations/${LOCATION}/configs"
```
2. In the JSON response, locate the name field for your app (projects/PROJECT_ID/locations/LOCATION/configs/<CONFIG_ID>), and then set it as your CONFIG_NAME variable:
```
CONFIG_NAME="CONFIG_NAME"
```

Set the sampling rate:

To adjust the sampling rate, use the PATCH method to update the sampling_rate field. You must specify updateMask=sampling_rate in the query parameters. The sampling rate is a double value representing the percentage of sessions to collect (for example, 0.25 for 25%):

# Example: Set sampling rate to 25%
curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"sampling_rate\": 0.25,
    \"app_id\": \"${APP_ID}\"
  }" \
  "https://firebasetelemetryadmin.googleapis.com/v1alpha/${CONFIG_NAME}?updateMask=sampling_rate"

Disable or enable telemetry collection

By default, telemetry collection is enabled when you set up Crashlytics for your web app. If you need to disable or re-enable telemetry collection dynamically after installing the Crashlytics SDK, you can manage collection endpoints using the Firebase Telemetry Admin API (firebasetelemetryadmin.googleapis.com/v1alpha).

Before you can disable or enable telemetry, you need to set the following variables: