refactor: rename internal trace package to tel (#638)

Before introducing OpenTelemetry into this project, it's important to
have a clear distinction between the existing telemetry based on
OpenCensus and the new telemetry which will be based on OpenTelemetry.
To do that, this commit renames the existing package containing metrics
and tracing to be more generic. Later commits will introduce a "tel/v2"
to make the relationship between old and new clear.

dialer.go

@@ -35,7 +35,7 @@ import (
 	"cloud.google.com/go/alloydbconn/debug"
 	"cloud.google.com/go/alloydbconn/errtype"
 	"cloud.google.com/go/alloydbconn/internal/alloydb"
-	"cloud.google.com/go/alloydbconn/internal/trace"
+	"cloud.google.com/go/alloydbconn/internal/tel"
 	"github.com/google/uuid"
 	"golang.org/x/net/proxy"
 	"golang.org/x/oauth2"
@@ -219,7 +219,7 @@ func NewDialer(ctx context.Context, opts ...Option) (*Dialer, error) {
 		opt(&dialCfg)
 	}
 
-	if err := trace.InitMetrics(); err != nil {
+	if err := tel.InitMetrics(); err != nil {
 		return nil, err
 	}
 	g, err := newKeyGenerator(cfg.rsaKey, cfg.lazyRefresh,
@@ -260,13 +260,13 @@ func (d *Dialer) Dial(ctx context.Context, instance string, opts ...DialOption)
 	default:
 	}
 	startTime := time.Now()
-	var endDial trace.EndSpanFunc
-	ctx, endDial = trace.StartSpan(ctx, "cloud.google.com/go/alloydbconn.Dial",
-		trace.AddInstanceName(instance),
-		trace.AddDialerID(d.dialerID),
+	var endDial tel.EndSpanFunc
+	ctx, endDial = tel.StartSpan(ctx, "cloud.google.com/go/alloydbconn.Dial",
+		tel.AddInstanceName(instance),
+		tel.AddDialerID(d.dialerID),
 	)
 	defer func() {
-		go trace.RecordDialError(context.Background(), instance, d.dialerID, err)
+		go tel.RecordDialError(context.Background(), instance, d.dialerID, err)
 		endDial(err)
 	}()
 	cfg := d.defaultDialCfg
@@ -278,8 +278,8 @@ func (d *Dialer) Dial(ctx context.Context, instance string, opts ...DialOption)
 		return nil, err
 	}
 
-	var endInfo trace.EndSpanFunc
-	ctx, endInfo = trace.StartSpan(ctx, "cloud.google.com/go/alloydbconn/internal.InstanceInfo")
+	var endInfo tel.EndSpanFunc
+	ctx, endInfo = tel.StartSpan(ctx, "cloud.google.com/go/alloydbconn/internal.InstanceInfo")
 	cache, err := d.connectionInfoCache(ctx, inst)
 	if err != nil {
 		endInfo(err)
@@ -318,8 +318,8 @@ func (d *Dialer) Dial(ctx context.Context, instance string, opts ...DialOption)
 		return nil, err
 	}
 
-	var connectEnd trace.EndSpanFunc
-	ctx, connectEnd = trace.StartSpan(ctx, "cloud.google.com/go/alloydbconn/internal.Connect")
+	var connectEnd tel.EndSpanFunc
+	ctx, connectEnd = tel.StartSpan(ctx, "cloud.google.com/go/alloydbconn/internal.Connect")
 	defer func() { connectEnd(err) }()
 	hostPort := net.JoinHostPort(addr, serverProxyPort)
 	f := d.dialFunc
@@ -374,13 +374,13 @@ func (d *Dialer) Dial(ctx context.Context, instance string, opts ...DialOption)
 	latency := time.Since(startTime).Milliseconds()
 	go func() {
 		n := atomic.AddUint64(cache.openConns, 1)
-		trace.RecordOpenConnections(ctx, int64(n), d.dialerID, inst.String())
-		trace.RecordDialLatency(ctx, instance, d.dialerID, latency)
+		tel.RecordOpenConnections(ctx, int64(n), d.dialerID, inst.String())
+		tel.RecordDialLatency(ctx, instance, d.dialerID, latency)
 	}()
 
 	return newInstrumentedConn(tlsConn, func() {
 		n := atomic.AddUint64(cache.openConns, ^uint64(0))
-		trace.RecordOpenConnections(context.Background(), int64(n), d.dialerID, inst.String())
+		tel.RecordOpenConnections(context.Background(), int64(n), d.dialerID, inst.String())
 	}, d.dialerID, inst.String()), nil
 }
 
@@ -560,7 +560,7 @@ type instrumentedConn struct {
 func (i *instrumentedConn) Read(b []byte) (int, error) {
 	bytesRead, err := i.Conn.Read(b)
 	if err == nil {
-		go trace.RecordBytesReceived(context.Background(), int64(bytesRead), i.instance, i.dialerID)
+		go tel.RecordBytesReceived(context.Background(), int64(bytesRead), i.instance, i.dialerID)
 	}
 	return bytesRead, err
 }
@@ -570,7 +570,7 @@ func (i *instrumentedConn) Read(b []byte) (int, error) {
 func (i *instrumentedConn) Write(b []byte) (int, error) {
 	bytesWritten, err := i.Conn.Write(b)
 	if err == nil {
-		go trace.RecordBytesSent(context.Background(), int64(bytesWritten), i.instance, i.dialerID)
+		go tel.RecordBytesSent(context.Background(), int64(bytesWritten), i.instance, i.dialerID)
 	}
 	return bytesWritten, err
 }

internal/alloydb/refresh.go

@@ -29,7 +29,7 @@ import (
 	alloydbadmin "cloud.google.com/go/alloydb/apiv1alpha"
 	"cloud.google.com/go/alloydb/apiv1alpha/alloydbpb"
 	"cloud.google.com/go/alloydbconn/errtype"
-	"cloud.google.com/go/alloydbconn/internal/trace"
+	"cloud.google.com/go/alloydbconn/internal/tel"
 	"google.golang.org/protobuf/types/known/durationpb"
 )
 
@@ -55,8 +55,8 @@ type instanceInfo struct {
 func fetchInstanceInfo(
 	ctx context.Context, cl *alloydbadmin.AlloyDBAdminClient, inst InstanceURI,
 ) (i instanceInfo, err error) {
-	var end trace.EndSpanFunc
-	ctx, end = trace.StartSpan(ctx, "cloud.google.com/go/alloydbconn/internal.FetchMetadata")
+	var end tel.EndSpanFunc
+	ctx, end = tel.StartSpan(ctx, "cloud.google.com/go/alloydbconn/internal.FetchMetadata")
 	defer func() { end(err) }()
 	req := &alloydbpb.GetConnectionInfoRequest{
 		Parent: fmt.Sprintf(
@@ -123,8 +123,8 @@ func fetchClientCertificate(
 	key *rsa.PrivateKey,
 	disableMetadataExchange bool,
 ) (cc *clientCertificate, err error) {
-	var end trace.EndSpanFunc
-	ctx, end = trace.StartSpan(ctx, "cloud.google.com/go/alloydbconn/internal.FetchEphemeralCert")
+	var end tel.EndSpanFunc
+	ctx, end = tel.StartSpan(ctx, "cloud.google.com/go/alloydbconn/internal.FetchEphemeralCert")
 	defer func() { end(err) }()
 
 	buf := &bytes.Buffer{}
@@ -263,12 +263,12 @@ func (c adminAPIClient) connectionInfo(
 	ctx context.Context, i InstanceURI,
 ) (res ConnectionInfo, err error) {
 
-	var refreshEnd trace.EndSpanFunc
-	ctx, refreshEnd = trace.StartSpan(ctx, "cloud.google.com/go/alloydbconn/internal.RefreshConnection",
-		trace.AddInstanceName(i.String()),
+	var refreshEnd tel.EndSpanFunc
+	ctx, refreshEnd = tel.StartSpan(ctx, "cloud.google.com/go/alloydbconn/internal.RefreshConnection",
+		tel.AddInstanceName(i.String()),
 	)
 	defer func() {
-		go trace.RecordRefreshResult(
+		go tel.RecordRefreshResult(
 			context.Background(), i.String(), c.dialerID, err,
 		)
 		refreshEnd(err)

internal/tel/doc.go

@@ -0,0 +1,17 @@
+// Copyright 2024 Google LLC
+//
+// 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
+//
+//	https://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 tel provides telemetry data on the connector's internal operations.
+// The initial version is based on OpenCensus.
+package tel

internal/trace/metrics.go → internal/tel/metrics.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package trace
+package tel
 
 import (
 	"context"

internal/trace/metrics_test.go → internal/tel/metrics_test.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package trace
+package tel
 
 import (
 	"errors"

internal/trace/trace.go → internal/tel/trace.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package trace
+package tel
 
 import (
 	"context"