README

OpenCensus Agent Go Exporter

Build Status GoDoc

This repository contains the Go implementation of the OpenCensus Agent (OC-Agent) Exporter. OC-Agent is a deamon process running in a VM that can retrieve spans/stats/metrics from OpenCensus Library, export them to other backends and possibly push configurations back to Library. See more details on OC-Agent Readme.

Note: This is an experimental repository and is likely to get backwards-incompatible changes. Ultimately we may want to move the OC-Agent Go Exporter to OpenCensus Go core library.

Installation

$ go get -u contrib.go.opencensus.io/exporter/ocagent

Usage

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

	"contrib.go.opencensus.io/exporter/ocagent"
	"go.opencensus.io/trace"
)

func Example() {
	exp, err := ocagent.NewExporter(ocagent.WithInsecure(), ocagent.WithServiceName("your-service-name"))
	if err != nil {
		log.Fatalf("Failed to create the agent exporter: %v", err)
	}
	defer exp.Stop()

	// Now register it as a trace exporter.
	trace.RegisterExporter(exp)

	// Then use the OpenCensus tracing library, like we normally would.
	ctx, span := trace.StartSpan(context.Background(), "AgentExporter-Example")
	defer span.End()

	for i := 0; i < 10; i++ {
		_, iSpan := trace.StartSpan(ctx, fmt.Sprintf("Sample-%d", i))
		<-time.After(6 * time.Millisecond)
		iSpan.End()
	}
}
Expand ▾ Collapse ▴

Documentation

Overview

Example (Insecure)
Output:

Example (WithTLS)
Output:

Index

Examples

Constants

View Source
const (
	DefaultAgentPort uint16 = 55678
	DefaultAgentHost string = "localhost"
)
View Source
const Version = "0.0.1"

Variables

This section is empty.

Functions

func NodeWithStartTime

func NodeWithStartTime(nodeName string) *commonpb.Node

    NodeWithStartTime creates a node using nodeName and derives:

    Hostname from the environment
    Pid from the current process
    StartTimestamp from the start time of this process
    Language and library information.
    

    Types

    type Exporter

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

    func NewExporter

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

    func NewUnstartedExporter

    func NewUnstartedExporter(opts ...ExporterOption) (*Exporter, error)

    func (*Exporter) ExportMetricsServiceRequest

    func (ae *Exporter) ExportMetricsServiceRequest(batch *agentmetricspb.ExportMetricsServiceRequest) error

      ExportMetricsServiceRequest sends proto metrics with the metrics service client.

      func (*Exporter) ExportSpan

      func (ae *Exporter) ExportSpan(sd *trace.SpanData)

      func (*Exporter) ExportTraceServiceRequest

      func (ae *Exporter) ExportTraceServiceRequest(batch *agenttracepb.ExportTraceServiceRequest) error

      func (*Exporter) ExportView

      func (ae *Exporter) ExportView(vd *view.Data)

      func (*Exporter) Flush

      func (ae *Exporter) Flush()

      func (*Exporter) Start

      func (ae *Exporter) Start() error

        Start dials to the agent, 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 agent periodically if the connection dies.

        func (*Exporter) Stop

        func (ae *Exporter) Stop() error

          Stop shuts down all the connections and resources related to the exporter.

          type ExporterOption

          type ExporterOption interface {
          	// contains filtered or unexported methods
          }

          func UseCompressor

          func UseCompressor(compressorName string) ExporterOption

            UseCompressor 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 WithAddress

            func WithAddress(addr string) ExporterOption

              WithAddress allows one to set the address that the exporter will connect to the agent on. If unset, it will instead try to use connect to DefaultAgentHost:DefaultAgentPort

              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 agent the ones here will take preference since they are set last.

                func WithHeaders

                func WithHeaders(headers map[string]string) ExporterOption

                  WithHeaders will send the provided headers when the gRPC stream connection is instantiated

                  func WithInsecure

                  func WithInsecure() ExporterOption

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

                    func WithReconnectionPeriod

                    func WithReconnectionPeriod(rp time.Duration) ExporterOption

                    func WithResourceDetector

                    func WithResourceDetector(rd resource.Detector) ExporterOption

                      WithResourceDetector allows one to register a resource detector. Resource Detector is used to detect resources associated with the application. Detected resource is exported along with the metrics. If the detector fails then it panics. If a resource detector is not provided then by default it detects from the environment.

                      func WithServiceName

                      func WithServiceName(serviceName string) ExporterOption

                        WithServiceName allows one to set/override the service name that the exporter will report to the agent.

                        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.

                          Directories

                          Path Synopsis