trace

README

OpenTelemetry Google Cloud Trace Exporter

OpenTelemetry Google Cloud Trace Exporter allows the user to send collected traces and spans to Google Cloud.

Google Cloud Trace is a distributed tracing backend system. It helps developers to gather timing data needed to troubleshoot latency problems in microservice & monolithic architectures. It manages both the collection and lookup of gathered trace data.

This exporter package assumes your application is already instrumented with the OpenTelemetry SDK. Once you get ready to export OpenTelemetry data, you can add this exporter to your application.

Setup

Google Cloud Trace is a managed service provided by Google Cloud Platform. The end-to-end set up guide with OpenTelemetry is available on the official GCP docs, so this document goes through the exporter set up.

Usage

Once you import the trace exporter package, create and install a new export pipeline, then you can start tracing. If you are running in a GCP environment, the exporter will automatically authenticate using the environment's service account. If not, you will need to follow the instruction in Authentication.

package main

import (
    "context"
    "log"
    "os"

    texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"

    "go.opentelemetry.io/otel"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
    // Create exporter and trace provider pipeline, and register provider.
    _, flush, err := texporter.InstallNewPipeline(
        []texporter.Option {
            // optional exporter options
        },
        // This example code uses sdktrace.AlwaysSample sampler to sample all traces.
        // In a production environment or high QPS setup please use ProbabilitySampler
        // set at the desired probability.
        // Example:
        // sdktrace.WithConfig(sdktrace.Config {
        //     DefaultSampler: sdktrace.ProbabilitySampler(0.0001),
        // })
        sdktrace.WithConfig(sdktrace.Config{
            DefaultSampler: sdktrace.AlwaysSample(),
        }),
        // other optional provider options
    )
    if err != nil {
        log.Fatalf("texporter.InstallNewPipeline: %v", err)
    }
    // before ending program, wait for all enqueued spans to be exported
    defer flush()

    // Create custom span.
    tracer := otel.TraceProvider().Tracer("example.com/trace")
    err = func(ctx context.Context) error {
        ctx, span := tracer.Start(ctx, "foo")
        defer span.End()

        // Do some work.

        return nil
    }(ctx)
}

Authentication

The Google Cloud Trace exporter depends upon google.FindDefaultCredentials, so the service account is automatically detected by default, but also the custom credential file (so called service_account_key.json) can be detected with specific conditions. Quoting from the document of google.FindDefaultCredentials:

• A JSON file whose path is specified by the GOOGLE_APPLICATION_CREDENTIALS environment variable.
• A JSON file in a location known to the gcloud command-line tool. On Windows, this is %APPDATA%/gcloud/application_default_credentials.json. On other systems, $HOME/.config/gcloud/application_default_credentials.json.

When running code locally, you may need to specify a Google Project ID in addition to GOOGLE_APPLICATION_CREDENTIALS. This is best done using an environment variable (e.g. GOOGLE_CLOUD_PROJECT) and the WithProjectID method, e.g.:

projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
_, flush, err := texporter.InstallNewPipeline(
    []texporter.Option {
        texporter.WithProjectID(projectID),
        // other optional exporter options
    },
    ...
)

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry Go, visit: https://github.com/open-telemetry/opentelemetry-go
• Learn more about Google Cloud Trace at https://cloud.google.com/trace

Documentation

Index

• Constants
• func InstallNewPipeline(opts []Option, topts ...sdktrace.TracerProviderOption) (trace.TracerProvider, func(), error)
• func NewExportPipeline(opts []Option, topts ...sdktrace.TracerProviderOption) (trace.TracerProvider, func(), error)
• func Version() string
• func WithBufferMaxBytes(bufferMaxBytes int) func(o *options)
• func WithBundleByteLimit(bundleByteLimit int) func(o *options)
• func WithBundleByteThreshold(bundleByteThreshold int) func(o *options)
• func WithBundleCountThreshold(bundleCountThreshold int) func(o *options)
• func WithBundleDelayThreshold(bundleDelayThreshold time.Duration) func(o *options)
• func WithContext(ctx context.Context) func(o *options)
• func WithDisplayNameFormatter(f DisplayNameFormatter) func(o *options)
• func WithMaxNumberOfWorkers(n int) func(o *options)
• func WithMonitoringClientOptions(opts []option.ClientOption) func(o *options)
• func WithOnError(onError func(err error)) func(o *options)
• func WithProjectID(projectID string) func(o *options)
• func WithTimeout(t time.Duration) func(o *options)
• func WithTraceClientOptions(opts []option.ClientOption) func(o *options)
• type DisplayNameFormatter
• type Exporter
  • func NewExporter(opts ...Option) (*Exporter, error)
  • func (e *Exporter) ExportSpans(ctx context.Context, spanData []*export.SpanSnapshot) error
  • func (e *Exporter) Shutdown(ctx context.Context) error
