[receiver/postgresql] Add receiver.postgresql.useOTelSemconv feature gate for OTel semconv resource model (#45345)

#### Description

Adds a new **`receiver.postgresql.useOTelSemconv`** feature gate (alpha,
disabled by default) that aligns the PostgreSQL receiver's resource
model with [OpenTelemetry semantic
conventions](https://opentelemetry.io/docs/specs/semconv/database/postgresql/).

##### Feature gate: `receiver.postgresql.useOTelSemconv`

**When disabled (default):** Legacy per-entity resource model is
preserved. Each database, table, and index emits metrics under a
separate resource with `postgresql.database.name`,
`postgresql.table.name`, `postgresql.index.name`, and
`postgresql.schema.name` as resource attributes.

**When enabled:** All metrics from a single PostgreSQL server are
emitted under one resource identified by:
- **`service.instance.id`**: Deterministic UUID v5 derived from server
address and port, using the [OTel namespace
UUID](https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/).
This ensures the `(service.namespace, service.name,
service.instance.id)` triplet is globally unique, which is required for
correct Prometheus OTLP conversion.
- **`server.address`**: PostgreSQL hostname, IP address, or Unix socket
path per semconv.
- **`server.port`**: PostgreSQL server port per semconv.

Database, schema, table, and index are differentiated through
metric-level attributes instead of resource attributes.

This gate is mutually exclusive with
`receiver.postgresql.separateSchemaAttr` — both cannot be enabled
simultaneously.

##### Added metric-level attributes when feature gate is enabled

The following metric-level attributes are added to applicable metrics
when the feature gate is enabled:
- **`db.namespace`**: Database name for database-level metrics;
`{database}|{schema}` for table/index/function metrics
- **`db.collection.name`**: Table name on table-level metrics 

#### Link to tracking issue

Fixes #45347.

#### Testing

- Focused semconv and feature-gate tests are added
- A semconv integration test is added
- Three semconv goldens are added

#### Documentation

- `documentation.md` regenerated via `mdatagen` to reflect new
attributes.
- `README.md` updated with new "OpenTelemetry semantic conventions
feature gate" section and mutual exclusivity note.
- Changelog entry added in `.chloggen/postgresql-service-name.yaml`.

<!--Authorship attestation. See AGENTS.md for details. AI agents must
not check this box on behalf
of the user; the human author must check it themselves before the PR is
ready for review.-->
#### Authorship

- [x] I, a human, wrote this pull request description myself.

---------

Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>

Author: aknuds1

.chloggen/postgresql-service-name.yaml

@@ -0,0 +1,33 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. receiver/filelog)
+component: receiver/postgresql
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: |
+  Align resource and metric attributes with OpenTelemetry semantic conventions behind the
+  receiver.postgresql.useOTelSemconv feature gate (alpha, disabled by default).
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [45347]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  - When gate enabled: single resource per server with server.address, server.port, service.instance.id (UUID v5)
+  - When gate enabled: db.namespace, db.collection.name, postgresql.index.name added as metric-level attributes
+  - When gate disabled (default): legacy per-entity resource model with postgresql.database.name, etc.
+  - receiver.postgresql.separateSchemaAttr kept at StageAlpha; mutually exclusive with useOTelSemconv
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]

receiver/postgresqlreceiver/README.md

@@ -48,6 +48,9 @@ The monitoring user must be granted `SELECT` on `pg_stat_database`.
 > otelcol-contrib --feature-gates=receiver.postgresql.separateSchemaAttr
 > ```
 >
+> **Note:** This gate is mutually exclusive with `receiver.postgresql.useOTelSemconv`. Both cannot be
+> enabled at the same time.
+>
 > See https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/29559 for more details.
 
 ## Configuration
@@ -191,6 +194,15 @@ receivers:
       max_open: 5
 ```
 
+## OpenTelemetry semantic conventions feature gate
+
+The feature gate `receiver.postgresql.useOTelSemconv` (alpha, disabled by default) controls the resource model used by this receiver:
+
+- **Gate disabled (default):** Legacy per-entity resource model. Each database, table, and index emits metrics under a separate resource with `postgresql.database.name`, `postgresql.table.name`, `postgresql.index.name`, and `postgresql.schema.name` as resource attributes. `service.instance.id` is in `host:port` format.
+- **Gate enabled:** Single resource per server. All metrics are emitted under one resource with `server.address`, `server.port`, and `service.instance.id` (UUID v5) as resource attributes, aligning with OpenTelemetry semantic conventions. Metric-level attributes `db.namespace`, `db.collection.name`, and `postgresql.index.name` are present on applicable metrics.
+
+This gate is mutually exclusive with `receiver.postgresql.separateSchemaAttr` — both cannot be enabled simultaneously.
+
 ## Metrics
 
 Details about the metrics produced by this receiver can be found in [metadata.yaml](./metadata.yaml)

receiver/postgresqlreceiver/documentation.md

@@ -95,7 +95,10 @@ func createMetricsReceiver(
 		clientFactory = newDefaultClientFactory(cfg)
 	}
 
