chore: update the wording again

Author: kartikgola

receiver/postgresqlreceiver/README.md

@@ -94,9 +94,12 @@ to grant the user you are using `pg_monitor`. Take the example from `testdata/in
 GRANT pg_monitor TO otelu;
 ```
 
-Query sample events include the backend's `postgresql.state`. The `postgresql.backends` metric instead reports the
-total number of PostgreSQL backend processes associated with each database, including client connections in active,
-idle, and idle-in-transaction states, as reported by `pg_stat_activity`.
+The `postgresql.backends` metric reports the number of PostgreSQL backend processes associated with each database,
+as counted from `pg_stat_activity`. It applies no filter on connection state or backend type, so it counts active,
+idle, and idle-in-transaction client connections as well as non-client backends such as autovacuum workers and
+parallel query workers. Background processes that are not associated with a database (e.g. the background writer and
+WAL writer, which have a `NULL` `datname`) are not attributed to any database. This differs from query sample events,
+which include each backend's `postgresql.state`.
 
 The following options are available:
 - `max_rows_per_query`: (optional, default=1000) The max number of rows would return from the query 

receiver/postgresqlreceiver/client.go

@@ -341,8 +341,10 @@ func (c *postgreSQLClient) getDatabaseLocks(ctx context.Context) ([]databaseLock
 	return dl, multierr.Combine(errs...)
 }
 
-// getBackends returns the total number of PostgreSQL backend processes associated with each database,
-// including client connections in active, idle, and idle-in-transaction states.
+// getBackends returns the number of backend processes for each database, counted from pg_stat_activity
+// across all connection states (active, idle, idle-in-transaction) and all backend types, including
+// non-client backends such as autovacuum and parallel workers. Backends with no associated database
+// (NULL datname, e.g. the background writer and WAL writer) are not attributed to any database.
 func (c *postgreSQLClient) getBackends(ctx context.Context, databases []string) (map[databaseName]int64, error) {
 	query := filterQueryByDatabases("SELECT datname, count(*) as count from pg_stat_activity", databases, true)
 	rows, err := c.client.QueryContext(ctx, query)

receiver/postgresqlreceiver/documentation.md

@@ -14,7 +14,7 @@ metrics:
 
 ### postgresql.backends
 
-The total number of PostgreSQL backend processes associated with this database, including client connections in active, idle, and idle-in-transaction states, as reported by `pg_stat_activity`.
+The number of backend processes associated with each database, as reported by `pg_stat_activity`. Counts backends across all connection states (active, idle, idle-in-transaction) and all backend types, including non-client backends such as autovacuum and parallel workers.
 
 | Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
 | ---- | ----------- | ---------- | ----------------------- | --------- | --------- |

receiver/postgresqlreceiver/internal/metadata/generated_metrics.go

@@ -262,7 +262,7 @@ events:
 metrics:
   postgresql.backends:
     enabled: true
-    description: The total number of PostgreSQL backend processes associated with this database, including client connections in active, idle, and idle-in-transaction states, as reported by `pg_stat_activity`.
+    description: The number of backend processes associated with each database, as reported by `pg_stat_activity`. Counts backends across all connection states (active, idle, idle-in-transaction) and all backend types, including non-client backends such as autovacuum and parallel workers.
     stability: development
     unit: "1"
     sum:

receiver/postgresqlreceiver/internal/metadata/generated_metrics_test.go

@@ -492,7 +492,7 @@ resourceMetrics:
             stringValue: postgres
     scopeMetrics:
       - metrics:
-          - description: The total number of PostgreSQL backend processes associated with this database, including client connections in active, idle, and idle-in-transaction states, as reported by `pg_stat_activity`.
+          - description: The number of backend processes associated with each database, as reported by `pg_stat_activity`. Counts backends across all connection states (active, idle, idle-in-transaction) and all backend types, including non-client backends such as autovacuum and parallel workers.
             name: postgresql.backends
             sum:
               aggregationTemporality: 2

receiver/postgresqlreceiver/metadata.yaml

@@ -6,7 +6,7 @@ resourceMetrics:
             stringValue: postgres
     scopeMetrics:
       - metrics:
-          - description: The total number of PostgreSQL backend processes associated with this database, including client connections in active, idle, and idle-in-transaction states, as reported by `pg_stat_activity`.
+          - description: The number of backend processes associated with each database, as reported by `pg_stat_activity`. Counts backends across all connection states (active, idle, idle-in-transaction) and all backend types, including non-client backends such as autovacuum and parallel workers.
             name: postgresql.backends
             sum:
               aggregationTemporality: 2
@@ -483,7 +483,7 @@ resourceMetrics:
             stringValue: otel
     scopeMetrics:
       - metrics:
-          - description: The total number of PostgreSQL backend processes associated with this database, including client connections in active, idle, and idle-in-transaction states, as reported by `pg_stat_activity`.
+          - description: The number of backend processes associated with each database, as reported by `pg_stat_activity`. Counts backends across all connection states (active, idle, idle-in-transaction) and all backend types, including non-client backends such as autovacuum and parallel workers.
             name: postgresql.backends
             sum:
               aggregationTemporality: 2
@@ -1028,7 +1028,7 @@ resourceMetrics:
             stringValue: otel2
     scopeMetrics:
       - metrics:
-          - description: The total number of PostgreSQL backend processes associated with this database, including client connections in active, idle, and idle-in-transaction states, as reported by `pg_stat_activity`.
+          - description: The number of backend processes associated with each database, as reported by `pg_stat_activity`. Counts backends across all connection states (active, idle, idle-in-transaction) and all backend types, including non-client backends such as autovacuum and parallel workers.
             name: postgresql.backends
             sum:
               aggregationTemporality: 2

receiver/postgresqlreceiver/testdata/integration/expected_all_db.yaml

@@ -492,7 +492,7 @@ resourceMetrics:
             stringValue: postgres
     scopeMetrics:
       - metrics:
-          - description: The total number of PostgreSQL backend processes associated with this database, including client connections in active, idle, and idle-in-transaction states, as reported by `pg_stat_activity`.
+          - description: The number of backend processes associated with each database, as reported by `pg_stat_activity`. Counts backends across all connection states (active, idle, idle-in-transaction) and all backend types, including non-client backends such as autovacuum and parallel workers.
             name: postgresql.backends
             sum:
               aggregationTemporality: 2

receiver/postgresqlreceiver/testdata/integration/expected_all_db_connpool.yaml

@@ -326,7 +326,7 @@ resourceMetrics:
             stringValue: otel
     scopeMetrics:
       - metrics:
-          - description: The total number of PostgreSQL backend processes associated with this database, including client connections in active, idle, and idle-in-transaction states, as reported by `pg_stat_activity`.
+          - description: The number of backend processes associated with each database, as reported by `pg_stat_activity`. Counts backends across all connection states (active, idle, idle-in-transaction) and all backend types, including non-client backends such as autovacuum and parallel workers.
             name: postgresql.backends
             sum:
               aggregationTemporality: 2
@@ -871,7 +871,7 @@ resourceMetrics:
             stringValue: otel2
     scopeMetrics:
       - metrics:
-          - description: The total number of PostgreSQL backend processes associated with this database, including client connections in active, idle, and idle-in-transaction states, as reported by `pg_stat_activity`.
+          - description: The number of backend processes associated with each database, as reported by `pg_stat_activity`. Counts backends across all connection states (active, idle, idle-in-transaction) and all backend types, including non-client backends such as autovacuum and parallel workers.
             name: postgresql.backends
             sum:
               aggregationTemporality: 2