rkquery

package module
v2.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 6, 2022 License: Apache-2.0 Imports: 17 Imported by: 0

README

rk-query

build codecov Go Report Card License

Human-readable query logger with zap, lumberjack and rk-logger

Table of Contents generated with DocToc

Installation

go get github.com/rookie-ninja/rk-query/v2

Quick Start

Zap logger needs to be pass to query in order to write logs

Please refer https://github.com/rookie-ninja/rk-logger for easy initialization of zap logger

Console encoding

It is human friendly printed query log encoding type.

Example:

var (
    bytes = []byte(`{
     "level": "info",
     "encoding": "console",
     "outputPaths": ["stdout"],
     "errorOutputPaths": ["stderr"],
     "initialFields": {},
     "encoderConfig": {
       "messageKey": "msg",
       "levelKey": "",
       "nameKey": "",
       "timeKey": "",
       "callerKey": "",
       "stacktraceKey": "",
       "callstackKey": "",
       "errorKey": "",
       "timeEncoder": "iso8601",
       "fileKey": "",
       "levelEncoder": "capital",
       "durationEncoder": "second",
       "callerEncoder": "full",
       "nameEncoder": "full"
     },
    "maxsize": 1024,
    "maxage": 7,
    "maxbackups": 3,
    "localtime": true,
    "compress": true
   }`)
)

func withEventConsoleEncoding() {
	logger, _, _ := rklogger.NewZapLoggerWithBytes(bytes, rk_logger.JSON)

	fac := rkquery.NewEventFactory(
		rkquery.WithServiceName("serviceName"),
		rkquery.WithEncoding(rkquery.CONSOLE),
		rkquery.WithOperation("op"),
		rkquery.WithLogger(logger))
	event := fac.CreateEvent()

	event.SetStartTime(time.Now())
	event.StartTimer("t1")
	time.Sleep(1 * time.Second)
	event.EndTimer("t1")
	event.AddPair("key", "value")
	event.SetCounter("count", 1)
	event.AddFields(zap.String("f1", "f2"), zap.Time("t2", time.Now()))
	event.AddErr(MyError{})
	event.SetEndTime(time.Now())
	event.WriteLog()
}

Output

------------------------------------------------------------------------
endTime=2021-06-13T01:16:27.58556+08:00
startTime=2021-06-13T01:16:26.581691+08:00
elapsedNano=1003868481
timezone=CST
ids={"eventId":"581812ae-924a-44b2-83f8-fa8eef071393"}
service={"serviceName":"appName","serviceVersion":"v0.0.1","entryName":"entry-example","entryKind":"example"}
env={"arch":"amd64","hostname":"lark.local","realm":"*","region":"*","az":"*","domain":"*","os":"darwin"}
payloads={"f1":"f2","t2":"2021-06-13T01:16:27.58554+08:00"}
error={"my error":1}
counters={"count":1}
pairs={"key":"value"}
timing={"t1.count":1,"t1.elapsedMs":1004}
remoteAddr=localhost
operation=op
resCode=200
eventStatus=Ended
EOE

JSON encoding

It is parsing friendly printed query log encoding type.

Example:

var (
    bytes = []byte(`{
     "level": "info",
     "encoding": "console",
     "outputPaths": ["stdout"],
     "errorOutputPaths": ["stderr"],
     "initialFields": {},
     "encoderConfig": {
       "messageKey": "msg",
       "levelKey": "",
       "nameKey": "",
       "timeKey": "",
       "callerKey": "",
       "stacktraceKey": "",
       "callstackKey": "",
       "errorKey": "",
       "timeEncoder": "iso8601",
       "fileKey": "",
       "levelEncoder": "capital",
       "durationEncoder": "second",
       "callerEncoder": "full",
       "nameEncoder": "full"
     },
    "maxsize": 1024,
    "maxage": 7,
    "maxbackups": 3,
    "localtime": true,
    "compress": true
   }`)
)

