otlp

README

OpenTelemetry Collector Go Exporter

This exporter exports OpenTelemetry spans and metrics to the OpenTelemetry Collector.

Installation and Setup

The exporter can be installed using standard go functionality.

$ go get -u go.opentelemetry.io/otel/exporters/otlp

A new exporter can be created using the NewExporter function.

package main

import (
	"context"
	"log"

	"go.opentelemetry.io/otel/sdk/metric/controller/push"
	"go.opentelemetry.io/otel/exporters/otlp"
	processor "go.opentelemetry.io/otel/sdk/metric/processor/basic"
	"go.opentelemetry.io/otel/sdk/metric/selector/simple"
	metricsdk "go.opentelemetry.io/otel/sdk/export/metric"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
	ctx := context.Background()
	exporter, err := otlp.NewExporter(ctx) // Configure as needed.
	if err != nil {
		log.Fatalf("failed to create exporter: %v", err)
	}
	defer func() {
		err := exporter.Shutdown(ctx)
		if err != nil {
			log.Fatalf("failed to stop exporter: %v", err)
		}
	}()

	// Note: The exporter can also be used as a Batcher. E.g.
	//   tracerProvider := sdktrace.NewTracerProvider(
	//   	sdktrace.WithBatcher(exporter,
	//   		sdktrace.WithBatchTimeout(time.Second*15),
	//   		sdktrace.WithMaxExportBatchSize(100),
	//   	),
	//   )
	tracerProvider := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
	processor := processor.New(simple.NewWithInexpensiveDistribution(), metricsdk.StatelessExportKindSelector())
	pusher := push.New(processor, exporter)
	pusher.Start()
	metricProvider := pusher.MeterProvider()

	// Your code here ...
}

Configuration

Configurations options can be specified when creating a new exporter (NewExporter).

WorkerCount(n uint)

Sets the number of Goroutines to use when processing telemetry.

WithInsecure()

Disables client transport security for the exporter's gRPC connection just like grpc.WithInsecure() does. By default, client security is required unless WithInsecure is used.

WithAddress(addr string)

Sets the address that the exporter will connect to the collector on. The default address the exporter connects to is localhost:55680.

WithReconnectionPeriod(rp time.Duration)

Set the delay between connection attempts after failing to connect with the collector.

WithCompressor(compressor string)

Set the compressor for the gRPC client to use when sending requests. The compressor used needs to have been registered with google.golang.org/grpc/encoding prior to using here. This can be done by encoding.RegisterCompressor. Some compressors auto-register on import, such as gzip, which can be registered by calling import _ "google.golang.org/grpc/encoding/gzip".

WithHeaders(headers map[string]string)

Headers to send with gRPC requests.

WithTLSCredentials(creds "google.golang.org/grpc/credentials".TransportCredentials)

TLS credentials to use when talking to the server.

WithGRPCServiceConfig(serviceConfig string)

The default gRPC service config used when .

By default, the exporter is configured to support retries.

{
	"methodConfig":[{
		"name":[
			{ "service":"opentelemetry.proto.collector.metrics.v1.MetricsService" },
			{ "service":"opentelemetry.proto.collector.trace.v1.TraceService" }
		],
		"waitForReady": true,
		"retryPolicy":{
			"MaxAttempts":5,
			"InitialBackoff":"0.3s",
			"MaxBackoff":"5s",
			"BackoffMultiplier":2,
			"RetryableStatusCodes":[
				"UNAVAILABLE",
				"CANCELLED",
				"DEADLINE_EXCEEDED",
				"RESOURCE_EXHAUSTED",
				"ABORTED",
				"OUT_OF_RANGE",
				"UNAVAILABLE",
				"DATA_LOSS"
			]
		}
	}]
}

WithGRPCDialOption(opts ..."google.golang.org/grpc".DialOption)

Additional grpc.DialOption to be used.

These options take precedence over any other set by other parts of the configuration.

Retries

The exporter will not, by default, retry failed requests to the collector. However, it is configured in a way that it can easily be enable.

To enable retries, the GRPC_GO_RETRY environment variable needs to be set to on. For example,

GRPC_GO_RETRY=on go run .

The default service config used by default is defined to retry failed requests with exponential backoff (0.3seconds * (2)^retry) with a max of 5 retries).

These retries are only attempted for reponses that are deemed "retry-able" by the collector.

Documentation

Overview

Package otlp contains an exporter for the OpenTelemetry protocol buffers.

This package is currently in a pre-GA phase. Backwards incompatible changes may be introduced in subsequent minor version releases as we work to track the evolving OpenTelemetry specification and user feedback.

Index

• Constants
• type Exporter
  • func NewExporter(ctx context.Context, driver ProtocolDriver, opts ...ExporterOption) (*Exporter, error)
  • func NewUnstartedExporter(driver ProtocolDriver, opts ...ExporterOption) *Exporter
  • func (e *Exporter) Export(parent context.Context, cps metricsdk.CheckpointSet) error
  • func (e *Exporter) ExportKindFor(desc *metric.Descriptor, kind aggregation.Kind) metricsdk.ExportKind
  • func (e *Exporter) ExportSpans(ctx context.Context, ss []*tracesdk.SpanSnapshot) error
  • func (e *Exporter) Shutdown(ctx context.Context) error
  • func (e *Exporter) Start(ctx context.Context) error
