stdout

Documentation

Overview

Package stdout contains an OpenTelemetry exporter for both tracing and metric telemetry to be written to an output destination as JSON.

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

package main

import (
	"context"
	"log"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/exporters/stdout"
	"go.opentelemetry.io/otel/metric"
	"go.opentelemetry.io/otel/metric/global"
	"go.opentelemetry.io/otel/trace"
)

const (
	instrumentationName    = "github.com/instrumentron"
	instrumentationVersion = "v0.1.0"
)

var (
	tracer = otel.GetTracerProvider().Tracer(
		instrumentationName,
		trace.WithInstrumentationVersion(instrumentationVersion),
	)

	meter = global.GetMeterProvider().Meter(
		instrumentationName,
		metric.WithInstrumentationVersion(instrumentationVersion),
	)

	loopCounter = metric.Must(meter).NewInt64Counter("function.loops")
	paramValue  = metric.Must(meter).NewInt64ValueRecorder("function.param")

	nameKey = attribute.Key("function.name")
)

func add(ctx context.Context, x, y int64) int64 {
	nameKV := nameKey.String("add")

	var span trace.Span
	ctx, span = tracer.Start(ctx, "Addition")
	defer span.End()

	loopCounter.Add(ctx, 1, nameKV)
	paramValue.Record(ctx, x, nameKV)
	paramValue.Record(ctx, y, nameKV)

	return x + y
}

func multiply(ctx context.Context, x, y int64) int64 {
	nameKV := nameKey.String("multiply")

	var span trace.Span
	ctx, span = tracer.Start(ctx, "Multiplication")
	defer span.End()

	loopCounter.Add(ctx, 1, nameKV)
	paramValue.Record(ctx, x, nameKV)
	paramValue.Record(ctx, y, nameKV)

	return x * y
}

func main() {
	exportOpts := []stdout.Option{
		stdout.WithPrettyPrint(),
	}
	// Registers both a trace and meter Provider globally.
	tracerProvider, pusher, err := stdout.InstallNewPipeline(exportOpts, nil)
	if err != nil {
		log.Fatal("Could not initialize stdout exporter:", err)
	}
	ctx := context.Background()

	log.Println("the answer is", add(ctx, multiply(ctx, multiply(ctx, 2, 2), 10), 2))

	if err := pusher.Stop(ctx); err != nil {
		log.Fatal("Could not stop stdout exporter:", err)
	}
	if err := tracerProvider.Shutdown(ctx); err != nil {
		log.Fatal("Could not stop stdout tracer:", err)
	}
}

Index

• func InstallNewPipeline(exportOpts []Option, pushOpts []controller.Option) (*sdktrace.TracerProvider, *controller.Controller, error)
• func NewExportPipeline(exportOpts []Option, pushOpts []controller.Option) (*sdktrace.TracerProvider, *controller.Controller, error)
• type Config
  • func NewConfig(options ...Option) (Config, error)
• type Exporter
  • func NewExporter(options ...Option) (*Exporter, error)
  • func (e *Exporter) Export(_ context.Context, checkpointSet exportmetric.CheckpointSet) error
  • func (e *Exporter) ExportKindFor(desc *metric.Descriptor, kind aggregation.Kind) exportmetric.ExportKind
  • func (e *Exporter) ExportSpans(ctx context.Context, ss []*trace.SpanSnapshot) error
  • func (e *Exporter) Shutdown(ctx context.Context) error
• type Option
  • func WithLabelEncoder(enc attribute.Encoder) Option
  • func WithPrettyPrint() Option
  • func WithWriter(w io.Writer) Option
  • func WithoutMetricExport() Option
  • func WithoutTimestamps() Option
  • func WithoutTraceExport() Option

Examples

• Package

Functions

func InstallNewPipeline

func InstallNewPipeline(exportOpts []Option, pushOpts []controller.Option) (*sdktrace.TracerProvider, *controller.Controller, error)

InstallNewPipeline creates a complete export pipelines with defaults and registers it globally. It is the responsibility of the caller to stop the returned tracer provider and push Controller.

Typically this is called as:

pipeline, err := stdout.InstallNewPipeline(stdout.Config{...})
if err != nil {
	...
}
defer pipeline.Stop()
... Done

func NewExportPipeline

func NewExportPipeline(exportOpts []Option, pushOpts []controller.Option) (*sdktrace.TracerProvider, *controller.Controller, error)

NewExportPipeline creates a complete export pipeline with the default selectors, processors, and trace registration. It is the responsibility of the caller to stop the returned tracer provider and push Controller.

Types

type Config

type Config struct {
	// Writer is the destination.  If not set, os.Stdout is used.
	Writer io.Writer

	// PrettyPrint will encode the output into readable JSON. Default is
	// false.
	PrettyPrint bool

	// Timestamps specifies if timestamps should be pritted. Default is
	// true.
	Timestamps bool

	// LabelEncoder encodes the labels.
	LabelEncoder attribute.Encoder

	// DisableTraceExport prevents any export of trace telemetry.
	DisableTraceExport bool

	// DisableMetricExport prevents any export of metric telemetry.
	DisableMetricExport bool
}

Config contains options for the STDOUT exporter.

func NewConfig

func NewConfig(options ...Option) (Config, error)

NewConfig creates a validated Config configured with options.

type Exporter

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

func NewExporter

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

NewExporter creates an Exporter with the passed options.

func (*Exporter) Export

func (e *Exporter) Export(_ context.Context, checkpointSet exportmetric.CheckpointSet) error

func (*Exporter) ExportKindFor

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

func (*Exporter) ExportSpans

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

ExportSpans writes SpanSnapshots in json format to stdout.

func (*Exporter) Shutdown

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

Shutdown is called to stop the exporter, it preforms no action.

type Option

type Option interface {
	// Apply option value to Config.
	Apply(*Config)
	// contains filtered or unexported methods
}

Option sets the value of an option for a Config.

func WithLabelEncoder

func WithLabelEncoder(enc attribute.Encoder) Option

WithLabelEncoder sets the label encoder used in export.

func WithPrettyPrint

func WithPrettyPrint() Option

WithPrettyPrint sets the export stream format to use JSON.

func WithWriter

func WithWriter(w io.Writer) Option

WithWriter sets the export stream destination.

func WithoutMetricExport

func WithoutMetricExport() Option

WithoutMetricExport disables all metric exporting.

func WithoutTimestamps

func WithoutTimestamps() Option

WithoutTimestamps sets the export stream to not include timestamps.

func WithoutTraceExport

func WithoutTraceExport() Option

WithoutTraceExport disables all trace exporting.