otlp

package module
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 20, 2020 License: Apache-2.0 Imports: 18 Imported by: 67

README

OpenTelemetry Collector Go Exporter

PkgGoDev

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 (
	"log"

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

func main() {
	exporter, err := otlp.NewExporter() // Configure as needed.
	if err != nil {
		log.Fatalf("failed to create exporter: %v", err)
	}
	defer func() {
		err := exporter.Stop()
		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))
	pusher := push.New(simple.NewWithInexpensiveDistribution(), 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.

Example (Insecure) 
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp"

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

func main() {
	exp, err := otlp.NewExporter(otlp.WithInsecure())
	if err != nil {
		log.Fatalf("Failed to create the collector exporter: %v", err)
	}
	defer func() {
		ctx, cancel := context.WithTimeout(context.Background(), time.Second)
		defer cancel()
		if err := exp.Shutdown(ctx); err != nil {
			otel.Handle(err)
		}
	}()

	tp := sdktrace.NewTracerProvider(
		sdktrace.WithConfig(sdktrace.Config{DefaultSampler: sdktrace.AlwaysSample()}),
		sdktrace.WithBatcher(
			exp,
			// add following two options to ensure flush
			sdktrace.WithBatchTimeout(5),
			sdktrace.WithMaxExportBatchSize(10),
		),
	)
	otel.SetTracerProvider(tp)

	tracer := otel.Tracer("test-tracer")

	// Then use the OpenTelemetry tracing library, like we normally would.
	ctx, span := tracer.Start(context.Background(), "CollectorExporter-Example")
	defer span.End()

	for i := 0; i < 10; i++ {
		_, iSpan := tracer.Start(ctx, fmt.Sprintf("Sample-%d", i))
		<-time.After(6 * time.Millisecond)
		iSpan.End()
	}
}

Output:
Example (WithTLS) 
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"google.golang.org/grpc/credentials"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp"

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

func main() {
	// Please take at look at https://pkg.go.dev/google.golang.org/grpc/credentials#TransportCredentials
	// for ways on how to initialize gRPC TransportCredentials.
	creds, err := credentials.NewClientTLSFromFile("my-cert.pem", "")
	if err != nil {
		log.Fatalf("failed to create gRPC client TLS credentials: %v", err)
	}

	exp, err := otlp.NewExporter(otlp.WithTLSCredentials(creds))
	if err != nil {
		log.Fatalf("failed to create the collector exporter: %v", err)
	}
	defer func() {
		ctx, cancel := context.WithTimeout(context.Background(), time.Second)
		defer cancel()
		if err := exp.Shutdown(ctx); err != nil {
			otel.Handle(err)
		}
	}()

	tp := sdktrace.NewTracerProvider(
		sdktrace.WithConfig(sdktrace.Config{DefaultSampler: sdktrace.AlwaysSample()}),
		sdktrace.WithBatcher(
			exp,
			// add following two options to ensure flush
			sdktrace.WithBatchTimeout(5),
			sdktrace.WithMaxExportBatchSize(10),
		),
	)
	otel.SetTracerProvider(tp)

	tracer := otel.Tracer("test-tracer")

	// Then use the OpenTelemetry tracing library, like we normally would.
	ctx, span := tracer.Start(context.Background(), "Securely-Talking-To-Collector-Span")
	defer span.End()

	for i := 0; i < 10; i++ {
		_, iSpan := tracer.Start(ctx, fmt.Sprintf("Sample-%d", i))
		<-time.After(6 * time.Millisecond)
		iSpan.End()
	}
}

Output:

Index

Examples

Constants

View Source 
const (
	// DefaultCollectorPort is the port the Exporter will attempt connect to
	// if no collector port is provided.
	DefaultCollectorPort uint16 = 55680
	// DefaultCollectorHost is the host address the Exporter will attempt
	// connect to if no collector address is provided.
	DefaultCollectorHost string = "localhost"
	// DefaultGRPCServiceConfig is the gRPC service config used if none is
	// provided by the user.
	//
	// For more info on gRPC service configs:
	// https://github.com/grpc/proposal/blob/master/A6-client-retries.md
	//
	// For more info on the RetryableStatusCodes we allow here:
	// https://github.com/open-telemetry/oteps/blob/be2a3fcbaa417ebbf5845cd485d34fdf0ab4a2a4/text/0035-opentelemetry-protocol.md#export-response
	//
	// Note: MaxAttempts > 5 are treated as 5. See
	// https://github.com/grpc/proposal/blob/master/A6-client-retries.md#validation-of-retrypolicy
	// for more details.
	DefaultGRPCServiceConfig = `` /* 497-byte string literal not displayed */

)

Variables

This section is empty.

Functions

This section is empty.

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(opts ...ExporterOption) (*Exporter, error)

NewExporter constructs a new Exporter and starts it.

func NewUnstartedExporter 

func NewUnstartedExporter(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 added in v0.7.0 

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 cumulative format.

func (*Exporter) ExportSpans 

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

ExportSpans exports a batch of SpanData.

func (*Exporter) Shutdown added in v0.12.0 

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.

func (*Exporter) Start 

func (e *Exporter) Start() error

Start dials to the collector, establishing a connection to it. It also initiates the Config and Trace services by sending over the initial messages that consist of the node identifier. Start invokes a background connector that will reattempt connections to the collector periodically if the connection dies.

type ExporterOption 

type ExporterOption func(*config)

ExporterOption are setting options passed to an Exporter on creation.

func WithAddress 

func WithAddress(addr string) ExporterOption

WithAddress allows one to set the address that the exporter will connect to the collector on. If unset, it will instead try to use connect to DefaultCollectorHost:DefaultCollectorPort.

func WithCompressor 

func WithCompressor(compressor string) ExporterOption

WithCompressor will set the compressor for the gRPC client to use when sending requests. It is the responsibility of the caller to ensure that the compressor set has been registered with google.golang.org/grpc/encoding. 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"`

func WithGRPCDialOption 

func WithGRPCDialOption(opts ...grpc.DialOption) ExporterOption

WithGRPCDialOption opens support to any grpc.DialOption to be used. If it conflicts with some other configuration the GRPC specified via the collector the ones here will take preference since they are set last.

func WithGRPCServiceConfig added in v0.7.0 

func WithGRPCServiceConfig(serviceConfig string) ExporterOption

WithGRPCServiceConfig defines the default gRPC service config used.

func WithHeaders 

func WithHeaders(headers map[string]string) ExporterOption

WithHeaders will send the provided headers with gRPC requests

func WithInsecure 

func WithInsecure() ExporterOption

WithInsecure disables client transport security for the exporter's gRPC connection just like grpc.WithInsecure() https://pkg.go.dev/google.golang.org/grpc#WithInsecure does. Note, by default, client security is required unless WithInsecure is used.

func WithMetricExportKindSelector added in v0.14.0 

func WithMetricExportKindSelector(selector metricsdk.ExportKindSelector) ExporterOption

WithMetricExportKindSelector defines the ExportKindSelector used for selecting AggregationTemporality (i.e., Cumulative vs. Delta aggregation).

func WithReconnectionPeriod 

func WithReconnectionPeriod(rp time.Duration) ExporterOption

WithReconnectionPeriod allows one to set the delay between next connection attempt after failing to connect with the collector.

func WithTLSCredentials 

func WithTLSCredentials(creds credentials.TransportCredentials) ExporterOption

WithTLSCredentials allows the connection to use TLS credentials when talking to the server. It takes in grpc.TransportCredentials instead of say a Certificate file or a tls.Certificate, because the retrieving these credentials can be done in many ways e.g. plain file, in code tls.Config or by certificate rotation, so it is up to the caller to decide what to use.

Source Files

View all Source files

Directories

Path Synopsis
internal
opentelemetry-proto-gen/collector/logs/v1
opentelemetry-proto-gen/collector/metrics/v1
opentelemetry-proto-gen/collector/trace/v1
opentelemetry-proto-gen/common/v1
opentelemetry-proto-gen/logs/v1
opentelemetry-proto-gen/metrics/v1
opentelemetry-proto-gen/resource/v1
opentelemetry-proto-gen/trace/v1
transform
Package transform provides translations for opentelemetry-go concepts and structures to otlp structures.
 Package transform provides translations for opentelemetry-go concepts and structures to otlp structures.
retry Module
otlplog
otlploggrpc Module
otlploghttp Module
otlpmetric module
otlpmetricgrpc Module
otlpmetrichttp Module
otlptrace module
otlptracegrpc Module
otlptracehttp Module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.