func withEventJSONEncoding() {
	logger, _, _ := rklogger.NewZapLoggerWithBytes(bytes, rk_logger.JSON)

	fac := rkquery.NewEventFactory(
		rkquery.WithServiceName("serviceName"),
		rkquery.WithEncoding(rkquery.JSON),
		rkquery.WithOperation("op"),
		rkquery.WithLogger(logger))
	event := fac.CreateEvent()

	event.SetStartTime(time.Now())
	event.StartTimer("t1")
	time.Sleep(1 * time.Second)
	event.EndTimer("t1")
	event.AddPair("key", "value")
	event.SetCounter("count", 1)
	event.AddFields(zap.String("f1", "f2"), zap.Time("t2", time.Now()))
	event.AddErr(MyError{})
	event.SetEndTime(time.Now())
	event.WriteLog()
}

Output We formatted JSON output bellow, actual logs would not be a pretty formatted JSON

{
    "endTime":"2021-06-13T00:24:21.261+0800",
    "startTime":"2021-06-13T00:24:20.257+0800",
    "elapsedNano":1004326112,
    "timezone":"CST",
    "ids":{
        "eventId":"72a59682-230f-4ba2-a9fc-e99a031e4d8c",
        "requestId":"",
        "traceId":""
    },
    "service":{
        "serviceName":"serviceName",
        "serviceVersion":"unknown",
        "entryName":"unknown",
        "entryType":"unknown"
    },
    "env":{
        "arch":"amd64",
        "hostname":"lark.local",
        "realm":"*",
        "region":"*",
        "az":"*",
        "domain":"*",
        "os":"darwin"
    },
    "payloads":{
        "f1":"f2",
        "t2":"2021-06-13T00:24:21.261768+08:00"
    },
    "error":{
        "my error":1
    },
    "counters":{
        "count":1
    },
    "pairs":{
        "key":"value"
    },
    "timing":{
        "t1.count":1,
        "t1.elapsed_ms":1004
    },
    "remoteAddr":"localhost",
    "operation":"op",
    "eventStatus":"Ended",
    "resCode":"200"
}

Flatten encoding

It will skip most of values and remains only valuable ones.

Example:

var (
    bytes = []byte(`{
     "level": "info",
     "encoding": "console",
     "outputPaths": ["stdout"],
     "errorOutputPaths": ["stderr"],
     "initialFields": {},
     "encoderConfig": {
       "messageKey": "msg",
       "levelKey": "",
       "nameKey": "",
       "timeKey": "",
       "callerKey": "",
       "stacktraceKey": "",
       "callstackKey": "",
       "errorKey": "",
       "timeEncoder": "iso8601",
       "fileKey": "",
       "levelEncoder": "capital",
       "durationEncoder": "second",
       "callerEncoder": "full",
       "nameEncoder": "full"
     },
    "maxsize": 1024,
    "maxage": 7,
    "maxbackups": 3,
    "localtime": true,
    "compress": true
   }`)
)

func withEventConsoleEncoding() {
	logger, _, _ := rklogger.NewZapLoggerWithBytes(bytes, rk_logger.JSON)

	fac := rkquery.NewEventFactory(
		rkquery.WithServiceName("serviceName"),
		rkquery.WithEncoding(rkquery.FLATTEN),
		rkquery.WithOperation("op"),
		rkquery.WithLogger(logger))
	event := fac.CreateEvent()

	event.SetStartTime(time.Now())
	event.StartTimer("t1")
	time.Sleep(1 * time.Second)
	event.EndTimer("t1")
	event.AddPair("key", "value")
	event.SetCounter("count", 1)
	event.AddFields(zap.String("f1", "f2"), zap.Time("t2", time.Now()))
	event.AddErr(MyError{})
	event.SetEndTime(time.Now())
	event.WriteLog()
}

Output

2022-03-04T02:29:53.478+0800    [200]    1002ms    op    entry-example    example    localhost    [f76ab5d3-e765-46ce-8c6f-8ad16e77f3b4]

Development Status: Stable

Contributing

We encourage and support an active, healthy community of contributors — including you! Details are in the contribution guide and the code of conduct. The rk maintainers keep an eye on issues and pull requests, but you can also report any negative conduct to lark@rkdev.info.