• type Option

Constants

const (

	// Attributes recorded on the span for the requests.
	// Only trace exporters will need them.
	HostAttribute       = "http.host"
	MethodAttribute     = "http.method"
	PathAttribute       = "http.path"
	URLAttribute        = "http.url"
	UserAgentAttribute  = "http.user_agent"
	StatusCodeAttribute = "http.status_code"
	ServiceAttribute    = "service.name"
)

Functions

func InstallNewPipeline

func InstallNewPipeline(opts []Option, topts ...sdktrace.TracerProviderOption) (trace.TracerProvider, func(), error)

InstallNewPipeline instantiates a NewExportPipeline and registers it globally.

func NewExportPipeline

func NewExportPipeline(opts []Option, topts ...sdktrace.TracerProviderOption) (trace.TracerProvider, func(), error)

NewExportPipeline sets up a complete export pipeline with the recommended setup for trace provider. Returns provider, flush function, and errors.

func Version

func Version() string

Version is the current release version of the OpenTelemetry Operations Trace Exporter in use.

func WithBufferMaxBytes

func WithBufferMaxBytes(bufferMaxBytes int) func(o *options)

WithBufferMaxBytes sets the maximum size (in bytes) of spans that will be buffered in memory before being dropped

func WithBundleByteLimit

func WithBundleByteLimit(bundleByteLimit int) func(o *options)

WithBundleByteLimit sets the maximum size of a bundle, in bytes. Zero means unlimited.

func WithBundleByteThreshold

func WithBundleByteThreshold(bundleByteThreshold int) func(o *options)

WithBundleByteThreshold sets the number of bytes that can be buffered before batch uploading them to the backend.

func WithBundleCountThreshold

func WithBundleCountThreshold(bundleCountThreshold int) func(o *options)

WithBundleCountThreshold sets how many trace spans can be buffered before batch uploading them to the backend.

func WithBundleDelayThreshold

func WithBundleDelayThreshold(bundleDelayThreshold time.Duration) func(o *options)

WithBundleDelayThreshold sets the max amount of time the exporter can wait before uploading trace spans to the backend.

func WithContext

func WithContext(ctx context.Context) func(o *options)

WithContext sets the context that trace exporter and metric exporter relies on.

func WithDisplayNameFormatter

func WithDisplayNameFormatter(f DisplayNameFormatter) func(o *options)

WithDisplayNameFormatter sets the way span's display names will be generated from SpanSnapshot

func WithMaxNumberOfWorkers

func WithMaxNumberOfWorkers(n int) func(o *options)

WithMaxNumberOfWorkers sets the number of go routines that send requests to the Cloud Trace backend.

func WithMonitoringClientOptions

func WithMonitoringClientOptions(opts []option.ClientOption) func(o *options)

WithMonitoringClientOptions sets additionial client options for monitoring.

func WithOnError

func WithOnError(onError func(err error)) func(o *options)

WithOnError sets the hook to be called when there is an error occurred on uploading the span data to Stackdriver. If no custom hook is set, errors are logged.

func WithProjectID

func WithProjectID(projectID string) func(o *options)

WithProjectID sets Google Cloud Platform project as projectID. Without using this option, it automatically detects the project ID from the default credential detection process. Please find the detailed order of the default credentail detection proecess on the doc: https://godoc.org/golang.org/x/oauth2/google#FindDefaultCredentials

func WithTimeout

func WithTimeout(t time.Duration) func(o *options)

WithTimeout sets the timeout for trace exporter and metric exporter

func WithTraceClientOptions

func WithTraceClientOptions(opts []option.ClientOption) func(o *options)

WithTraceClientOptions sets additionial client options for tracing.

Types

type DisplayNameFormatter

type DisplayNameFormatter func(*export.SpanSnapshot) string

DisplayNameFormatter is is a function that produces the display name of a span given its SpanSnapshot

type Exporter

type Exporter struct {
	// contains filtered or unexported fields
}

Exporter is a trace exporter that uploads data to Stackdriver.

TODO(yoshifumi): add a metrics exporter once the spec definition process and the sampler implementation are done.

func NewExporter

func NewExporter(opts ...Option) (*Exporter, error)

NewExporter creates a new Exporter thats implements trace.Exporter.

TODO(yoshifumi): add a metrics exporter one the spec definition process and the sampler implementation are done.

func (*Exporter) ExportSpans

func (e *Exporter) ExportSpans(ctx context.Context, spanData []*export.SpanSnapshot) error

ExportSpans exports a SpanSnapshot to Stackdriver Trace.

func (*Exporter) Shutdown

func (e *Exporter) Shutdown(ctx context.Context) error

Shutdown waits for exported data to be uploaded.

This is useful if your program is ending and you do not want to lose recent spans.

type Option

type Option func(*options)

Option is function type that is passed to the exporter initialization function.