-	ns := newPostgreSQLScraper(params, cfg, clientFactory, newCache(1), newTTLCache[string](1, time.Second))
+	ns, err := newPostgreSQLScraper(params, cfg, clientFactory, newCache(1), newTTLCache[string](1, time.Second))
+	if err != nil {
+		return nil, err
+	}
 	s, err := scraper.NewMetrics(ns.scrape, scraper.WithShutdown(ns.shutdown))
 	if err != nil {
 		return nil, err
@@ -128,7 +131,10 @@ func createLogsReceiver(
 	if cfg.Events.DbServerQuerySample.Enabled {
 		// query sample collection does not need cache, but we do not want to make it
 		// nil, so create one size 1 cache as a placeholder.
-		ns := newPostgreSQLScraper(params, cfg, clientFactory, newCache(1), newTTLCache[string](1, time.Second))
+		ns, err := newPostgreSQLScraper(params, cfg, clientFactory, newCache(1), newTTLCache[string](1, time.Second))
+		if err != nil {
+			return nil, err
+		}
 		s, err := scraper.NewLogs(func(ctx context.Context) (plog.Logs, error) {
 			return ns.scrapeQuerySamples(ctx, cfg.QuerySampleCollection.MaxRowsPerQuery)
 		}, scraper.WithShutdown(ns.shutdown))
@@ -145,7 +151,10 @@ func createLogsReceiver(
 
 	if cfg.Events.DbServerTopQuery.Enabled {
 		// we have 10 updated only attributes. so we set the cache size accordingly.
-		ns := newPostgreSQLScraper(params, cfg, clientFactory, newCache(int(cfg.TopNQuery*10*2)), newTTLCache[string](cfg.QueryPlanCacheSize, cfg.QueryPlanCacheTTL))
+		ns, err := newPostgreSQLScraper(params, cfg, clientFactory, newCache(int(cfg.TopNQuery*10*2)), newTTLCache[string](cfg.QueryPlanCacheSize, cfg.QueryPlanCacheTTL))
+		if err != nil {
+			return nil, err
+		}
 		s, err := scraper.NewLogs(func(ctx context.Context) (plog.Logs, error) {
 			return ns.scrapeTopQuery(ctx, cfg.TopQueryCollection.MaxRowsPerQuery, cfg.TopNQuery, cfg.MaxExplainEachInterval, cfg.TopQueryCollection.CollectionInterval)
 		}, scraper.WithShutdown(ns.shutdown))

receiver/postgresqlreceiver/factory.go

@@ -6,6 +6,7 @@ require (
 	github.com/DATA-DOG/go-sqlmock v1.5.2
 	github.com/DataDog/datadog-agent/pkg/obfuscate v0.77.0-devel.0.20260213154712-e02b9359151a
 	github.com/google/go-cmp v0.7.0
+	github.com/google/uuid v1.6.0
 	github.com/hashicorp/golang-lru/v2 v2.0.7
 	github.com/lib/pq v1.12.3
 	github.com/open-telemetry/opentelemetry-collector-contrib/internal/common v0.156.0
@@ -67,7 +68,6 @@ require (
 	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
 	github.com/gobwas/glob v0.2.3 // indirect
 	github.com/google/go-tpm v0.9.8 // indirect
-	github.com/google/uuid v1.6.0 // indirect
 	github.com/hashicorp/go-version v1.9.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/compress v1.18.5 // indirect

receiver/postgresqlreceiver/go.mod

@@ -65,7 +65,67 @@ func TestIntegrationWithConnectionPool(t *testing.T) {
 	t.Run("all_db_connpool", integrationTest("all_db_connpool", []string{}, pre17TestVersion))
 }
 
-func integrationTest(name string, databases []string, pgVersion string) func(*testing.T) {
+func TestIntegrationSemconv(t *testing.T) {
+	defer testutil.SetFeatureGateForTest(t, metadata.ReceiverPostgresqlUseOTelSemconvFeatureGate, true)()
+	defer testutil.SetFeatureGateForTest(t, metadata.ReceiverPostgresqlConnectionPoolFeatureGate, false)()
+	t.Run("multi_db", integrationTestSemconv("multi_db_semconv", []string{"otel", "otel2"}, pre17TestVersion))
+}
+
+func integrationTest(
+	name string,
+	databases []string,
+	pgVersion string,
+	additionalIgnoredResourceAttributeValues ...string,
+) func(*testing.T) {
+	compareOptions := []pmetrictest.CompareMetricsOption{
+		pmetrictest.IgnoreResourceAttributeValue("service.instance.id"),
+	}
+	for _, attribute := range additionalIgnoredResourceAttributeValues {
+		compareOptions = append(compareOptions, pmetrictest.IgnoreResourceAttributeValue(attribute))
+	}
+	compareOptions = append(compareOptions,
+		pmetrictest.IgnoreResourceMetricsOrder(),
+		pmetrictest.IgnoreMetricValues(
+			"postgresql.backends",
+			"postgresql.bgwriter.buffers.allocated",
+			"postgresql.bgwriter.buffers.writes",
+			"postgresql.bgwriter.checkpoint.count",
+			"postgresql.bgwriter.duration",
+			"postgresql.bgwriter.maxwritten",
+			"postgresql.blks_hit",
+			"postgresql.blks_read",
+			"postgresql.blocks_read",
+			"postgresql.commits",
+			"postgresql.connection.max",
+			"postgresql.database.count",
+			"postgresql.database.locks",
+			"postgresql.db_size",
+			"postgresql.deadlocks",
+			"postgresql.index.scans",
+			"postgresql.index.size",
+			"postgresql.operations",
+			"postgresql.replication.data_delay",
+			"postgresql.rollbacks",
+			"postgresql.rows",
+			"postgresql.sequential_scans",
+			"postgresql.table.count",
+			"postgresql.table.size",
+			"postgresql.table.vacuum.count",
+			"postgresql.tup_deleted",
+			"postgresql.tup_fetched",
+			"postgresql.tup_inserted",
+			"postgresql.tup_returned",
+			"postgresql.tup_updated",
+			"postgresql.wal.age",
+			"postgresql.wal.delay",
+			"postgresql.wal.lag",
+		),
+		pmetrictest.IgnoreSubsequentDataPoints("postgresql.backends"),
+		pmetrictest.IgnoreMetricDataPointsOrder(),
+		pmetrictest.IgnoreStartTimestamp(),
+		pmetrictest.IgnoreTimestamp(),
+	)
+
 	expectedFile := filepath.Join("testdata", "integration", "expected_"+name+".yaml")
 	return scraperinttest.NewIntegrationTest(
 		NewFactory(),
@@ -110,52 +170,14 @@ func integrationTest(name string, databases []string, pgVersion string) func(*te
 				rCfg.Metrics.PostgresqlDatabaseLocks.Enabled = true
 			}),
 		scraperinttest.WithExpectedFile(expectedFile),
-		scraperinttest.WithCompareOptions(
-			pmetrictest.IgnoreResourceAttributeValue("service.instance.id"),
-			pmetrictest.IgnoreResourceMetricsOrder(),
-			pmetrictest.IgnoreMetricValues(
-				"postgresql.backends",
-				"postgresql.bgwriter.buffers.allocated",
-				"postgresql.bgwriter.buffers.writes",
-				"postgresql.bgwriter.checkpoint.count",
-				"postgresql.bgwriter.duration",
-				"postgresql.bgwriter.maxwritten",
-				"postgresql.blks_hit",
-				"postgresql.blks_read",
-				"postgresql.blocks_read",
-				"postgresql.commits",
-				"postgresql.connection.max",
-				"postgresql.database.count",
-				"postgresql.database.locks",
-				"postgresql.db_size",
-				"postgresql.deadlocks",
-				"postgresql.index.scans",
-				"postgresql.index.size",
-				"postgresql.operations",
-				"postgresql.replication.data_delay",
-				"postgresql.rollbacks",
-				"postgresql.rows",
-				"postgresql.sequential_scans",
-				"postgresql.table.count",
-				"postgresql.table.size",
-				"postgresql.table.vacuum.count",
-				"postgresql.tup_deleted",
-				"postgresql.tup_fetched",
-				"postgresql.tup_inserted",
-				"postgresql.tup_returned",
-				"postgresql.tup_updated",
-				"postgresql.wal.age",
-				"postgresql.wal.delay",
-				"postgresql.wal.lag",
-			),
-			pmetrictest.IgnoreSubsequentDataPoints("postgresql.backends"),
-			pmetrictest.IgnoreMetricDataPointsOrder(),
-			pmetrictest.IgnoreStartTimestamp(),
-			pmetrictest.IgnoreTimestamp(),
-		),
+		scraperinttest.WithCompareOptions(compareOptions...),
 	).Run
 }
 
+func integrationTestSemconv(name string, databases []string, pgVersion string) func(*testing.T) {
+	return integrationTest(name, databases, pgVersion, "server.address", "server.port")
+}
+
 func TestGetDatabaseTableMetricsIgnoresAccessExclusiveLocks(t *testing.T) {
 	ci, err := testcontainers.GenericContainer(
 		t.Context(),
@@ -367,11 +389,12 @@ func TestScrapeLogsFromContainer(t *testing.T) {
 	}
 	clientFactory := newDefaultClientFactory(&cfg)
 
-	ns := newPostgreSQLScraper(receiver.Settings{
+	ns, err := newPostgreSQLScraper(receiver.Settings{
 		TelemetrySettings: component.TelemetrySettings{
 			Logger: zap.Must(zap.NewProduction()),
 		},
 	}, &cfg, clientFactory, newCache(1), newTTLCache[string](1000, time.Second))
+	assert.NoError(t, err)
 	plogs, err := ns.scrapeQuerySamples(t.Context(), 30)
 	assert.NoError(t, err)
 	logRecords := plogs.ResourceLogs().At(0).ScopeLogs().At(0).LogRecords()