Cloud Functions for Firebase
Learn how to set up Sentry in your Cloud Functions for Firebase project and capture your first errors.
Cloud Functions for Firebase let you automatically run backend code in response to events triggered by Firebase features and HTTPS requests. Sentry's Node SDK works out of the box with Cloud Functions for Firebase.
The Sentry SDK includes a built-in Firebase integration that automatically instruments:
- Cloud Functions - HTTP functions, background functions, and event triggers
- Firestore - Database operations like reads, writes, and queries are instrumented out of the box
This integration is enabled by default, so you get automatic performance monitoring and error tracking without any additional configuration.
You need:
- A Sentry account and project
- Your application up and running
- Node version
18.0.0or above (>=19.9.0or18.19.0recommended)
Choose the features you want to configure, and this guide will show you how:
Run the command for your preferred package manager to add the Sentry SDK to your Firebase Functions project:
npm install @sentry/node --save
Create an initialization file (for example, instrument.js) that imports and initializes Sentry. This file must be imported at the very top of your functions entry point, before any other imports.
instrument.jsconst Sentry = require("@sentry/node");
Sentry.init({
dsn: "___PUBLIC_DSN___",
// Adds request headers and IP for users, for more info visit:
// https://docs.sentry.io/platforms/javascript/guides/firebase/configuration/options/#sendDefaultPii
sendDefaultPii: true,
// ___PRODUCT_OPTION_START___ performance
// Add Tracing by setting tracesSampleRate
// Set tracesSampleRate to 1.0 to capture 100% of transactions
// We recommend adjusting this value in production
// Learn more at
// https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
tracesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ performance
// ___PRODUCT_OPTION_START___ profiling
// Set profilesSampleRate to 1.0 to profile 100% of sampled transactions.
// This is relative to tracesSampleRate
profilesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ profiling
// ___PRODUCT_OPTION_START___ logs
// Enable logs to be sent to Sentry
enableLogs: true,
// ___PRODUCT_OPTION_END___ logs
});
Import the initialization file at the very top of your functions entry point (for example, index.js), before any other imports:
index.jsrequire("./instrument"); // Require Sentry initialization first
const { onRequest } = require("firebase-functions/https");
const { onDocumentCreated } = require("firebase-functions/firestore");
const admin = require("firebase-admin");
admin.initializeApp();
// HTTP function - automatically instrumented
exports.helloWorld = onRequest(async (request, response) => {
response.send("Hello from Firebase!");
});
// Firestore trigger - automatically instrumented
exports.onUserCreated = onDocumentCreated(
"users/{userId}",
async (event) => {
const userId = event.params.userId;
// Your logic here
},
);
The key is to import the initialization file before any other require calls, including Firebase imports. This ensures Sentry can properly instrument all modules.
The stack traces in your Sentry errors probably won't look like your actual code without unminifying them. To fix this, upload your source maps to Sentry. The easiest way to do this is by using the Sentry Wizard:
npx @sentry/wizard@latest -i sourcemaps
Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.
Add a test function that throws an error to verify Sentry is capturing errors:
index.jsrequire("./instrument"); // Import Sentry initialization first
const { onRequest } = require("firebase-functions/https");
exports.testSentry = onRequest(async (request, response) => {
throw new Error("Sentry Test Error - This is intentional!");
});
Deploy your functions and trigger the test endpoint:
firebase deploy --only functions
curl https://<region>-<project-id>.cloudfunctions.net/testSentry
Firebase Functions are automatically instrumented for tracing. You can also create custom spans:
index.jsrequire("./instrument");
const Sentry = require("@sentry/node");
const { onRequest } = require("firebase-functions/https");
exports.tracedFunction = onRequest(async (request, response) => {
await Sentry.startSpan(
{ op: "task", name: "My Custom Task" },
async () => {
// Simulate some work
await new Promise((resolve) => setTimeout(resolve, 100));
},
);
response.send("Done!");
});
Now, head over to your project on Sentry.io to view the collected data (it takes a couple of moments for the data to appear).
At this point, you should have integrated Sentry into your Cloud Functions for Firebase project.
Now's a good time to customize your setup and look into more advanced topics:
- Explore practical guides on what to monitor, log, track, and investigate after setup
- Continue to customize your configuration
- Learn how to manually capture errors
- Get familiar with Sentry's product features like tracing, insights, and alerts
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").