Released under the Apache 2.0 License.

Documentation

Overview

Package rkquery can be used for creating Event instance for logging.

Index

Constants

View Source 
const (
	// NotStarted will be assigned to Event before SetStartTime() was called.
	NotStarted eventStatus = 0
	// InProgress will be assigned to Event after SetStartTime() was called.
	InProgress eventStatus = 1
	// Ended will be assigned to Event after SetEndTime() was called.
	Ended eventStatus = 2
)

Variables

View Source 
var (
	// StdLoggerConfigBytes defines zap logger config whose output path is stdout.
	StdLoggerConfigBytes = []byte(`{
     "level": "info",
     "encoding": "console",
     "outputPaths": ["stdout"],
     "errorOutputPaths": ["stderr"],
     "initialFields": {},
     "encoderConfig": {
       "messageKey": "msg",
       "levelKey": "",
       "nameKey": "",
       "timeKey": "",
       "callerKey": "",
       "stacktraceKey": "",
       "callstackKey": "",
       "errorKey": "",
       "timeEncoder": "iso8601",
       "fileKey": "",
       "levelEncoder": "capital",
       "durationEncoder": "second",
       "callerEncoder": "full",
       "nameEncoder": "full"
     },
    "maxsize": 1,
    "maxage": 7,
    "maxbackups": 3,
    "localtime": true,
    "compress": true
   }`)

	// StdoutLogger defines zap logger which use StdLoggerConfigBytes as config.
	StdoutLogger, _, _ = rk_logger.NewZapLoggerWithBytes(StdLoggerConfigBytes, rk_logger.JSON)
)

Functions

This section is empty.

Types

type Encoding 

type Encoding int

Encoding supported format of Console and JSON currently. 

const (
	// CONSOLE is human readable format.
	CONSOLE Encoding = 0
	// JSON format.
	JSON Encoding = 1
	// FLATTEN format.
	FLATTEN Encoding = 2
)

func ToEncoding 

func ToEncoding(f string) Encoding

ToEncoding returns Encoding type from string value.

func (Encoding) String 

func (ec Encoding) String() string

String will return string value of Encoding types.

type Event 

type Event interface {

	// SetStartTime sets start timer of current event. This can be overridden by user.
	// We keep this function open in order to mock event during unit test.
	SetStartTime(time.Time)

	// GetStartTime returns start time of current event data.
	GetStartTime() time.Time

	// SetEndTime sets end timer of current event. This can be overridden by user.
	// We keep this function open in order to mock event during unit test.
	SetEndTime(time.Time)

	// GetEndTime returns end time of current event data.
	GetEndTime() time.Time

	// AddPayloads function add payload as zap.Field.
	// Payload could be anything with RPC requests or user event such as http request param.
	AddPayloads(...zap.Field)

	// ListPayloads will list payloads.
	ListPayloads() []zap.Field

	// GetEventId returns event id of current event.
	GetEventId() string

	// SetEventId sets event id of current event.
	// A new event id would be created while event data was created from EventFactory.
	// User could override event id with this function.
	SetEventId(string)

	// GetTraceId returns trace id of current event.
	GetTraceId() string

	// SetTraceId set trace id of current event.
	SetTraceId(string)

	// GetRequestId returns request id of current event.
	GetRequestId() string

	// SetRequestId set request id of current event.
	SetRequestId(string)

	// AddErr function adds an error into event which could be printed with error.Error() function.
	AddErr(error)

	// GetErrCount returns error count.
	// We will use value of error.Error() as the key.
	GetErrCount(error) int64

	// GetOperation returns operation of current event.
	GetOperation() string

	// SetOperation sets operation of current event.
	SetOperation(string)

	// GetRemoteAddr returns remote address of current event.
	GetRemoteAddr() string

	// SetRemoteAddr sets remote address of current event, mainly used in RPC calls.
	// Default value of <localhost> would be assigned while creating event via EventFactory.
	SetRemoteAddr(string)

	// GetResCode returns response code of current event.
	// Mainly used in RPC calls.
	GetResCode() string

	// SetResCode sets response code of current event.
	SetResCode(string)

	// GetEventStatus returns event status of current event.
	// Available event status as bellow:
	// 1: NotStarted
	// 2: InProgress
	// 3: Ended
	GetEventStatus() eventStatus

	// StartTimer starts timer of current sub event.
	StartTimer(string)

	// EndTimer ends timer of current sub event.
	EndTimer(string)

	// UpdateTimerMs updates timer of current sub event with time elapsed in milli seconds.
	UpdateTimerMs(string, int64)

	// UpdateTimerMsWithSample updates timer of current sub event with time elapsed in milli seconds and sample.
	UpdateTimerMsWithSample(string, int64, int64)

	// GetTimeElapsedMs returns timer elapsed in milli seconds.
	GetTimeElapsedMs(string) int64

	// GetValueFromPair returns value with key in pairs.
	GetValueFromPair(string) string

	// AddPair adds value with key in pairs.
	AddPair(string, string)

	// GetCounter returns counter of current event.
	GetCounter(string) int64

	// SetCounter sets counter of current event.
	SetCounter(string, int64)

	// IncCounter increases counter of current event.
	IncCounter(string, int64)

	// Finish sets event status and flush to logger.
	Finish()

	// Sync flushes logger in buffer
	Sync()
}