• type ExporterOption
  • func WithMetricExportKindSelector(selector metricsdk.ExportKindSelector) ExporterOption
• type ProtocolDriver
  • func NewSplitDriver(cfg SplitConfig) ProtocolDriver
• type SplitConfig

Constants

const (
	// DefaultCollectorPort is the port the Exporter will attempt connect to
	// if no collector port is provided.
	DefaultCollectorPort uint16 = 4317
	// DefaultCollectorHost is the host address the Exporter will attempt
	// connect to if no collector address is provided.
	DefaultCollectorHost string = "localhost"
)

Types

type Exporter

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

Exporter is an OpenTelemetry exporter. It exports both traces and metrics from OpenTelemetry instrumented to code using OpenTelemetry protocol buffers to a configurable receiver.

func NewExporter

func NewExporter(ctx context.Context, driver ProtocolDriver, opts ...ExporterOption) (*Exporter, error)

NewExporter constructs a new Exporter and starts it.

func NewUnstartedExporter

func NewUnstartedExporter(driver ProtocolDriver, opts ...ExporterOption) *Exporter

NewUnstartedExporter constructs a new Exporter and does not start it.

func (*Exporter) Export

func (e *Exporter) Export(parent context.Context, cps metricsdk.CheckpointSet) error

Export implements the "go.opentelemetry.io/otel/sdk/export/metric".Exporter interface. It transforms and batches metric Records into OTLP Metrics and transmits them to the configured collector.

func (*Exporter) ExportKindFor

func (e *Exporter) ExportKindFor(desc *metric.Descriptor, kind aggregation.Kind) metricsdk.ExportKind

ExportKindFor reports back to the OpenTelemetry SDK sending this Exporter metric telemetry that it needs to be provided in a configured format.

func (*Exporter) ExportSpans

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

ExportSpans implements the "go.opentelemetry.io/otel/sdk/export/trace".SpanExporter interface. It transforms and batches trace SpanSnapshots into OTLP Trace and transmits them to the configured collector.

func (*Exporter) Shutdown

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

Shutdown closes all connections and releases resources currently being used by the exporter. If the exporter is not started this does nothing. A shut down exporter can't be started again. Shutting down an already shut down exporter does nothing.

func (*Exporter) Start

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

Start establishes connections to the OpenTelemetry collector. Starting an already started exporter returns an error.

type ExporterOption

type ExporterOption func(*config)

ExporterOption are setting options passed to an Exporter on creation.

func WithMetricExportKindSelector

func WithMetricExportKindSelector(selector metricsdk.ExportKindSelector) ExporterOption

WithMetricExportKindSelector defines the ExportKindSelector used for selecting AggregationTemporality (i.e., Cumulative vs. Delta aggregation). If not specified otherwise, exporter will use a cumulative export kind selector.

type ProtocolDriver

type ProtocolDriver interface {
	// Start should establish connection(s) to endpoint(s). It is
	// called just once by the exporter, so the implementation
	// does not need to worry about idempotence and locking.
	Start(ctx context.Context) error
	// Stop should close the connections. The function is called
	// only once by the exporter, so the implementation does not
	// need to worry about idempotence, but it may be called
	// concurrently with ExportMetrics or ExportTraces, so proper
	// locking is required. The function serves as a
	// synchronization point - after the function returns, the
	// process of closing connections is assumed to be finished.
	Stop(ctx context.Context) error
	// ExportMetrics should transform the passed metrics to the
	// wire format and send it to the collector. May be called
	// concurrently with ExportTraces, so the manager needs to
	// take this into account by doing proper locking.
	ExportMetrics(ctx context.Context, cps metricsdk.CheckpointSet, selector metricsdk.ExportKindSelector) error
	// ExportTraces should transform the passed traces to the wire
	// format and send it to the collector. May be called
	// concurrently with ExportMetrics, so the manager needs to
	// take this into account by doing proper locking.
	ExportTraces(ctx context.Context, ss []*tracesdk.SpanSnapshot) error
}

ProtocolDriver is an interface used by OTLP exporter. It's responsible for connecting to and disconnecting from the collector, and for transforming traces and metrics into wire format and transmitting them to the collector.

func NewSplitDriver

func NewSplitDriver(cfg SplitConfig) ProtocolDriver

NewSplitDriver creates a protocol driver which contains two other protocol drivers and will forward traces to one of them and metrics to another.

type SplitConfig

type SplitConfig struct {
	// ForMetrics driver will be used for sending metrics to the
	// collector.
	ForMetrics ProtocolDriver
	// ForTraces driver will be used for sending spans to the
	// collector.
	ForTraces ProtocolDriver
}

SplitConfig is used to configure a split driver.