Jaeger Agent Refactor Design

design.md

Introduction

This document represents the plan for refactoring the Jaeger Agent to support different Reporters. The use case is identified by Issue 927.

Jaeger Workflow:

Instrumented App > Jaeger Client Library >---(SPANs)---> Agent > Collector > Storage (ES, Cassandra)

jaeger-agent is a daemon program which runs on every host and receives tracing data submitted by Jaeger client libraries. The daemon performs the following upon startup:

• Creates the jaeger-agent command (Cobra).
• Loads the config (Viper), parses cmd flags.
• Initializes logging (Zap).
• Initializes a Builder, from a Viper config. Builder holds the overall config of the agent. Builder creates the agent.
• Starts the agent (http/udp servers, one or more Processors).

Agent Workflow:

Builder > Agent Config (Overall config for each sub component, i.e. Processor, etc.)
Metrics > Metric Backend (Prometheus)
Processors (UDP|HTTP) > Reporter

It appears the Builder needs to be refactored/extended to support different Reporter backends (tchan, grpc, etc.).

Builder holds configurations for:

• Processors: Holds config for a processor that receives spans from Server
• HTTPServer: Holds config for a server providing sampling strategies and baggage restrictions to clients
• Metrics: Provides command line options to configure metrics backend used by Jaeger executables.
• tchreporter.Builder: Holds tch-specific configs (CollectorHostPorts, DiscoveryMinPeers, CollectorServiceName, ConnCheckTimeout).
• otherReporters: Reporter handles spans received by Processor and forwards them to central collectors.
• metricsFactory: Creates new metrics (Counter, Timer, Guage, Namespace)

Agent Code Current State

Agent code lives at jaeger/cmd/agent/.

Agent is a composition of all Agent subcomponents:

type Agent struct {
	processors []processors.Processor
	httpServer *http.Server
	httpAddr   atomic.Value // string, set once agent starts listening
	logger     *zap.Logger
	closer     io.Closer
}

CreateAgent operates on a Builder pointer receiver, takes a logger and returns a pointer of type Agent (above) or an error if Agent can not be created.

Reporter handles spans received by Processor and forwards them to central Collectors.

type Reporter interface {
	EmitZipkinBatch(spans []*zipkincore.Span) (err error)
	EmitBatch(batch *jaeger.Batch) (err error)
}

Agent Code Future State

• Update agent/flags pkg to pass in Reporter config. Approrpriate reporter should be instantiated based on reporters field in config file:

reporters:
    - kind: tchannel
      # tchannel-specific parameters, e.g.
      collector:
        hostPort: ...
      discovery:
        minPeers: 10
    - kind: grpc
      # grpc-specific parameters

• Update Builder struct to include []*reports.ReporterConfig
• Remove embedding tchreporter.Builder in Builder struct. Implementation-specific builders should be

Update pkg reporter to reporters and all associated references.

Update Agent struct to include a slice of type Reporter :

type Agent struct {
	processors []processors.Processor
	reporters  []reporters.Reporter
  httpServer *http.Server
	httpAddr   atomic.Value // string, set once agent starts listening
	logger     *zap.Logger
	closer     io.Closer
}

Create defaultReporters var in cmd/agent/app/flags.go:

var defaultReporters = []struct {
	kind      string
	TBD
}{
	{kind: "zipkin", TBD: "TBD"},
	{kind: "jaeger", TBD: "TBD"},
}

ReporterConfiguration holds the configuration for a Reporter.

type ReporterConfiguration struct {
	Kind      string              `yaml:"kind"`
	Collector Collector           `yaml:"collector"`
	Discovery Discovery           `yaml:"discovery"`
}