logruscls

README

Tencent CLS Hook for logrus

Asynchronise batch upload logs to Tencent Cloud CLS for logrus with configurable batch number and max wait time.

Usage

package main

import (
	"github.com/chuangbo/logruscls"
	log "github.com/sirupsen/logrus"
)

func main() {
	// NewCLSAsyncClient or NewCLSClient
	client, err := logruscls.NewCLSAsyncClient(
		"topicID",
		"region",
		"secretID",
		"secretKey",
		30, // max number of logs for batch upload
		time.Second*30, // max wait time before reach max number of logs
	)
	if err != nil {
		panic(err)
	}

	hook, err := logruscls.NewHook(client)
	if err != nil {
		panic(err)
	}
	log.AddHook(hook)
}

Of course the logrus-free golang cls client CLSClient and CLSAsyncClient are for you to use directly as well if logrus is not your thing.

package main

import (
	"github.com/chuangbo/logruscls"
	"github.com/chuangbo/logruscls/pb"
	"github.com/golang/protobuf/proto"
)

func main() {
	client, err := logruscls.NewCLSAsyncClient(...)
	if err != nil {
		panic(err)
	}

	err = client.Log(&pb.Log{
		Time: proto.Int64(time.Now().UnixNano() / int64(time.Millisecond)),
		Contents: []*pb.Log_Content{
			{
				Key:   proto.String("message"),
				Value: proto.String("Hello Logrus"),
			},
		},
	})
	if err != nil {
		panic(err)
	}
}

For more API please refer to godoc and CLS protobuf definition. But please keep in mind, this may never going to be a full-feature CLS client.

Todos

• signature for headers and query string (md5 doesn't work so kind of pointless)
• content md5 (seems upload using even wrong random md5 checksum work)
• lz4 compress (doesn't work)
• tests

License

MIT

Copyright (c) 2019-present, Chuangbo Li

Documentation

Overview

Package logruscls provides logrus hook for tencent cls.

It has these top-level structs:

Hook
CLSClient
CLSAsyncClient

Index

• type CLSAsyncClient
  • func NewCLSAsyncClient(region, secretID, secretKey, topicID string, batch int, delay time.Duration) (*CLSAsyncClient, error)
  • func (c *CLSAsyncClient) Log(log *pb.Log) error
• type CLSClient
  • func NewCLSClient(region, secretID, secretKey, topicID string) (*CLSClient, error)
  • func (c *CLSClient) Log(log *pb.Log) error
  • func (c *CLSClient) UploadStructuredLog(logGroupList *pb.LogGroupList) error
• type CLSLogger
• type Hook
  • func NewHook(client CLSLogger) (*Hook, error)
  • func (hook *Hook) Fire(entry *logrus.Entry) error
  • func (hook *Hook) Levels() []logrus.Level

Types

type CLSAsyncClient

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

CLSAsyncClient to send logs to cls in batch on the background.

func NewCLSAsyncClient

func NewCLSAsyncClient(region, secretID, secretKey, topicID string, batch int, delay time.Duration) (*CLSAsyncClient, error)

NewCLSAsyncClient creates a async version of CLSClient

func (*CLSAsyncClient) Log

func (c *CLSAsyncClient) Log(log *pb.Log) error

Log put one log to the logs queue

type CLSClient

type CLSClient struct {
	URL                 string
	SecretID, SecretKey string
	TopicID             string
}

CLSClient is cls client

func NewCLSClient

func NewCLSClient(region, secretID, secretKey, topicID string) (*CLSClient, error)

NewCLSClient create a cls client

func (*CLSClient) Log

func (c *CLSClient) Log(log *pb.Log) error

Log upload one log directly to cls

func (*CLSClient) UploadStructuredLog

func (c *CLSClient) UploadStructuredLog(logGroupList *pb.LogGroupList) error

UploadStructuredLog upload structured log to tencent CLS

type CLSLogger

type CLSLogger interface {
	Log(log *pb.Log) error
}

CLSLogger provides a cls client which has Log function for hook to use

type Hook

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

Hook to send logs via tencent cls.

func NewHook

func NewHook(client CLSLogger) (*Hook, error)

NewHook creates a hook to be added to an instance of logger

func (*Hook) Fire

func (hook *Hook) Fire(entry *logrus.Entry) error

Fire uploads logs to cls

func (*Hook) Levels

func (hook *Hook) Levels() []logrus.Level

Levels returns support levels for the hook