Merge pull request #723 from NHSDigital/feature/made14-NRL-1146-reporting

[NRL-1146] Add report to count pointers for a custodian

Author: mattdean3-nhs

README.md

@@ -511,3 +511,26 @@ Once you have a new release version ready, you can deploy it through our environ
 2. If any issues arise in the deployment, fix the issues, create a new release version and start this process again.
 3. Once the deployments are complete, use the "Persistent Environment Deploy" Github Action workflow to deploy the release version to `ref`.
 4. Once that is complete, use the "Persistent Environment Deploy" workflow to deploy the release version to `prod`.
+
+## Reports
+
+Reports are provided as scripts in the `reports/` directory. To run a report:
+
+1. Login to your AWS account on the command line, choosing the account that contains the resources you want to report on.
+2. Run your chosen report script, giving the script the resource names and parameters it requires. See each report script for details.
+
+For example, to count the number of pointers from X26 in the pointers table in the dev environment:
+
+```
+$ poetry run python ./scripts/count_pointers_for_custodian.py \
+   nhsd-nrlf--dev-pointers-table \
+   X26
+```
+
+### Running reports in the prod environment
+
+The reports scripts may require resources that could affect the performance of the live production system. Because of this, it is recommended that you take steps to minimise this impact before running reports.
+
+If you are running a report against the DynamoDB pointers table in prod, you should create a copy (or restore a PITR backup) of the table and run your report against the copy.
+
+Please ensure any duplicated resource/data is deleted from the prod environment once you have finished using it.

reports/count_pointers_for_custodian.py

@@ -0,0 +1,59 @@
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional
+
+import boto3
+import fire
+
+dynamodb = boto3.client("dynamodb")
+paginator = dynamodb.get_paginator("scan")
+
+
+def _count_pointers(
+    table_name: str, ods_code: str, created_date: Optional[str] = None
+) -> dict[str, float]:
+    """
+    Count the number of pointers for a given custodian (ODS code) in the pointers table.
+    Parameters:
+    - table_name: The name of the pointers table to use.
+    - ods_code: The custodian ODS code to find pointers for.
+    - created_date: The created date to filter pointers on. (optional)
+    """
+
+    print(f"Counting pointers for {ods_code} in table {table_name}....")  # noqa
+
+    params: dict[str, Any] = {
+        "TableName": table_name,
+        "FilterExpression": "custodian = :ods_code",
+        "ExpressionAttributeValues": {":ods_code": {"S": ods_code}},
+        "Select": "COUNT",
+        "PaginationConfig": {"PageSize": 100},
+    }
+
+    if created_date:
+        params["FilterExpression"] += " AND starts_with(created_on, :created_date)"
+        params["ExpressionAttributeValues"][":created_date"] = {"S": created_date}
+
+    custodian_pointers_count = 0
+    total_scanned_count = 0
+
+    start_time = datetime.now(tz=timezone.utc)
+
+    for page in paginator.paginate(**params):
+        custodian_pointers_count += page["Count"]
+        total_scanned_count += page["ScannedCount"]
+
+        if total_scanned_count % 1000 == 0:
+            print(".", end="", flush=True)  # noqa
+
+    end_time = datetime.now(tz=timezone.utc)
+
+    print(" Done")  # noqa
+    return {
+        "items_found": custodian_pointers_count,
+        "scanned_count": total_scanned_count,
+        "took-secs": timedelta.total_seconds(end_time - start_time),
+    }
+
+
+if __name__ == "__main__":
+    fire.Fire(_count_pointers)