trace.go

package tracing

import "github.com/DistributedClocks/GoVector/govec"

// Trace is a set of recorded actions that are associated with a unique trace ID.
// You must now first get access to a trace and then you can record an action
// (Trace.RecordAction(action)).
// There are two ways in which your code can get access to a trace instance:
// (1) create a new trace with a unique ID. In this case you should use
//     tracer.CreateTrace()
// (2) receive an existing trace from another node. In this case you should
//     use tracer.ReceiveToken(token), which token is generated by a previous
//     trace.GenerateToken() call.
type Trace struct {
	ID     uint64
	Tracer *Tracer
}

// RecordAction ensures that the record is recorded by the tracing server,
// and optionally logs the record's contents. record can be any struct value;
// its contents will be extracted via reflection.
// RecordAction implementation is thread-safe.
//
// For example, consider (with tracer id "id"):
// 	struct MyRecord { Foo string; Bar string }
// and the call:
// 	RecordAction(MyRecord{ Foo: "foo", Bar: "bar" })
//
// This will result in a log (and relevant tracing data) that contains the following:
//  [TracerID] TraceID=ID MyRecord Foo="foo", Bar="bar"
func (trace *Trace) RecordAction(record interface{}) {
	trace.Tracer.lock.Lock()
	defer trace.Tracer.lock.Unlock()

	trace.Tracer.recordAction(trace, record, true)
}

// PrepareTokenTrace is an action that indicates start of generating a tracing
// token.
type PrepareTokenTrace struct{}

// GenerateTokenTrace is an action that indicates generation of a tracing token.
type GenerateTokenTrace struct {
	Token TracingToken // the generated tracing token
}

// GenerateToken produces a fresh TracingToken, and records the event via RecordAction.
// This allows analysis of the resulting trace to correlate token generation
// and token reception.
func (trace *Trace) GenerateToken() TracingToken {
	trace.Tracer.lock.Lock()
	defer trace.Tracer.lock.Unlock()

	token := trace.Tracer.logger.PrepareSend(trace.Tracer.getLogString(trace, PrepareTokenTrace{}),
		trace.ID, govec.GetDefaultLogOptions())
	trace.Tracer.recordAction(trace, GenerateTokenTrace{Token: token}, false)
	return token
}