From c540b4a3c06eb11fcf3b676f8090a5d357be9cbc Mon Sep 17 00:00:00 2001
From: Eno Compton <enocom@google.com>
Date: Mon, 2 Dec 2024 12:52:37 -0700
Subject: [PATCH] refactor: rename internal trace package to tel

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                               | 32 ++++++++++++-------------
 internal/alloydb/refresh.go             | 18 +++++++-------
 internal/tel/doc.go                     | 17 +++++++++++++
 internal/{trace => tel}/metrics.go      |  2 +-
 internal/{trace => tel}/metrics_test.go |  2 +-
 internal/{trace => tel}/trace.go        |  2 +-
 6 files changed, 45 insertions(+), 28 deletions(-)
 create mode 100644 internal/tel/doc.go
 rename internal/{trace => tel}/metrics.go (99%)
 rename internal/{trace => tel}/metrics_test.go (99%)
 rename internal/{trace => tel}/trace.go (99%)

diff --git a/dialer.go b/dialer.go
index 40226a0c..915702cd 100644
--- a/dialer.go
+++ b/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
 }
diff --git a/internal/alloydb/refresh.go b/internal/alloydb/refresh.go
index e3b97223..2c246fe6 100644
--- a/internal/alloydb/refresh.go
+++ b/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)
diff --git a/internal/tel/doc.go b/internal/tel/doc.go
new file mode 100644
index 00000000..b6adf7ff
--- /dev/null
+++ b/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
diff --git a/internal/trace/metrics.go b/internal/tel/metrics.go
similarity index 99%
rename from internal/trace/metrics.go
rename to internal/tel/metrics.go
index 962428b7..f8172d3b 100644
--- a/internal/trace/metrics.go
+++ b/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"
diff --git a/internal/trace/metrics_test.go b/internal/tel/metrics_test.go
similarity index 99%
rename from internal/trace/metrics_test.go
rename to internal/tel/metrics_test.go
index 204ceff5..a6c09d73 100644
--- a/internal/trace/metrics_test.go
+++ b/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"
diff --git a/internal/trace/trace.go b/internal/tel/trace.go
similarity index 99%
rename from internal/trace/trace.go
rename to internal/tel/trace.go
index cd5ecd6a..f87d4378 100644
--- a/internal/trace/trace.go
+++ b/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"