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"
	"time"

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

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

// NewClient produces a new default client implementation for emitting metrics.
func NewClient() Client {
	return Client{
		now: time.Now,
		uuid: func() string {
			buf := make([]byte, 16)
			n, err := io.ReadFull(rand.Reader, buf)
			if err != nil {
				panic(err)
			}

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

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

func (o Client) WithNow(now func() time.Time) Client {
	o.now = now
	return o
}

func (o Client) WithUUID(uuid func() string) Client {
	o.uuid = uuid
	return o
}

func (o Client) WithCallerSkip(callerSkip int) Client {
	o.callerSkip = callerSkip
	return o
}

func (o Client) With(tags ...Tag) Client {
	o.tags = append(o.tags, tags...)
	return o
}

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

// Observe reports a metric and it's associated value.
func (o Client) Observe(metric string, value float64, tags ...Tag) {
	o.With(tags...).emit(&pb.Entry{
		Value: &pb.Entry_Double{Double: value},
		Kind:  pb.Kind_Metric,
		Name:  metric,
	})
}

// Trace allows a method to be traced, and it's execution time recorded and reported for viewing.
func (o Client) Trace(ctx context.Context, tags ...Tag) (context.Context, DoneFunc) {
	name, _ := caller(o.callerSkip)
	start := o.now()

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

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

	o.With(tags...).With(String("bookend", "start")).emit(&pb.Entry{
		Kind:  pb.Kind_Event,
		Name:  name,
		Value: &pb.Entry_String_{String_: "trace"},
	})

	return context.WithValue(ctx, SpanKey, span), func() {
		duration := o.now().Sub(start)

		o.With(tags...).With(String("bookend", "complete")).emit(&pb.Entry{
			Kind:  pb.Kind_Event,
			Name:  name,
			Value: &pb.Entry_String_{String_: "trace"},
		})

		tags = append(
			[]Tag{
				String("trace-id", span.TraceID),
				String("trace-span-id", span.ID),
				String("trace-parent-id", span.ParentID),
			},
			tags...,
		)

		o.With(tags...).emit(
			&pb.Entry{
				Kind:  pb.Kind_Trace,
				Name:  name,
				Value: &pb.Entry_Duration{Duration: pb.DurationPB(duration)},
			},
		)
	}
}

// Debug produces a debug log event.
func (o Client) Debug(msg string, tags ...Tag) {
	o.With(tags...).emit(&pb.Entry{
		Kind:  pb.Kind_Log,
		Name:  msg,
		Value: &pb.Entry_String_{String_: "debug"},
	})
}

// Info produces an information log event.
func (o Client) Info(msg string, tags ...Tag) {
	o.With(tags...).emit(&pb.Entry{
		Kind:  pb.Kind_Log,
		Name:  msg,
		Value: &pb.Entry_String_{String_: "info"},
	})
}

// Warn produces a warning that is surfaced to operators.
func (o Client) Warn(msg string, tags ...Tag) {
	o.With(tags...).emit(&pb.Entry{
		Kind:  pb.Kind_Log,
		Name:  msg,
		Value: &pb.Entry_String_{String_: "warn"},
	})
}

// Error produces a message that communicates an error has occurred.
func (o Client) Error(msg string, tags ...Tag) {
	o.With(tags...).emit(&pb.Entry{
		Kind:  pb.Kind_Log,
		Name:  msg,
		Value: &pb.Entry_String_{String_: "error"},
	})
}

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

	for _, entry := range entries {
		// todo: check if log level is enabled

		entry.Timestamp = now

		for _, tag := range o.tags {
			if tagpb := tag.AsTagPB(); tagpb != nil {
				entry.Tags = append(entry.Tags, tagpb)
			}
		}

		_ = marshaler.Marshal(sink, entry)
		_ = sink.WriteByte('\n')
	}

	_ = sink.Flush()
}

// max returns the largest number in a series.
func max(series ...int) int {
	largest := 0

	for _, v := range series {
		if v > largest {
			largest = v
		}
	}

	return largest
}

// caller attempts to get method caller information. This information is used for tracing information across an
// applications source code.
func caller(skip int) (name string, line int) {
	pctr, _, line, ok := runtime.Caller(skip)
	if !ok {
		return "", 0
	}

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