README
¶
OpenTelemetry Google Cloud Trace Propagators
This package contains Trace Context Propagators for use with Google Cloud Trace that make it compatible with OpenTelemetry.
To get started with instrumentation in Google Cloud, see Generate traces and metrics with Go.
To learn more about instrumentation and observability, including opinionated recommendations for Google Cloud Observability, visit Instrumentation and observability.
There are two available propagators in this package:
CloudTraceOneWayPropagator (Recommended)
The CloudTraceOneWayPropagator reads the X-Cloud-Trace-Context header for trace and
span IDs, but does not write the X-Cloud-Trace-Context header into outgoing
requests.
This is useful for ensuring spans created in your code are attached to the traces that some Google Cloud services automatically trace.
Usage
import (
"go.opentelemetry.io/otel/propagation"
gcppropagator "github.com/GoogleCloudPlatform/opentelemetry-operations-go/propagator"
)
func installPropagators() {
otel.SetTextMapPropagator(
propagation.NewCompositeTextMapPropagator(
// Putting the CloudTraceOneWayPropagator first means the TraceContext propagator
// takes precedence if both the traceparent and the XCTC headers exist.
gcppropagator.CloudTraceOneWayPropagator{},
propagation.TraceContext{},
propagation.Baggage{},
))
}
CloudTraceFormatPropagator
The standard propagator reads and writes the X-Cloud-Trace-Context header.
Note that because of differences between the meaning of the sampled flag
(described below), this can result in 100% tracing when the parent context
has a deferred tracing decision.
Usage
import (
"go.opentelemetry.io/otel/propagation"
gcppropagator "github.com/GoogleCloudPlatform/opentelemetry-operations-go/propagator"
)
func installPropagators() {
otel.SetTextMapPropagator(
propagation.NewCompositeTextMapPropagator(
// Putting the CloudTraceFormatPropagator first means the TraceContext propagator
// takes precedence if both the traceparent and the XCTC headers exist.
gcppropagator.CloudTraceFormatPropagator{},
propagation.TraceContext{},
propagation.Baggage{},
))
}
Differences between Google Cloud Trace and W3C Trace Context
Google Cloud Trace encodes trace information in the X-Cloud-Trace-Context HTTP
header, using the format described in the Trace documentation.
OpenTelemetry uses the newer, W3C standard
traceparent header
There is an important semantic difference between Cloud Trace's
TRACE_TRUE flag, and W3C's sampled flag.
As outlined in the Trace
documentation, setting
the TRACE_TRUE flag will cause trace information to be collected.
This differs from the W3C behavior, where the sampled
flag indicates that the
caller may have recorded trace information, but does not necessarily impact
the sampling done by other services.
To preserve the Cloud-Trace behavior when using traceparent, you can use the
ParentBased
sampler like
so:
import sdktrace go.opentelemetry.io/otel/sdk/trace
sampler := sdktrace.ParentBased(
sdktrace.NeverSample(),
sdktrace.WithRemoteParentSampled(sdktrace.AlwaysSample()))
)
Documentation
¶
Index ¶
Constants ¶
const TraceContextHeaderName = "x-cloud-trace-context"
TraceContextHeaderName is the HTTP header field for Google Cloud Trace https://cloud.google.com/trace/docs/setup#force-trace
Variables ¶
This section is empty.
Functions ¶
func SpanContextFromRequest ¶
func SpanContextFromRequest(req *http.Request) (trace.SpanContext, error)
SpanContextFromRequest extracts a trace.SpanContext from the HTTP request req. In this method, SpanID is expected to be stored in big endian.
Types ¶
type CloudTraceFormatPropagator ¶
type CloudTraceFormatPropagator struct{}
CloudTraceFormatPropagator is a TextMapPropagator that injects/extracts a context to/from the carrier following Google Cloud Trace format.
func (CloudTraceFormatPropagator) Extract ¶
func (p CloudTraceFormatPropagator) Extract(ctx context.Context, carrier propagation.TextMapCarrier) context.Context
Extract extacts a context from the carrier if the header contains Google Cloud Trace header format. In this method, SpanID is expected to be stored in big endian.
func (CloudTraceFormatPropagator) Fields ¶
func (p CloudTraceFormatPropagator) Fields() []string
Fields just returns the header name.
func (CloudTraceFormatPropagator) Inject ¶
func (p CloudTraceFormatPropagator) Inject(ctx context.Context, carrier propagation.TextMapCarrier)
Inject injects a context to the carrier following Google Cloud Trace format. In this method, SpanID is expected to be stored in big endian.
type CloudTraceOneWayPropagator ¶
type CloudTraceOneWayPropagator struct {
CloudTraceFormatPropagator
}
CloudTraceOneWayPropagator will propagate trace context from the w3c standard headers (traceparent and tracestate). If traceparent is not present, it will extract trace context from x-cloud-trace-context, and propagate that trace context forward using the w3c standard headers.
This is the preferred mechanism of propagation as X-Cloud-Trace-Context sampling flag behaves subtly different from expectations in both w3c traceparent *and* opentelemetry propagation.
func (CloudTraceOneWayPropagator) Fields ¶
func (p CloudTraceOneWayPropagator) Fields() []string
Fields returns an empty list of fields, since the one way propagator does not inject any fields.
func (CloudTraceOneWayPropagator) Inject ¶
func (p CloudTraceOneWayPropagator) Inject(ctx context.Context, carrier propagation.TextMapCarrier)
Inject does not inject anything for the oneway propagator.
Source Files