> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/azfar-imtiaz/PayPulse-Cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# CloudWatch monitoring

> Log groups and monitoring configuration for PayPulse Cloud Lambda functions.

PayPulse Cloud uses Amazon CloudWatch for centralized logging across all Lambda functions and the API Gateway. Log groups are defined in `aws-infra-terraform/cloudwatch.tf`, with additional logging configuration in `api_gateway.tf`.

## Lambda log groups

Four log groups are explicitly managed in Terraform with a 90-day retention policy:

```hcl theme={null}
resource "aws_cloudwatch_log_group" "fetch_invoices" {
  name              = "/aws/lambda/fetch_invoices"
  retention_in_days = 90
}

resource "aws_cloudwatch_log_group" "fetch_latest_invoice" {
  name              = "/aws/lambda/fetch_latest_invoice"
  retention_in_days = 90
}

resource "aws_cloudwatch_log_group" "parse_invoice" {
  name              = "/aws/lambda/parse_invoice"
  retention_in_days = 90
}

resource "aws_cloudwatch_log_group" "send_invoice_notification" {
  name              = "/aws/lambda/send_invoice_notification"
  retention_in_days = 90
}
```

The remaining Lambda functions create their log groups automatically when first invoked. The full set of active log groups is:

| Log group                               | Function                    | Trigger                          |
| --------------------------------------- | --------------------------- | -------------------------------- |
| `/aws/lambda/login_user`                | `login_user`                | API Gateway                      |
| `/aws/lambda/signup_user`               | `signup_user`               | API Gateway                      |
| `/aws/lambda/fetch_invoices`            | `fetch_invoices`            | API Gateway                      |
| `/aws/lambda/fetch_latest_invoice`      | `fetch_latest_invoice`      | EventBridge (weekdays 08:30 UTC) |
| `/aws/lambda/fetch_retail_invoices`     | `fetch_retail_invoices`     | API Gateway                      |
| `/aws/lambda/parse_invoice`             | `parse_invoice`             | S3 event (PDF upload)            |
| `/aws/lambda/get_rental_invoice`        | `get_rental_invoice`        | API Gateway                      |
| `/aws/lambda/get_rental_invoices`       | `get_rental_invoices`       | API Gateway                      |
| `/aws/lambda/get_user_profile`          | `get_user_profile`          | API Gateway                      |
| `/aws/lambda/gmail_store_tokens`        | `gmail_store_tokens`        | API Gateway                      |
| `/aws/lambda/delete_user`               | `delete_user`               | API Gateway                      |
| `/aws/lambda/send_invoice_notification` | `send_invoice_notification` | DynamoDB stream                  |

## API Gateway log group

The API Gateway has its own log group for access logging:

```
/aws/apigateway/PayPulseAPI
```

Retention is set to **30 days** for the API Gateway log group.

### Access log format

API Gateway is configured with detailed structured access logging. Each request produces a JSON log entry containing:

| Field                     | Description                                       |
| ------------------------- | ------------------------------------------------- |
| `requestId`               | Unique identifier for the request                 |
| `sourceIp`                | Client IP address                                 |
| `requestTime`             | Timestamp of the request                          |
| `httpMethod`              | HTTP verb (GET, POST, DELETE, etc.)               |
| `path`                    | Request path                                      |
| `status`                  | HTTP response status code                         |
| `protocol`                | HTTP protocol version                             |
| `responseLength`          | Response body size in bytes                       |
| `integrationErrorMessage` | Error message from the Lambda integration, if any |

This format makes it straightforward to query access logs in CloudWatch Insights by status code, path, or error message.

## Throttling settings

API Gateway throttling limits are configured to protect backend Lambda functions from traffic spikes:

| Setting     | Value                 |
| ----------- | --------------------- |
| Burst limit | 5,000 requests        |
| Rate limit  | 1,000 requests/second |

Requests that exceed the rate limit receive a `429 Too Many Requests` response.

## Querying logs with CloudWatch Insights

You can query any Lambda log group using CloudWatch Insights. Example query to find errors across all Lambda functions:

```sql theme={null}
fields @timestamp, @message
| filter @message like /ERROR/
| sort @timestamp desc
| limit 50
```

To filter by a specific function, select the corresponding log group (e.g., `/aws/lambda/parse_invoice`) before running the query.

<Tip>
  For the invoice processing pipeline (`fetch_latest_invoice` → `parse_invoice` → `send_invoice_notification`), correlate log entries across all three log groups using the `requestId` present in each function's log output.
</Tip>