Event is used to record any event related stuff like RPC

type EventFactory 

type EventFactory struct {
	// contains filtered or unexported fields
}

EventFactory is not thread safe!!!

func NewEventFactory 

func NewEventFactory(option ...EventOption) *EventFactory

NewEventFactory creates a new event factory with option.

func (*EventFactory) CreateEvent 

func (factory *EventFactory) CreateEvent(options ...EventOption) Event

CreateEvent creates a new event with options.

func (*EventFactory) CreateEventNoop 

func (factory *EventFactory) CreateEventNoop() Event

CreateEventNoop creates a new noop event.

func (*EventFactory) CreateEventThreadSafe 

func (factory *EventFactory) CreateEventThreadSafe(options ...EventOption) Event

CreateEventThreadSafe create a new thread safe event.

type EventHelper 

type EventHelper struct {
	Factory *EventFactory
}

EventHelper is a helper function for easy use of EventData.

func NewEventHelper 

func NewEventHelper(factory *EventFactory) *EventHelper

NewEventHelper creates a new event helper.

func (*EventHelper) Finish 

func (helper *EventHelper) Finish(event Event)

Finish current event.

func (*EventHelper) FinishWithCond 

func (helper *EventHelper) FinishWithCond(event Event, success bool)

FinishWithCond finish current event with condition.

func (*EventHelper) FinishWithError 

func (helper *EventHelper) FinishWithError(event Event, err error)

FinishWithError finish current event with error.

func (*EventHelper) Start 

func (helper *EventHelper) Start(operation string, opts ...EventOption) Event

Start function creates and start a new event with options.

type EventOption 

type EventOption func(Event)

EventOption will be pass into EventFactory while creating Event to override fields in Event.

func WithEncoding 

func WithEncoding(ec Encoding) EventOption

WithEncoding override encoding in Event.

func WithEntryKind 

func WithEntryKind(kind string) EventOption

WithEntryKind override entry kind in Event.

func WithEntryName 

func WithEntryName(name string) EventOption

WithEntryName override entry name in Event.

func WithOperation 

func WithOperation(operation string) EventOption

WithOperation overrides operation in Event.

func WithPayloads 

func WithPayloads(fields ...zap.Field) EventOption

WithPayloads overrides payloads with form of zap.Field in Event.

func WithQuietMode 

func WithQuietMode(quietMode bool) EventOption

WithQuietMode turn on quiet mode which won't flush data to logger.

func WithServiceName 

func WithServiceName(name string) EventOption

WithServiceName override service name in Event.

func WithServiceVersion added in v2.0.1 

func WithServiceVersion(version string) EventOption

WithServiceVersion overrides app version in event.

func WithZapLogger 

func WithZapLogger(logger *zap.Logger) EventOption

WithZapLogger override logger in Event.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.