// 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/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{ level: LevelInfo, now: time.Now, uuid: defaultUUID, callerSkip: 2, } } // Client provides a default implementation. type Client struct { level Level now func() time.Time uuid func() string tags []Tag callerSkip int } // 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"), String("fn", name)). emit(&pb.Entry{ Kind: pb.Kind_Log, Scope: "trace", }) } 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"), String("fn", a.name)).emit( &pb.Entry{ Kind: pb.Kind_Log, Scope: "trace", }, ) } // 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 } c.With(tags...). With(String("msg", msg)). emit(&pb.Entry{ Kind: pb.Kind_Log, Scope: "debug", }) } // Info produces an information log event. func (c Client) Info(msg string, tags ...Tag) { if c.level > LevelInfo { return } c.With(tags...). With(String("msg", msg)). emit(&pb.Entry{ Kind: pb.Kind_Log, Scope: "info", }) } // Warn produces a warning that is surfaced to operators. func (c Client) Warn(msg string, tags ...Tag) { if c.level > LevelWarn { return } c.With(tags...). With(String("msg", msg)). emit(&pb.Entry{ Kind: pb.Kind_Log, Scope: "warn", }) } // Error produces a message that communicates an error has occurred. func (c Client) Error(msg string, tags ...Tag) { if c.level > LevelError { return } c.With(tags...). With(String("msg", msg)). emit(&pb.Entry{ Kind: pb.Kind_Log, Scope: "error", }) } 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 _ = DefaultFormat.Marshal(sink, entry) } _ = sink.Flush() } // 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 }