xopbase

type Builder interface {
	// Enum adds a key/value pair.  Calls to Enum are expected to be
	// sequenced with other calls to add attributes to prefill and/or
	// lines.
	Enum(*xopat.EnumAttribute, xopat.Enum)

	// Float64 adds a key/value pair.  Calls to Float64 are expected to be
	// sequenced with other calls to add attributes to prefill and/or
	// lines.
	Float64(xopat.K, float64, DataType)
	// Int64 adds a key/value pair.  Calls to Int64 are expected to be
	// sequenced with other calls to add attributes to prefill and/or
	// lines.
	Int64(xopat.K, int64, DataType)
	// String adds a key/value pair.  Calls to String are expected to be
	// sequenced with other calls to add attributes to prefill and/or
	// lines.
	String(xopat.K, string, DataType)
	// Uint64 adds a key/value pair.  Calls to Uint64 are expected to be
	// sequenced with other calls to add attributes to prefill and/or
	// lines.
	Uint64(xopat.K, uint64, DataType)

	// Any adds a key/value pair.  Calls to Any are expected to be
	// sequenced with other calls to add attributes to prefill and/or
	// lines.
	Any(xopat.K, ModelArg)
	// Bool adds a key/value pair.  Calls to Bool are expected to be
	// sequenced with other calls to add attributes to prefill and/or
	// lines.
	Bool(xopat.K, bool)
	// Duration adds a key/value pair.  Calls to Duration are expected to be
	// sequenced with other calls to add attributes to prefill and/or
	// lines.
	Duration(xopat.K, time.Duration)
	// Time adds a key/value pair.  Calls to Time are expected to be
	// sequenced with other calls to add attributes to prefill and/or
	// lines.
	Time(xopat.K, time.Time)
}

type CanReplay interface {
	// Replay is how a Logger will feed it's output to another Logger.  The
	// input param should be the collected output from the first Logger.  If
	// it isn't in the right format, it should throw an error.  This
	// capability can be used to transform from one format to another, it can
	// also be used to during testing to make sure that a Logger can round-trip
	// without data loss.  Loggers are not required to round-trip without
	// data loss.
	Replay(ctx context.Context, input []byte, logger Logger) error
}

type DataType int

type Encoder interface {
	MimeType() string
	ProducesText() bool
	Encode(elementName string, data interface{}) ([]byte, error)
}

type Line interface {
	Builder
	LineDone
}

type LineDone interface {
	Msg(string)
	Template(string)
	// Object may change in the future to also take an un-redaction string,
	Model(string, ModelArg)
	Link(string, xoptrace.Trace)
}

type Logger interface {
	// Request beings a new span that represents the start of an
	// operation: either a call to a server, a cron-job, or an event
	// being processed.  The provided Context is a pass-through from
	// the Seed and if the seed does not provide a context, the context
	// can be nil.
	Request(ctx context.Context, ts time.Time, span xoptrace.Bundle, description string, source SourceInfo) Request

	// ID returns a unique id for this instance of a logger.  This
	// is used to prevent duplicate Requests from being created when
	// additional loggers to added to an ongoing Request.
	ID() string

	// ReferencesKept should return true if Any() objects are not immediately
	// serialized (the object is kept around and serilized later).  If copies
	// are kept, then xop.Logger will make copies.
	ReferencesKept() bool

	// Buffered should return true if the logger buffers output and sends
	// it when Flush() is called. Even if Buffered() returns false,
	// Flush() may still be invoked but it doesn't have to do anything.
	Buffered() bool
}

type ModelArg struct {
	// If specified, overrides what would be provided by reflect.TypeOf(obj).Name()
	// Encoding and Encoded can be set for models that are already encoded. If they're
	// set, then Model will be ignored.
	Encoding  xopproto.Encoding `json:"encoding"`
	Encoded   []byte            `json:"v"`
	ModelType string            `json:"modelType"`
	Model     interface{}       `json:"-"`
}

type Prefilled interface {
	// Line starts another line of log output.  Span implementations
	// can expect multiple calls simultaneously and even during a call
	// to SpanInfo() or Flush().
	//
	// During replay, the stack frames may
	// only include filenames and line numbers so base loggers cannot
	// depend upon any other information being present in stack frames.
	//
	// During original log generation, the stack frame array can be
	// reused for subsequent calls to Line() with different values. The
	// value is only stable until the call returns so it must be used
	// or copied, not retained.
	Line(xopnum.Level, time.Time, []runtime.Frame) Line
}

type Prefilling interface {
	Builder

	PrefillComplete(msg string) Prefilled
}

