ocagent

README

OpenCensus Agent Go Exporter

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()
	}
}

Documentation

Overview

Example

package main

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

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

func main() {
	exp, err := ocagent.NewExporter(ocagent.WithInsecure(), ocagent.WithServiceName("engine"))
	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()
	}
}

Index

• Constants
• func NodeWithStartTime(nodeName string) *commonpb.Node
• type Exporter
  • func NewExporter(opts ...ExporterOption) (*Exporter, error)
  • func NewUnstartedExporter(opts ...ExporterOption) (*Exporter, error)
  • func (ae *Exporter) ExportSpan(sd *trace.SpanData)
  • func (ae *Exporter) ExportView(vd *view.Data)
  • func (ae *Exporter) Flush()
  • func (ae *Exporter) Start() error
  • func (ae *Exporter) Stop() error
• type ExporterOption
  • func WithAddress(addr string) ExporterOption
  • func WithInsecure() ExporterOption
  • func WithReconnectionPeriod(rp time.Duration) ExporterOption
  • func WithServiceName(serviceName string) ExporterOption

Examples

• Package

Constants

const (
	DefaultAgentPort uint16 = 55678
	DefaultAgentHost string = "localhost"
)

const Version = "0.0.1"

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) ExportSpan

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

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 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 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 WithServiceName

func WithServiceName(serviceName string) ExporterOption

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