trace.go

Documentation: cloud.google.com/go/internal/trace

     1  // Copyright 2018 Google LLC
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package trace
    16  
    17  import (
    18  	"context"
    19  	"errors"
    20  	"fmt"
    21  	"os"
    22  	"strings"
    23  	"sync"
    24  
    25  	"go.opencensus.io/trace"
    26  	"go.opentelemetry.io/otel"
    27  	"go.opentelemetry.io/otel/attribute"
    28  	"go.opentelemetry.io/otel/codes"
    29  	ottrace "go.opentelemetry.io/otel/trace"
    30  	"google.golang.org/api/googleapi"
    31  	"google.golang.org/genproto/googleapis/rpc/code"
    32  	"google.golang.org/grpc/status"
    33  )
    34  
    35  const (
    36  	// TelemetryPlatformTracingOpenCensus is the value to which the environment
    37  	// variable GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING should be
    38  	// set to enable OpenCensus tracing.
    39  	TelemetryPlatformTracingOpenCensus = "opencensus"
    40  	// TelemetryPlatformTracingOpenCensus is the value to which the environment
    41  	// variable GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING should be
    42  	// set to enable OpenTelemetry tracing.
    43  	TelemetryPlatformTracingOpenTelemetry = "opentelemetry"
    44  	// TelemetryPlatformTracingOpenCensus is the name of the environment
    45  	// variable that can be set to change the default tracing from OpenCensus
    46  	// to OpenTelemetry.
    47  	TelemetryPlatformTracingVar = "GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING"
    48  	// OpenTelemetryTracerName is the name given to the OpenTelemetry Tracer
    49  	// when it is obtained from the OpenTelemetry TracerProvider.
    50  	OpenTelemetryTracerName = "cloud.google.com/go"
    51  )
    52  
    53  var (
    54  	// openTelemetryTracingEnabledMu guards access to openTelemetryTracingEnabled field
    55  	openTelemetryTracingEnabledMu = sync.RWMutex{}
    56  	// openTelemetryTracingEnabled is true if the environment variable
    57  	// GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING is set to the
    58  	// case-insensitive value "opentelemetry".
    59  	openTelemetryTracingEnabled bool = strings.EqualFold(strings.TrimSpace(
    60  		os.Getenv(TelemetryPlatformTracingVar)), TelemetryPlatformTracingOpenTelemetry)
    61  )
    62  
    63  // SetOpenTelemetryTracingEnabledField programmatically sets the value provided by GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING for the purpose of unit testing.
    64  // Do not invoke it directly. Intended for use only in unit tests. Restore original value after each test.
    65  func SetOpenTelemetryTracingEnabledField(enabled bool) {
    66  	openTelemetryTracingEnabledMu.Lock()
    67  	defer openTelemetryTracingEnabledMu.Unlock()
    68  	openTelemetryTracingEnabled = enabled
    69  }
    70  
    71  // IsOpenCensusTracingEnabled returns true if the environment variable
    72  // GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING is NOT set to the
    73  // case-insensitive value "opentelemetry".
    74  func IsOpenCensusTracingEnabled() bool {
    75  	return !IsOpenTelemetryTracingEnabled()
    76  }
    77  
    78  // IsOpenTelemetryTracingEnabled returns true if the environment variable
    79  // GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING is set to the
    80  // case-insensitive value "opentelemetry".
    81  func IsOpenTelemetryTracingEnabled() bool {
    82  	openTelemetryTracingEnabledMu.RLock()
    83  	defer openTelemetryTracingEnabledMu.RUnlock()
    84  	return openTelemetryTracingEnabled
    85  }
    86  
    87  // StartSpan adds a span to the trace with the given name. If IsOpenCensusTracingEnabled
    88  // returns true, the span will be an OpenCensus span. If IsOpenTelemetryTracingEnabled
    89  // returns true, the span will be an OpenTelemetry span. Set the environment variable
    90  // GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING to the case-insensitive
    91  // value "opentelemetry" before loading the package to use OpenTelemetry tracing.
    92  // The default will remain OpenCensus until May 29, 2024, at which time the default will
    93  // switch to "opentelemetry" and explicitly setting the environment variable to
    94  // "opencensus" will be required to continue using OpenCensus tracing.
    95  func StartSpan(ctx context.Context, name string) context.Context {
    96  	if IsOpenTelemetryTracingEnabled() {
    97  		ctx, _ = otel.GetTracerProvider().Tracer(OpenTelemetryTracerName).Start(ctx, name)
    98  	} else {
    99  		ctx, _ = trace.StartSpan(ctx, name)
   100  	}
   101  	return ctx
   102  }
   103  
   104  // EndSpan ends a span with the given error. If IsOpenCensusTracingEnabled
   105  // returns true, the span will be an OpenCensus span. If IsOpenTelemetryTracingEnabled
   106  // returns true, the span will be an OpenTelemetry span. Set the environment variable
   107  // GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING to the case-insensitive
   108  // value "opentelemetry" before loading the package to use OpenTelemetry tracing.
   109  // The default will remain OpenCensus until May 29, 2024, at which time the default will
   110  // switch to "opentelemetry" and explicitly setting the environment variable to
   111  // "opencensus" will be required to continue using OpenCensus tracing.
   112  func EndSpan(ctx context.Context, err error) {
   113  	if IsOpenTelemetryTracingEnabled() {
   114  		span := ottrace.SpanFromContext(ctx)
   115  		if err != nil {
   116  			span.SetStatus(codes.Error, toOpenTelemetryStatusDescription(err))
   117  			span.RecordError(err)
   118  		}
   119  		span.End()
   120  	} else {
   121  		span := trace.FromContext(ctx)
   122  		if err != nil {
   123  			span.SetStatus(toStatus(err))
   124  		}
   125  		span.End()
   126  	}
   127  }
   128  
   129  // toStatus converts an error to an equivalent OpenCensus status.
   130  func toStatus(err error) trace.Status {
   131  	var err2 *googleapi.Error
   132  	if ok := errors.As(err, &err2); ok {
   133  		return trace.Status{Code: httpStatusCodeToOCCode(err2.Code), Message: err2.Message}
   134  	} else if s, ok := status.FromError(err); ok {
   135  		return trace.Status{Code: int32(s.Code()), Message: s.Message()}
   136  	} else {
   137  		return trace.Status{Code: int32(code.Code_UNKNOWN), Message: err.Error()}
   138  	}
   139  }
   140  
   141  // toOpenTelemetryStatus converts an error to an equivalent OpenTelemetry status description.
   142  func toOpenTelemetryStatusDescription(err error) string {
   143  	var err2 *googleapi.Error
   144  	if ok := errors.As(err, &err2); ok {
   145  		return err2.Message
   146  	} else if s, ok := status.FromError(err); ok {
   147  		return s.Message()
   148  	} else {
   149  		return err.Error()
   150  	}
   151  }
   152  
   153  // TODO(deklerk): switch to using OpenCensus function when it becomes available.
   154  // Reference: https://github.com/googleapis/googleapis/blob/26b634d2724ac5dd30ae0b0cbfb01f07f2e4050e/google/rpc/code.proto
   155  func httpStatusCodeToOCCode(httpStatusCode int) int32 {
   156  	switch httpStatusCode {
   157  	case 200:
   158  		return int32(code.Code_OK)
   159  	case 499:
   160  		return int32(code.Code_CANCELLED)
   161  	case 500:
   162  		return int32(code.Code_UNKNOWN) // Could also be Code_INTERNAL, Code_DATA_LOSS
   163  	case 400:
   164  		return int32(code.Code_INVALID_ARGUMENT) // Could also be Code_OUT_OF_RANGE
   165  	case 504:
   166  		return int32(code.Code_DEADLINE_EXCEEDED)
   167  	case 404:
   168  		return int32(code.Code_NOT_FOUND)
   169  	case 409:
   170  		return int32(code.Code_ALREADY_EXISTS) // Could also be Code_ABORTED
   171  	case 403:
   172  		return int32(code.Code_PERMISSION_DENIED)
   173  	case 401:
   174  		return int32(code.Code_UNAUTHENTICATED)
   175  	case 429:
   176  		return int32(code.Code_RESOURCE_EXHAUSTED)
   177  	case 501:
   178  		return int32(code.Code_UNIMPLEMENTED)
   179  	case 503:
   180  		return int32(code.Code_UNAVAILABLE)
   181  	default:
   182  		return int32(code.Code_UNKNOWN)
   183  	}
   184  }
   185  
   186  // TracePrintf retrieves the current OpenCensus or OpenTelemetry span from context, then:
   187  // * calls Span.Annotatef if OpenCensus is enabled; or
   188  // * calls Span.AddEvent if OpenTelemetry is enabled.
   189  //
   190  // If IsOpenCensusTracingEnabled returns true, the expected span must be an
   191  // OpenCensus span. If IsOpenTelemetryTracingEnabled returns true, the expected
   192  // span must be an OpenTelemetry span. Set the environment variable
   193  // GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING to the case-insensitive
   194  // value "opentelemetry" before loading the package to use OpenTelemetry tracing.
   195  // The default will remain OpenCensus until May 29, 2024, at which time the default will
   196  // switch to "opentelemetry" and explicitly setting the environment variable to
   197  // "opencensus" will be required to continue using OpenCensus tracing.
   198  func TracePrintf(ctx context.Context, attrMap map[string]interface{}, format string, args ...interface{}) {
   199  	if IsOpenTelemetryTracingEnabled() {
   200  		attrs := otAttrs(attrMap)
   201  		ottrace.SpanFromContext(ctx).AddEvent(fmt.Sprintf(format, args...), ottrace.WithAttributes(attrs...))
   202  	} else {
   203  		attrs := ocAttrs(attrMap)
   204  		// TODO: (odeke-em): perhaps just pass around spans due to the cost
   205  		// incurred from using trace.FromContext(ctx) yet we could avoid
   206  		// throwing away the work done by ctx, span := trace.StartSpan.
   207  		trace.FromContext(ctx).Annotatef(attrs, format, args...)
   208  	}
   209  }
   210  
   211  // ocAttrs converts a generic map to OpenCensus attributes.
   212  func ocAttrs(attrMap map[string]interface{}) []trace.Attribute {
   213  	var attrs []trace.Attribute
   214  	for k, v := range attrMap {
   215  		var a trace.Attribute
   216  		switch v := v.(type) {
   217  		case string:
   218  			a = trace.StringAttribute(k, v)
   219  		case bool:
   220  			a = trace.BoolAttribute(k, v)
   221  		case int:
   222  			a = trace.Int64Attribute(k, int64(v))
   223  		case int64:
   224  			a = trace.Int64Attribute(k, v)
   225  		default:
   226  			a = trace.StringAttribute(k, fmt.Sprintf("%#v", v))
   227  		}
   228  		attrs = append(attrs, a)
   229  	}
   230  	return attrs
   231  }
   232  
   233  // otAttrs converts a generic map to OpenTelemetry attributes.
   234  func otAttrs(attrMap map[string]interface{}) []attribute.KeyValue {
   235  	var attrs []attribute.KeyValue
   236  	for k, v := range attrMap {
   237  		var a attribute.KeyValue
   238  		switch v := v.(type) {
   239  		case string:
   240  			a = attribute.Key(k).String(v)
   241  		case bool:
   242  			a = attribute.Key(k).Bool(v)
   243  		case int:
   244  			a = attribute.Key(k).Int(v)
   245  		case int64:
   246  			a = attribute.Key(k).Int64(v)
   247  		default:
   248  			a = attribute.Key(k).String(fmt.Sprintf("%#v", v))
   249  		}
   250  		attrs = append(attrs, a)
   251  	}
   252  	return attrs
   253  }
   254
View as plain text