Migrate db.statement to db.query.text (XSAM#478)

Part of XSAM#388

Author: XSAM

.gitignore

@@ -9,3 +9,5 @@ Thumbs.db
 coverage.*
 bin/
 vendor/
+example/otel-collector/otel-collector
+example/stdout/stdout

CHANGELOG.md

@@ -8,6 +8,14 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Added
+
+- Support to emit query related attributes for the v1.24.0 and v1.30.0 semantic conventions based on the value of the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable. (#478)
+
+  - `database/dup`: Emit both `db.statement` and `db.query.text` attributes.
+  - `database`: Emit `db.query.text` attribute.
+  - by default: Emit `db.statement` attribute.
+
 ## [0.38.0] - 2025-03-26
 
 ### Added

Makefile

@@ -60,7 +60,7 @@ build: generate
 	set -e; for dir in $(ALL_GO_MOD_DIRS); do \
 	  echo "$(GO) build $${dir}/..."; \
 	  (cd "$${dir}" && \
-	    $(GO) build -o ./bin/main ./... && \
+	    $(GO) build ./... && \
 		$(GO) list ./... \
 		  | grep -v third_party \
 		  | xargs $(GO) test -vet=off -run xxxxxMatchNothingxxxxx >/dev/null); \

config.go

@@ -22,6 +22,8 @@ import (
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/metric"
 	"go.opentelemetry.io/otel/trace"
+
+	internalsemconv "github.com/XSAM/otelsql/internal/semconv"
 )
 
 const (
@@ -90,6 +92,14 @@ type config struct {
 	// The measurement will be recorded as status=ok.
 	// Default is false
 	DisableSkipErrMeasurement bool
+
+	// SemConvStabilityOptIn controls which database semantic convention are emitted.
+	// It follows the value of environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`.
+	SemConvStabilityOptIn internalsemconv.OTelSemConvStabilityOptInType
+
+	// DBQueryTextAttributes will be called to produce related attributes on `db.query.text`.
+	// It follows the value of environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`.
+	DBQueryTextAttributes func(query string) []attribute.KeyValue
 }
 
 // SpanOptions holds configuration of tracing span to decide
@@ -148,6 +158,9 @@ func newConfig(options ...Option) config {
 		TracerProvider:    otel.GetTracerProvider(),
 		MeterProvider:     otel.GetMeterProvider(),
 		SpanNameFormatter: defaultSpanNameFormatter,
+		// Uses the stable behavior
+		SemConvStabilityOptIn: internalsemconv.OTelSemConvStabilityOptInStable,
+		DBQueryTextAttributes: internalsemconv.NewDBQueryTextAttributes(internalsemconv.OTelSemConvStabilityOptInStable),
 	}
 	for _, opt := range options {
 		opt.Apply(&cfg)
@@ -169,5 +182,11 @@ func newConfig(options ...Option) config {
 		otel.Handle(err)
 	}
 
+	// Initialize SemConvStabilityOptIn from environment
+	cfg.SemConvStabilityOptIn = internalsemconv.ParseOTelSemConvStabilityOptIn()
+
+	// Initialize DBQueryTextAttributes based on SemConvStabilityOptIn
+	cfg.DBQueryTextAttributes = internalsemconv.NewDBQueryTextAttributes(cfg.SemConvStabilityOptIn)
+
 	return cfg
 }

config_test.go

@@ -22,17 +22,31 @@ import (
 	"go.opentelemetry.io/otel"
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/metric"
-	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
+	semconvlegacy "go.opentelemetry.io/otel/semconv/v1.24.0"
+	semconv "go.opentelemetry.io/otel/semconv/v1.30.0"
 	"go.opentelemetry.io/otel/trace"
+
+	internalsemconv "github.com/XSAM/otelsql/internal/semconv"
 )
 
 func TestNewConfig(t *testing.T) {
-	cfg := newConfig(WithSpanOptions(SpanOptions{Ping: true}), WithAttributes(semconv.DBSystemMySQL))
+	// Set a clean environment for the test
+	t.Setenv(internalsemconv.OTelSemConvStabilityOptIn, "")
+
+	cfg := newConfig(WithSpanOptions(SpanOptions{Ping: true}), WithAttributes(semconv.DBSystemNameMySQL))
 
 	// Compare function result
 	assert.Equal(t, defaultSpanNameFormatter(context.Background(), "foo", "bar"), cfg.SpanNameFormatter(context.Background(), "foo", "bar"))
-	// Ignore function compare
+
+	// Verify DBQueryTextAttributes exists and returns expected format
+	assert.NotNil(t, cfg.DBQueryTextAttributes)
+	attrs := cfg.DBQueryTextAttributes("SELECT 1")
+	assert.Len(t, attrs, 1)
+	assert.Contains(t, attrs[0].Key, string(semconvlegacy.DBStatementKey))
+
+	// Ignore function compares for test equality check
 	cfg.SpanNameFormatter = nil
+	cfg.DBQueryTextAttributes = nil
 
 	assert.EqualValues(t, config{
 		TracerProvider: otel.GetTracerProvider(),
@@ -49,9 +63,71 @@ func TestNewConfig(t *testing.T) {
 		Instruments: cfg.Instruments,
 		SpanOptions: SpanOptions{Ping: true},
 		Attributes: []attribute.KeyValue{
-			semconv.DBSystemMySQL,
+			semconv.DBSystemNameMySQL,
 		},
-		SQLCommenter: newCommenter(false),
+		SQLCommenter:          newCommenter(false),
+		SemConvStabilityOptIn: internalsemconv.OTelSemConvStabilityOptInNone,
 	}, cfg)
 	assert.NotNil(t, cfg.Instruments)
 }
+
+func TestConfigSemConvStabilityOptIn(t *testing.T) {
+	testCases := []struct {
+		name          string
+		envValue      string
+		expectedOptIn internalsemconv.OTelSemConvStabilityOptInType
+	}{
+		{
+			name:          "none",
+			envValue:      "",
+			expectedOptIn: internalsemconv.OTelSemConvStabilityOptInNone,
+		},
+		{
+			name:          "database/dup",
+			envValue:      "database/dup",
+			expectedOptIn: internalsemconv.OTelSemConvStabilityOptInDup,
+		},
+		{
+			name:          "database",
+			envValue:      "database",
+			expectedOptIn: internalsemconv.OTelSemConvStabilityOptInStable,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			// Use t.Setenv which automatically cleans up after the test
+			t.Setenv(internalsemconv.OTelSemConvStabilityOptIn, tc.envValue)
+
+			// Create new config
+			cfg := newConfig()
+
+			// Check that SemConvStabilityOptIn is correctly set
+			assert.Equal(t, tc.expectedOptIn, cfg.SemConvStabilityOptIn)
+
+			// Check that DBQueryTextAttributes is initialized
+			assert.NotNil(t, cfg.DBQueryTextAttributes)
+
+			// Test with a sample query to verify it returns the expected attributes format
+			const query = "SELECT * FROM test"
+			attrs := cfg.DBQueryTextAttributes(query)
+
+			// Verify format of returned attributes based on opt-in type
+			switch tc.expectedOptIn {
+			case internalsemconv.OTelSemConvStabilityOptInNone:
+				assert.Equal(t, attrs, []attribute.KeyValue{
+					semconvlegacy.DBStatementKey.String(query),
+				})
+			case internalsemconv.OTelSemConvStabilityOptInDup:
+				assert.Equal(t, attrs, []attribute.KeyValue{
+					semconvlegacy.DBStatementKey.String(query),
+					semconv.DBQueryTextKey.String(query),
+				})
+			case internalsemconv.OTelSemConvStabilityOptInStable:
+				assert.Equal(t, attrs, []attribute.KeyValue{
+					semconv.DBQueryTextKey.String(query),
+				})
+			}
+		})
+	}
+}

conn_test.go

@@ -23,7 +23,7 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"go.opentelemetry.io/otel/attribute"
-	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
+	semconv "go.opentelemetry.io/otel/semconv/v1.30.0"
 	"go.opentelemetry.io/otel/trace"
 )
 
@@ -268,7 +268,7 @@ func TestOtConn_Ping(t *testing.T) {
 func TestOtConn_ExecContext(t *testing.T) {
 	query := "query"
 	args := []driver.NamedValue{{Value: "foo"}}
-	expectedAttrs := []attribute.KeyValue{semconv.DBStatementKey.String(query)}
+	expectedAttrs := []attribute.KeyValue{semconv.DBQueryTextKey.String(query)}
 
 	testCases := []struct {
 		name             string
@@ -362,7 +362,7 @@ func TestOtConn_ExecContext(t *testing.T) {
 func TestOtConn_QueryContext(t *testing.T) {
 	query := "query"
 	args := []driver.NamedValue{{Value: "foo"}}
-	expectedAttrs := []attribute.KeyValue{semconv.DBStatementKey.String(query)}
+	expectedAttrs := []attribute.KeyValue{semconv.DBQueryTextKey.String(query)}
 
 	for _, omitConnQuery := range []bool{true, false} {
 		var testname string
@@ -488,7 +488,7 @@ func TestOtConn_QueryContext(t *testing.T) {
 
 func TestOtConn_PrepareContext(t *testing.T) {
 	query := "query"
-	expectedAttrs := []attribute.KeyValue{semconv.DBStatementKey.String(query)}
+	expectedAttrs := []attribute.KeyValue{semconv.DBQueryTextKey.String(query)}
 
 	for _, legacy := range []bool{true, false} {
 		var testname string

driver_test.go

@@ -22,7 +22,7 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"go.opentelemetry.io/otel/attribute"
-	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
+	semconv "go.opentelemetry.io/otel/semconv/v1.30.0"
 )
 
 type mockDriver struct {
@@ -65,12 +65,12 @@ var (
 )
 
 func TestNewDriver(t *testing.T) {
-	d := newDriver(newMockDriver(false), config{Attributes: []attribute.KeyValue{semconv.DBSystemMySQL}})
+	d := newDriver(newMockDriver(false), config{Attributes: []attribute.KeyValue{semconv.DBSystemNameMySQL}})
 
 	otelDriver, ok := d.(*otDriver)
 	require.True(t, ok)
 	assert.Equal(t, newMockDriver(false), otelDriver.driver)
-	assert.Equal(t, config{Attributes: []attribute.KeyValue{semconv.DBSystemMySQL}}, otelDriver.cfg)
+	assert.Equal(t, config{Attributes: []attribute.KeyValue{semconv.DBSystemNameMySQL}}, otelDriver.cfg)
 }
 
 func TestOtDriver_Open(t *testing.T) {

example/otel-collector/main.go

@@ -31,7 +31,7 @@ import (
 	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
 	"go.opentelemetry.io/otel/sdk/resource"
 	sdktrace "go.opentelemetry.io/otel/sdk/trace"
-	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
+	semconv "go.opentelemetry.io/otel/semconv/v1.30.0"
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/credentials/insecure"
 
@@ -162,7 +162,7 @@ func main() {
 }
 
 func connectDB() *sql.DB {
-	attrs := append(otelsql.AttributesFromDSN(mysqlDSN), semconv.DBSystemMySQL)
+	attrs := append(otelsql.AttributesFromDSN(mysqlDSN), semconv.DBSystemNameMySQL)
 
 	// Connect to database
 	db, err := otelsql.Open("mysql", mysqlDSN, otelsql.WithAttributes(

example/stdout/main.go

@@ -30,7 +30,7 @@ import (
 	"go.opentelemetry.io/otel/sdk/metric"
 	"go.opentelemetry.io/otel/sdk/resource"
 	sdktrace "go.opentelemetry.io/otel/sdk/trace"
-	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
+	semconv "go.opentelemetry.io/otel/semconv/v1.30.0"
 
 	"github.com/XSAM/otelsql"
 )
@@ -86,7 +86,7 @@ func main() {
 	initTracer()
 	initMeter()
 
-	attrs := append(otelsql.AttributesFromDSN(mysqlDSN), semconv.DBSystemMySQL)
+	attrs := append(otelsql.AttributesFromDSN(mysqlDSN), semconv.DBSystemNameMySQL)
 
 	// Connect to database
 	db, err := otelsql.Open("mysql", mysqlDSN, otelsql.WithAttributes(

example_test.go

@@ -18,7 +18,7 @@ import (
 	"database/sql"
 	"database/sql/driver"
 
-	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
+	semconv "go.opentelemetry.io/otel/semconv/v1.30.0"
 
 	"github.com/XSAM/otelsql"
 )
@@ -80,7 +80,7 @@ func ExampleRegister() {
 }
 
 func ExampleAttributesFromDSN() {
-	attrs := append(otelsql.AttributesFromDSN(mysqlDSN), semconv.DBSystemMySQL)
+	attrs := append(otelsql.AttributesFromDSN(mysqlDSN), semconv.DBSystemNameMySQL)
 
 	// Connect to database
 	db, err := otelsql.Open("mysql", mysqlDSN, otelsql.WithAttributes(

helpers.go

@@ -20,7 +20,7 @@ import (
 	"strings"
 
 	"go.opentelemetry.io/otel/attribute"
-	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
+	semconv "go.opentelemetry.io/otel/semconv/v1.30.0"
 )
 
 // AttributesFromDSN returns attributes extracted from a DSN string.

helpers_test.go

@@ -19,7 +19,7 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"go.opentelemetry.io/otel/attribute"
-	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
+	semconv "go.opentelemetry.io/otel/semconv/v1.30.0"
 )
 
 func TestAttributesFromDSN(t *testing.T) {

internal/semconv/attributes.go

@@ -0,0 +1,55 @@
+// Copyright Sam Xie
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package semconv
+
+import (
+	"go.opentelemetry.io/otel/attribute"
+	semconvlegacy "go.opentelemetry.io/otel/semconv/v1.24.0"
+	semconv "go.opentelemetry.io/otel/semconv/v1.30.0"
+)
+
+// NewDBQueryTextAttributes returns a function that generates appropriate database query attributes
+// based on the provided OTelSemConvStabilityOptInType.
+//
+//   - OTelSemConvStabilityOptInNone: Only legacy db.statement attribute
+//   - OTelSemConvStabilityOptInDup: Both legacy db.statement and stable db.query.text attributes
+//   - OTelSemConvStabilityOptInStable: Only stable db.query.text attribute
+func NewDBQueryTextAttributes(optInType OTelSemConvStabilityOptInType) func(query string) []attribute.KeyValue {
+	switch optInType {
+	case OTelSemConvStabilityOptInDup:
+		// Emit both legacy and stable attributes
+		return func(query string) []attribute.KeyValue {
+			return []attribute.KeyValue{
+				semconvlegacy.DBStatementKey.String(query),
+				semconv.DBQueryTextKey.String(query),
+			}
+		}
+	case OTelSemConvStabilityOptInStable:
+		// Only emit stable attribute
+		return func(query string) []attribute.KeyValue {
+			return []attribute.KeyValue{
+				semconv.DBQueryTextKey.String(query),
+			}
+		}
+	default:
+		// OTelSemConvStabilityOptInNone or any unknown types
+		// Only emit legacy attribute
+		return func(query string) []attribute.KeyValue {
+			return []attribute.KeyValue{
+				semconvlegacy.DBStatementKey.String(query),
+			}
+		}
+	}
+}