okit/client.go

// Copyright (C) 2022 The OKit Authors
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
// OR OTHER DEALINGS IN THE SOFTWARE.

package okit

import (
	"context"
	"crypto/rand"
	"encoding/base32"
	"io"
	"runtime"
	"sync"
	"time"

	"go.pitz.tech/okit/observer"
	"go.pitz.tech/okit/pb"
)

var (
	encoding = base32.StdEncoding.WithPadding(base32.NoPadding)

	defaultUUID = func() string {
		buf := make([]byte, 16)
		n, err := io.ReadFull(rand.Reader, buf)
		if err != nil {
			panic(err)
		}

		return encoding.EncodeToString(buf[:n])
	}
)

// NewClient produces a new default client implementation for emitting metrics.
func NewClient() Client {
	return Client{
		observer:   observer.Local(),
		level:      LevelInfo,
		now:        time.Now,
		uuid:       defaultUUID,
		callerSkip: 2,
	}
}

// Client provides a default implementation.
type Client struct {
	observer   observer.Observer
	level      Level
	now        func() time.Time
	uuid       func() string
	tags       []Tag
	callerSkip int
}

// WithObservers configures the new client with the provided observers.
func (c Client) WithObservers(observers ...observer.Observer) Client {
	c.observer = observer.Composite(observers)
	return c
}

// WithLevel allows the current logging level to be tuned. This does not prevent traces from being emit, or metrics
// from being reported. It only modifies the behavior of logs.
func (c Client) WithLevel(level Level) Client {
	c.level = level
	return c
}

// WithNow configures the function that's used to obtain the current timestamp.
func (c Client) WithNow(now func() time.Time) Client {
	c.now = now
	return c
}

// WithUUID returns a new uuid that uniquely identifies traces, spans, and tags.
func (c Client) WithUUID(uuid func() string) Client {
	c.uuid = uuid
	return c
}

// WithCallerSkip is used to configure the number of frames to skip when determining the caller. Callers are
// predominantly used when performing traces.
func (c Client) WithCallerSkip(callerSkip int) Client {
	c.callerSkip = callerSkip
	return c
}

// With appends tags to the current client that will automatically be added to all events, metrics, logs, and traces.
func (c Client) With(tags ...Tag) Client {
	c.tags = append(c.tags, tags...)
	return c
}

// Emit allows for the emission of an event which has now value and only associated tags.
func (c Client) Emit(event string, tags ...Tag) {
	c.With(tags...).emit(&pb.Entry{
		Kind:  pb.Kind_Event,
		Scope: event,
	})
}

// Observe reports a metric and it's associated value.
func (c Client) Observe(metric string, value float64, tags ...Tag) {
	c.With(tags...).With(Float64("value", value)).emit(&pb.Entry{
		Kind:  pb.Kind_Metric,
		Scope: metric,
	})
}

// Trace allows a method to be traced, and it's execution time recorded and reported for viewing.
func (c Client) Trace(ctxp *context.Context, tags ...Tag) ActiveTrace {
	ctx := *ctxp

	name, _ := caller(c.callerSkip)
	start := c.now()

	span := Span{
		TraceID: c.uuid(),
		ID:      c.uuid(),
	}

	v := ctx.Value(SpanKey)
	if v != nil {
		parent, hasParent := v.(Span)
		if hasParent {
			span.TraceID = parent.TraceID
			span.ParentID = parent.ID
		}
	}

	//goland:noinspection GoAssignmentToReceiver
	c = c.
		With(
			String("traceId", span.TraceID),
			String("traceSpanId", span.ID),
			String("traceParentId", span.ParentID),
		).
		With(tags...)

	if c.level <= LevelTrace {
		c.With(String("bookend", "start"), level(LevelTrace)).
			emit(&pb.Entry{
				Kind:  pb.Kind_Log,
				Scope: name,
			})
	}

	ctx = context.WithValue(ctx, SpanKey, span)
	*ctxp = ctx

	return &active{name, start, c, sync.Once{}}
}

type active struct {
	name  string
	start time.Time
	c     Client
	once  sync.Once
}

func (a *active) Done() {
	a.once.Do(func() {
		duration := a.c.now().Sub(a.start)

		//goland:noinspection GoAssignmentToReceiver
		a.c = a.c.With(Duration("duration", duration))

		if a.c.level <= LevelTrace {
			a.c.With(String("bookend", "end"), level(LevelTrace)).
				emit(
					&pb.Entry{
						Kind:  pb.Kind_Log,
						Scope: a.name,
					},
				)
		}

		// trace
		a.c.emit(&pb.Entry{
			Kind:  pb.Kind_Trace,
			Scope: a.name,
		})
	})
}

// Debug produces a debug log event.
func (c Client) Debug(msg string, tags ...Tag) {
	if c.level > LevelDebug {
		return
	}

	name, _ := caller(c.callerSkip)

	c.With(tags...).
		With(message(msg), level(LevelDebug)).
		emit(&pb.Entry{
			Kind:  pb.Kind_Log,
			Scope: name,
		})
}

// Info produces an information log event.
func (c Client) Info(msg string, tags ...Tag) {
	if c.level > LevelInfo {
		return
	}

	name, _ := caller(c.callerSkip)

	c.With(tags...).
		With(message(msg), level(LevelInfo)).
		emit(&pb.Entry{
			Kind:  pb.Kind_Log,
			Scope: name,
		})
}

// Warn produces a warning that is surfaced to operators.
func (c Client) Warn(msg string, tags ...Tag) {
	if c.level > LevelWarn {
		return
	}

	name, _ := caller(c.callerSkip)

	c.With(tags...).
		With(message(msg), level(LevelWarn)).
		emit(&pb.Entry{
			Kind:  pb.Kind_Log,
			Scope: name,
		})
}

// Error produces a message that communicates an error has occurred.
func (c Client) Error(msg string, tags ...Tag) {
	if c.level > LevelError {
		return
	}

	name, _ := caller(c.callerSkip)

	c.With(tags...).
		With(message(msg), level(LevelError)).
		emit(&pb.Entry{
			Kind:  pb.Kind_Log,
			Scope: name,
		})
}

func (c Client) emit(entries ...*pb.Entry) {
	now := pb.TimestampPB(c.now())

	tags := make([]*pb.Tag, 0, len(c.tags))
	for _, tag := range c.tags {
		tags = append(tags, tag.AsTagPB())
	}

	for _, entry := range entries {
		entry.Timestamp = now
		entry.Tags = tags
	}

	c.observer.Observe(entries)
}

// caller attempts to get method caller information. This information is used for tracing information across an
// applications source code. Need to look into the performance of this call. Parts of it may be able to be cached.
func caller(skip int) (name string, line int) {
	pctr, _, line, ok := runtime.Caller(skip)
	if !ok {
		return "", 0
	}

	return runtime.FuncForPC(pctr).Name(), line
}