docs: update README with audit config health checks and rationale

Author: Adilson Somensari

README.md

@@ -5,9 +5,10 @@ A New Relic Terraform utility with two modes:
 - **import mode** (default) — scan accounts via NerdGraph and generate
   [Terraform import blocks](https://developer.hashicorp.com/terraform/language/import)
   ready for `terraform plan -generate-config-out=resources.tf`.
-- **audit mode** — scan accounts for hardcoded entity IDs and GUIDs that will
-  break after an account migration, and print an annotated report with migration
-  suggestions.
+- **audit mode** — scan accounts for two categories of problems: hardcoded entity
+  IDs and GUIDs that will break after an account migration, and alert configuration
+  issues (disabled conditions, empty policies, policies with no notification, legacy
+  metric conditions) that indicate silent or ineffective monitoring.
 
 ---
 
@@ -27,20 +28,34 @@ No Terraform state is created or modified until you explicitly run `terraform ap
 
 ### Audit mode
 
-New Relic generates a unique `entityGuid` for every monitored entity (APM services,
-infrastructure hosts, dashboards, alerts, etc.). Dashboards and alert conditions often
-reference entities by these GUIDs or by numeric IDs such as `appId` or `hostId`. These
-IDs are **account-specific** — they change when resources are migrated to a new account,
-breaking any assets that reference them.
+Audit mode produces two categories of findings.
+
+**Hardcoded ID references** — New Relic generates a unique `entityGuid` for every
+monitored entity (APM services, infrastructure hosts, dashboards, alerts, etc.).
+Dashboards and alert conditions often reference entities by these GUIDs or by numeric
+IDs such as `appId` or `hostId`. These IDs are **account-specific** — they change when
+resources are migrated to a new account, silently breaking any asset that references them.
+
+**Alert configuration health** — Beyond migration risk, audit mode also flags structural
+problems in your alert setup that cause monitoring to be ineffective regardless of
+migration:
+
+- Conditions that are disabled and therefore never fire.
+- Policies with no conditions, which can never generate an alert.
+- Policies whose conditions are active but have no notification workflow routing their
+  alerts — violations open and close silently with nobody notified.
+- Legacy APM/Browser/Mobile metric conditions that predate NRQL alerting and should
+  be recreated as NRQL conditions for long-term support and flexibility.
 
 Audit mode:
 
-1. Fetches all dashboards, NRQL alert conditions, workloads, service levels, and
-   workflows for each account.
-2. Scans their NRQL queries, widget configurations, entity lists, and filter expressions
-   for hardcoded `entityGuid`, `appId`, `hostId`, `entityId`, and `monitorId` references.
-3. Resolves each found ID to an entity name via NerdGraph.
-4. Prints a grouped report with a migration suggestion per finding.
+1. Fetches dashboards, NRQL alert conditions, workloads, service levels, workflows,
+   alert policies, and legacy metric conditions for each account.
+2. Scans NRQL queries, widget configurations, entity lists, and filter expressions
+   for hardcoded ID references, and checks alert policies and conditions for
+   configuration problems.
+3. Resolves each found entity ID to a name via NerdGraph.
+4. Prints a grouped report and optionally writes a CSV file (`--csv`).
 
 ---
 
@@ -120,14 +135,20 @@ terraform apply
 
 # --- Audit mode ---
 
-# Audit all accessible accounts for hardcoded entity IDs
+# Full audit: hardcoded ID refs + alert config health
 nr-tf-util --mode audit
 
-# Audit a single account
-nr-tf-util --mode audit --account-id 2883194
+# Audit a single account and export findings to CSV
+nr-tf-util --mode audit --account-id 2883194 --csv findings.csv
 
-# Audit only dashboards and NRQL conditions
-nr-tf-util --mode audit --skip workloads --skip service_levels --skip workflows
+# Skip legacy-condition and uncovered-policy checks
+nr-tf-util --mode audit --skip legacy_conditions --skip uncovered_alert_policies
+
+# ID-reference checks only (skip all config health checks)
+nr-tf-util --mode audit \
+  --skip disabled_conditions \
+  --skip legacy_conditions \
+  --skip uncovered_alert_policies
 ```
 
 ---
@@ -156,6 +177,12 @@ nr-tf-util --mode audit --skip workloads --skip service_levels --skip workflows
 | `--out` | `./output` | Root directory for output. One subdirectory is created per account. |
 | `--dry-run` | `false` | Print what would be written without writing any files. |
 
+### Audit mode flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--csv` | — | Write findings to a CSV file (e.g. `--csv findings.csv`). |
+
 ---
 
 ## Regions
@@ -201,6 +228,8 @@ Only files with at least one resource are written.
 
 ### Asset types scanned
 
+#### Hardcoded ID reference checks
+
 | Asset type | `--skip` value | What is scanned |
 |---|---|---|
 | Dashboards | `dashboards` | NRQL queries in every widget (`rawConfiguration`) |
@@ -209,6 +238,20 @@ Only files with at least one resource are written.
 | Service levels | `service_levels` | Monitored entity GUID + events WHERE clauses |
 | Workflows | `workflows` | Issue filter predicate values |
 
+#### Alert configuration health checks
+
+| Check | `--skip` value | What is flagged | Rationale |
+|---|---|---|---|
+| Disabled NRQL conditions | `disabled_conditions` | Conditions with `enabled=false` | A disabled condition never fires. It should be re-enabled if monitoring is still needed, or removed to keep the policy readable. |
+| Legacy metric conditions | `legacy_conditions` | APM/Browser/Mobile metric conditions (non-NRQL) | These predate NRQL alerting and are no longer the recommended format. NRQL conditions offer finer control, support streaming alerts, and will receive future New Relic improvements; legacy conditions will not. |
+| Policies with no conditions | `uncovered_alert_policies` | Alert policies that have zero conditions | An empty policy can never generate an alert. It is dead configuration that clutters the policy list and may give a false sense of coverage. |
+| Policies with no notification | `uncovered_alert_policies` | Policies with at least one enabled condition but no aiWorkflow routing their alerts | When a condition fires, New Relic creates a violation and opens an issue — but if no workflow routes that issue to a destination, nobody is notified. This is one of the most common causes of silent alerting failures. |
+
+> **Note on notification detection:** The tool checks for aiWorkflows that explicitly
+> target a policy via `labels.policyIds` predicates, or for a catch-all workflow
+> (`VIEW_ALL` filter type). Workflows that match by policy *name* or other attributes
+> are not detected as coverage — review those policies manually.
+
 ### Hardcoded ID patterns detected
 
 | ID type | Example | Why it breaks |
@@ -233,11 +276,24 @@ The audit report includes a per-finding suggestion:
 | `monitorId` | yes | `Monitor ID changes on migration; after re-import reference '<name>' by name` |
 | any | no | Entity could not be resolved — may have been deleted or is in another account |
 
+### CSV export
+
+Pass `--csv <file>` to write all findings to a CSV file alongside the text report.
+The CSV has 12 columns:
+
+```
+account_id, account_name, asset_type, asset_id, asset_name,
+location, id_type, id_value, resolved, entity_name, entity_type, suggestion
+```
+
+Configuration health findings (disabled conditions, empty policies, etc.) appear as
+rows with blank `id_type`, `id_value`, `entity_name`, and `entity_type` columns.
+
 ### Sample audit output
 
 ```
 ══════════════════════════════════════════════════════════════
-Account: Production (2883194)   findings: 5   assets affected: 3
+Account: Production (2883194)   findings: 7   assets affected: 5
 ──────────────────────────────────────────────────────────────
 
   DASHBOARD  "APM Overview"  (id: MTIzNDU2N3xWS...)
@@ -249,21 +305,28 @@ Account: Production (2883194)   findings: 5   assets affected: 3
        entityGuid MTIzNDU2N3x... → Checkout Service (APPLICATION)
        suggestion: GUID is account-specific; after migration find 'Checkout Service' by name to get the new GUID
 
-  NRQL_CONDITION  "High Error Rate — Checkout"  (id: 2883194:444555)
-  └─ condition query
-       appId 99887766 → Checkout Service (APPLICATION)
-       suggestion: Replace with: appName = 'Checkout Service'
+  NRQL_CONDITION  "Latency P99 — Deprecated"  (id: 2883194:555)
+  └─ condition configuration
+       Condition is disabled — enable it or remove it to reduce policy noise
+
+  ALERT_CONDITION  "Response Time"  (id: 2883194:10)
+  └─ policy: APM Alerts
+       Legacy APM_APP_METRIC condition — recreate as a NRQL alert condition for long-term support
+
+  ALERT_POLICY  "Infra Monitoring"  (id: 77701)
+  └─ policy conditions
+       Policy has no conditions — it will never generate alerts
 
-  WORKLOAD  "Payments Team"  (id: 9988776)
-  └─ static entity list
-       entityGuid MTIzOTky... → payments-db (HOST)
-       suggestion: GUID is account-specific; after migration find 'payments-db' by name to get the new GUID
+  ALERT_POLICY  "Checkout Alerts"  (id: 77702)
+  └─ policy notification
+       Policy has active conditions but no workflow is routing its alerts — they will fire silently
 
 ══════════════════════════════════════════════════════════════
 Overall summary
-  Accounts  : 1
-  Findings  : 5 total  (5 resolved, 0 unresolved)
-  Assets    : 3 affected
+  Accounts           : 1
+  Hardcoded ID refs  : 2 total  (2 resolved, 0 unresolved)
+  Config issues      : 5
+  Assets affected    : 5
 ```
 
 ---