type Request interface {
	Span

	// Flush calls are single-threaded.  Flush can be triggered explicitly by
	// users and it can be triggered because all parts of a request have had
	// Done() called on them.  Flush can be callled more than once on the same
	// request.
	Flush()

	// SetErrorReported will always be called before any other method on the
	// Request.
	//
	// If a base logger encounters an error, it may use the provided function to
	// report it.  The base logger cannot assume that execution will stop.
	// The base logger may not panic.
	SetErrorReporter(func(error))

	// Final is called when there is no possibility of any further calls to
	// this Request of any sort.  There is no guarantee that Final will be
	// called in a timely fashion or even at all before program exit.
	Final()
}

type SimpleTable interface {
	Header() []string
	Rows() [][]string
}

type SourceInfo struct {
	Source           string
	SourceVersion    *semver.Version
	Namespace        string
	NamespaceVersion *semver.Version
}

type Span interface {
	// Span creates a new Span that should inherit prefil but not data.  Calls
	// to Span can be made in parallel.
	//
	// Note: in the Bundle, the only fields that are expected to be set are
	// span.Trace.SpanID and span.Parent.SpanID. The Bundle type was used for
	// convenience.
	Span(ctx context.Context, ts time.Time, span xoptrace.Bundle, descriptionOrName string, spanSequenceCode string) Span

	// MetadataAny adds a key/value pair to describe the span.  Calls to
	// MetadataAny are can be concurrent with other calls to set Metadata.
	MetadataAny(*xopat.AnyAttribute, ModelArg)
	// MetadataBool adds a key/value pair to describe the span.  Calls to
	// MetadataBool are can be concurrent with other calls to set Metadata.
	MetadataBool(*xopat.BoolAttribute, bool)
	// MetadataEnum adds a key/value pair to describe the span.  Calls to
	// MetadataEnum are can be concurrent with other calls to set Metadata.
	MetadataEnum(*xopat.EnumAttribute, xopat.Enum)
	// MetadataFloat64 adds a key/value pair to describe the span.  Calls to
	// MetadataFloat64 are can be concurrent with other calls to set Metadata.
	MetadataFloat64(*xopat.Float64Attribute, float64)
	// MetadataLink adds a key/value pair to describe the span.  Calls to
	// MetadataLink are can be concurrent with other calls to set Metadata.
	MetadataLink(*xopat.LinkAttribute, xoptrace.Trace)
	// MetadataString adds a key/value pair to describe the span.  Calls to
	// MetadataString are can be concurrent with other calls to set Metadata.
	MetadataString(*xopat.StringAttribute, string)
	// MetadataTime adds a key/value pair to describe the span.  Calls to
	// MetadataTime are can be concurrent with other calls to set Metadata.
	MetadataTime(*xopat.TimeAttribute, time.Time)

	// MetadataInt64 adds a key/value pair to describe the span.  Calls to
	// MetadataInt64 are can be concurrent with other calls to set Metadata.
	// MetadataInt64 is used for Int64, Int, Int8, Int16, Int32, and time.Duration
	// metadata recording.
	MetadataInt64(*xopat.Int64Attribute, int64)

	// Boring true indicates that a span (or request) is boring.  The
	// suggested meaning for this is that a boring request that is buffered
	// can ignore Flush() and never get sent to output.  A boring span
	// can be un-indexed. Boring requests that do get sent to output can
	// be marked as boring so that they're dropped at the indexing stage.
	//
	// Calls to Boring are single-threaded with respect to other calls to
	// Boring.  NOT YET IMPLEMENTED.
	Boring(bool)

	// ID must return the same string as the Logger it came from
	ID() string

	// NoPrefill must work in parallel with other calls to NoPrefill, Span,
	// and StartPrefill.
	NoPrefill() Prefilled

	// StartPrefill must work in parallel with other calls to NoPrefill, Span,
	// and StartPrefill.
	StartPrefill() Prefilling

	// Done is called when (1) log.Done is called on the log corresponding
	// to this span; (2) log.Done is called on a parent log of the log
	// corresponding to this span, and the log is not Detach()ed; or
	// (3) preceding Flush() if there has been logging activity since the
	// last call to Flush(), Done(), or the start of the span.
	//
	// final is true when the log is done, it is false when Done is called
	// prior to a Flush().  Just because Done was called with final does not
	// mean that Done won't be called again.  Any further calls would only
	// happen due a bug in the application: logging things after calling
	// log.Done.
	//
	// If the application never calls log.Done(), then final will never
	// be true.
	//
	// Done can be called in parallel to calls to Done on other Spans
	// and other activity including Flush(). There is no particular order
	// to the calls to Done().
	Done(endTime time.Time, final bool)
}