propagator

README

OpenTelemetry Google Cloud Trace Propagators

This package contains Trace Context Propagators for use with Google Cloud Trace that make it compatible with OpenTelemetry.

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
• func SpanContextFromRequest(req *http.Request) (trace.SpanContext, error)
• type CloudTraceFormatPropagator
  • func (p CloudTraceFormatPropagator) Extract(ctx context.Context, carrier propagation.TextMapCarrier) context.Context
  • func (p CloudTraceFormatPropagator) Fields() []string
  • func (p CloudTraceFormatPropagator) Inject(ctx context.Context, carrier propagation.TextMapCarrier)
• type CloudTraceOneWayPropagator
  • func (p CloudTraceOneWayPropagator) Fields() []string
  • func (p CloudTraceOneWayPropagator) Inject(ctx context.Context, carrier propagation.TextMapCarrier)

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

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.