[receiver/postgresql] clarify postgresql.backends metric semantics

receiver/postgresqlreceiver/README.md

@@ -97,6 +97,13 @@ to grant the user you are using `pg_monitor`. Take the example from `testdata/in
 GRANT pg_monitor TO otelu;
 ```
 
+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 
 against `pg_stat_activity`.

receiver/postgresqlreceiver/client.go

@@ -390,7 +390,10 @@ func (c *postgreSQLClient) getDatabaseLocks(ctx context.Context) ([]databaseLock
 	return dl, multierr.Combine(errs...)
 }
 
-// getBackends returns a map of database names to the number of active connections
+// 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 number of backends.
+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/metadata.yaml

@@ -334,7 +334,7 @@ events:
 metrics:
   postgresql.backends:
     enabled: true
-    description: The number of backends.
+    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/scraper.go

@@ -186,10 +186,10 @@ func legacyMetricAttributes[T ~string](attributes []T) []T {
 
 type dbRetrieval struct {
 	sync.RWMutex
-	activityMap     map[databaseName]int64
-	dbSizeMap       map[databaseName]int64
-	dbStats         map[databaseName]databaseStats
-	dbConflictStats map[databaseName]databaseConflictStats
+	backendCountByDB map[databaseName]int64
+	dbSizeMap        map[databaseName]int64
+	dbStats          map[databaseName]databaseStats
+	dbConflictStats  map[databaseName]databaseConflictStats
 }
 
 // scrape scrapes the metric stats, transforms them and attributes them into a metric slices.
@@ -222,10 +222,10 @@ func (p *postgreSQLScraper) scrape(ctx context.Context) (pmetric.Metrics, error)
 
 	var errs errsMux
 	r := &dbRetrieval{
-		activityMap:     make(map[databaseName]int64),
-		dbSizeMap:       make(map[databaseName]int64),
-		dbStats:         make(map[databaseName]databaseStats),
-		dbConflictStats: make(map[databaseName]databaseConflictStats),
+		backendCountByDB: make(map[databaseName]int64),
+		dbSizeMap:        make(map[databaseName]int64),
+		dbStats:          make(map[databaseName]databaseStats),
+		dbConflictStats:  make(map[databaseName]databaseConflictStats),
 	}
 	p.retrieveDBMetrics(ctx, listClient, databases, r, &errs)
 
@@ -552,8 +552,8 @@ func (p *postgreSQLScraper) retrieveDBMetrics(
 func (p *postgreSQLScraper) recordDatabase(now pcommon.Timestamp, db string, r *dbRetrieval, numTables int64) {
 	dbName := databaseName(db)
 	p.mb.RecordPostgresqlTableCountDataPoint(now, numTables, db)
-	if activeConnections, ok := r.activityMap[dbName]; ok {
-		p.mb.RecordPostgresqlBackendsDataPoint(now, activeConnections, db)
+	if backendCount, ok := r.backendCountByDB[dbName]; ok {
+		p.mb.RecordPostgresqlBackendsDataPoint(now, backendCount, db)
 	}
 	if size, ok := r.dbSizeMap[dbName]; ok {
 		p.mb.RecordPostgresqlDbSizeDataPoint(now, size, db)
@@ -893,13 +893,13 @@ func (*postgreSQLScraper) retrieveBackends(
 	errs *errsMux,
 ) {
 	defer wg.Done()
-	activityByDB, err := client.getBackends(ctx, databases)
+	backendCountByDB, err := client.getBackends(ctx, databases)
 	if err != nil {
 		errs.addPartial(err)
 		return
 	}
 	r.Lock()
-	r.activityMap = activityByDB
+	r.backendCountByDB = backendCountByDB
 	r.Unlock()
 }
 

receiver/postgresqlreceiver/testdata/integration/expected_all_db.yaml

@@ -492,7 +492,7 @@ resourceMetrics:
             stringValue: postgres
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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

@@ -6,7 +6,7 @@ resourceMetrics:
             stringValue: postgres
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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 number of backends.
+          - 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 number of backends.
+          - 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_schemaattr.yaml

@@ -492,7 +492,7 @@ resourceMetrics:
             stringValue: postgres
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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_multi_db_connpool.yaml

@@ -326,7 +326,7 @@ resourceMetrics:
             stringValue: otel
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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 number of backends.
+          - 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_single_db_connpool.yaml

@@ -326,7 +326,7 @@ resourceMetrics:
             stringValue: otel
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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/scraper/multiple/exclude.yaml

@@ -146,7 +146,7 @@ resourceMetrics:
             stringValue: otel
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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
@@ -203,7 +203,7 @@ resourceMetrics:
             stringValue: telemetry
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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/scraper/multiple/exclude_schemaattr.yaml

@@ -146,7 +146,7 @@ resourceMetrics:
             stringValue: otel
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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
@@ -203,7 +203,7 @@ resourceMetrics:
             stringValue: telemetry
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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/scraper/multiple/expected.yaml

@@ -212,7 +212,7 @@ resourceMetrics:
             stringValue: open
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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
@@ -369,7 +369,7 @@ resourceMetrics:
             stringValue: otel
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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
@@ -526,7 +526,7 @@ resourceMetrics:
             stringValue: telemetry
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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/scraper/multiple/expected_imprecise_lag.yaml

@@ -212,7 +212,7 @@ resourceMetrics:
             stringValue: open
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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
@@ -369,7 +369,7 @@ resourceMetrics:
             stringValue: otel
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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
@@ -526,7 +526,7 @@ resourceMetrics:
             stringValue: telemetry
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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/scraper/multiple/expected_imprecise_lag_schemaattr.yaml

@@ -212,7 +212,7 @@ resourceMetrics:
             stringValue: open
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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
@@ -369,7 +369,7 @@ resourceMetrics:
             stringValue: otel
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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
@@ -526,7 +526,7 @@ resourceMetrics:
             stringValue: telemetry
     scopeMetrics:
       - metrics:
-          - description: The number of backends.
+          - 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