Logging Monitoring Failures in Adonisjs with Firestore

AdonisJS, a Node.js web framework, relies on structured logging and clear error handling to expose issues during request processing. When integrating with Google Cloud Firestore, logging and monitoring failures typically arise from unhandled promise rejections, missing error classification, and the loss of contextual information across asynchronous boundaries. These gaps make it difficult to detect authentication problems, permission misconfigurations, or data access anomalies specific to Firestore operations.

In this combination, failures can remain invisible if AdonisJS exception handlers do not explicitly capture Firestore-specific errors such as permission-denied (e.g., permission-denied errors from Firestore security rules), network timeouts, or document not found scenarios. Without explicit logging of request identifiers, user context, and Firestore document paths, correlation across services breaks down, increasing mean time to resolution. For example, a missing index or an incorrect document path may surface as a generic error, masking underlying configuration or design issues.

The risk is compounded when Firestore calls are executed in background jobs or within middleware, where stack traces are not automatically surfaced. Sensitive operational details, such as rate-limit triggers or unexpected document mutations, may go unrecorded if the logging layer does not explicitly hook into Firestore client events. This creates blind spots for security monitoring, where subtle anomalies like unusual read patterns or repeated access denials are not captured in application logs or monitoring dashboards.

Furthermore, inconsistent log formats across AdonisJS providers and Firestore callbacks reduce the effectiveness of log aggregation tools. Without structured metadata—including HTTP method, route pattern, Firestore collection and document ID, and authenticated user ID—incident responders cannot efficiently trace the root cause. These logging monitoring failures in AdonisJS with Firestore expose operational and security gaps that require targeted instrumentation and error classification to close.

To address logging and monitoring gaps, implement structured error handling and explicit logging around all Firestore interactions in AdonisJS. Use provider-specific exception filters and centralized logging to ensure Firestore errors are captured with sufficient context for detection and remediation.

Structured error handling and logging

Create an exception filter for Firestore errors to standardize responses and ensure critical details are logged. In app/Exceptions/Filter/FirestoreExceptionFilter.ts:

import { ExceptionFilterContract } from '@ioc:Adonis/Core/ExceptionHandler'
import { HttpContextContract } from '@ioc:Adonis/Core/HttpContext'
import { Firestore, FirebaseError } from '@google-cloud/firestore'

export default class FirestoreExceptionFilter implements ExceptionFilterContract {
  public async handle(error: FirestoreError, context: HttpContextContract) {
    const logger = context.logger
    const requestId = context.request.id()
    const user = context.auth.getUser()

    // Log structured details for monitoring
    logger.error('Firestore operation failed', {
      requestId,
      userId: user ? user.id : null,
      path: error.path,
      code: error.code,
      customMessage: error.message,
      method: context.request.method(),
      url: context.request.url().toString(),
    })

    // Map Firestore errors to appropriate HTTP responses
    if (error.code === 'permission-denied') {
      context.response.status(403).send({ error: 'Access denied', code: 'PERMISSION_DENIED' })
      return
    }
    if (error.code === 'not-found') {
      context.response.status(404).send({ error: 'Resource not found', code: 'NOT_FOUND' })
      return
    }

    context.response.status(500).send({ error: 'Internal server error', code: 'INTERNAL' })
  }
}

Instrumented Firestore client usage in a controller

In your controller, wrap Firestore operations with explicit try/catch blocks and include contextual metadata in logs. For example, in app/Controllers/Http/DocumentController.ts:

import { schema } from '@ioc:Adonis/Core/Validator'
import { HttpContextContract } from '@ioc:Adonis/Core/HttpContext'
import { Firestore, DocumentReference } from '@google-cloud/firestore'

export default class DocumentsController {
  private firestore = new Firestore()

  public async show({ params, request, logger, response }: HttpContextContract) {
    const documentId = params.id
    const collectionName = 'records'
    logger.info('Fetching document', {
      collection: collectionName,
      documentId,
      method: request.method(),
      user: request.auth?.user?.id,
    })

    try {
      const docRef: DocumentReference = this.firestore.collection(collectionName).doc(documentId)
      const doc = await docRef.get()

      if (!doc.exists) {
        logger.warn('Document does not exist', {
          collection: collectionName,
          documentId,
        })
        return response.status(404).send({ error: 'Document not found' })
      }

      logger.info('Document retrieved successfully', {
        collection: collectionName,
        documentId,
        hasPendingWrites: doc.metadata.hasPendingWrites,
      })
      return response.send(doc.data())
    } catch (error) {
      logger.error('Firestore get failed in show', {
        collection: collectionName,
        documentId,
        error: error instanceof Error ? error.message : String(error),
      })
      return response.status(500).send({ error: 'Failed to retrieve document' })
    }
  }
}

Centralized provider registration

Register the exception filter in start/hooks.ts so that Firestore errors are consistently handled across routes:

import { ExceptionProvider } from '@ioc:Adonis/Core/ExceptionProvider'
import FirestoreExceptionFilter from 'App/Exceptions/Filter/FirestoreExceptionFilter'

export default class AppExceptionProvider extends ExceptionProvider {
  protected get filters() {
    return {
      FirestoreExceptionFilter,
    }
  }

  protected get mapping() {
    return {
      'FirebaseError': 'App/Exceptions/Filter/FirestoreExceptionFilter',
    }
  }
}

Monitoring and alerting integration

Use AdonisJS’s logger integrations to forward structured Firestore errors to monitoring platforms. Ensure logs include severity, request context, and Firestore metadata to enable alerting on patterns such as repeated permission-denied events or document-read failures.