tracer

README

knopkaLab Tracer - logging service

Интерфейс

Доступные операции в строке поиска:

• =
• !=
• >
• >=
• <
• <=
• @ (SQL LIKE)
• ? (field exists)

Полный путь логирования

• С помощью gitlab.com/knopkalab/tracer вы логируете действия вашего сервиса
• С должны опубликовать tracer.Exporter() в одном из handler'ов http сервера
• Tracer server опрашивает все экспортеры сервисов и заносит логи в базу данных MongoDB
• Через интерфейс трейсера можно посмотреть все логи в удобной древовидной структурой, с возможность поиска

Пример логирования в проекте

package main

import (
	"context"
	"fmt"
	"io/ioutil"
	"net/http"

	"gitlab.com/knopkalab/tracer"
)

func main() {
	// Создаём контекст приложения
	ctx := context.Background()

	// Инициализируем трейсер
	ringBufferSize := 1024 * 1024 * 5 // 5 MB
	exporterSecret := "secret"
	tracing := tracer.New().
		WithStdout(true /* colored */).
		WithExporter(ringBufferSize, exporterSecret).
		WithFile("app.log", &tracer.FileRotationConfig{
			MaxSizeMB:  50,
			MaxAgeDays: 200,
		})

	// Начинаем трассировку
	appCtx, span := tracing.Start(ctx, "main")
	// В конце выполнения программы заканчиваем трассировку
	defer span.Finish()

	// Просто лог о начале запуска
	span.Info().Msg("app started")

	// Создаём http роутер
	mux := http.NewServeMux()

	// Прописываем ручку экспорта логов по URL /logs
	mux.Handle("/logs", tracing.Handler())

	// Тестовая ручка с логированием
	mux.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
		// Начинаем трассировку на основе контекста реквеста
		ctx, span := tracer.Start(r.Context(), "http.request")
		// В конце выполнения функции заканчиваем трассировку
		defer span.Finish()

		// Пробрасываем поле во все ветки логов
		span.Forward(span.With().
			Str("request_remote_addr", r.RemoteAddr),
		)

		span.Trace().
			Str("uri", r.RequestURI).
			Msg("request info")

		if r.Body != nil {
			if body, err := ioutil.ReadAll(r.Body); err != nil {
				span.Trace().Bytes("body", body).Msg("request body")
			}
			defer r.Body.Close()
		}

		doResponse(ctx, w)
	})

	span.Info().Msg("  follow http://localhost:5050/hello")
	span.Info().Msg("see logs http://localhost:5050/logs")

	http.ListenAndServe(":5050", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// Прокидываем контекст трассировки приложения в контекст каждого реквеста
		r = r.WithContext(
			tracer.WithContext(r.Context(), appCtx),
		)
		mux.ServeHTTP(w, r)
	}))
}

func doResponse(ctx context.Context, w http.ResponseWriter) {
	// Начинаем трассировку на основе переданного контекста
	span := tracer.StartSpan(ctx, "doResponse")
	// В конце выполнения функции заканчиваем трассировку
	defer span.Finish()

	span.Debug().Msg("begin")

	w.WriteHeader(http.StatusOK)
	fmt.Fprint(w, "hello!")
}

Ошибки со стеком

Используйте создание или оборачивание ошибок через gitlab.com/knopkalab/tracer

• Error
• Errorf
• WithStack
• IsErrorStack

Сервер

Конфигурирование

В папку с бинарником поместите файл tracer.yml со следующим содержанием:

app:
  listen_port: 15500
  mongo_db:
    address: 127.0.0.1:27017
    database: tracing
    username: tracer
    password: secret

services:
  service_name:
    exporter:
      url: http://localhost:15000
      secret: bearer_token
      refresh: 1s
	  timeout: 5s

Documentation

Index

• Constants
• Variables
• func Check(ctx context.Context) bool
• func WithContext(ctx, spanCtx context.Context) context.Context
• type Context
• type Event
• type FileRotationConfig
• type Log
  • func FetchLogsFromExporter(client *http.Client, exporterURL, exporterSecret string) ([]Log, error)
  • func (log Log) ConvertTimeToString()
  • func (log Log) Fix()
  • func (log Log) HasDuration() bool
  • func (log Log) NoLevel() bool
  • func (log Log) Valid() bool
• type Logger
• type Span
  • func Start(ctx context.Context, spanName string) (context.Context, Span)
  • func StartSpan(ctx context.Context, spanName string) Span
• type SpanContext
  • func FromContext(ctx context.Context) SpanContext
  • func StartSpanContext(ctx context.Context, spanName string) SpanContext
• type SpanLogger
• type Storage
  • func NewStorage(ctx context.Context, db *mongo.Database, collection string) Storage
• type Tracer
  • func New() *Tracer
  • func (t *Tracer) Handler() http.Handler
  • func (t *Tracer) Start(ctx context.Context, span string) (context.Context, Span)
  • func (t *Tracer) WithExporter(bufferSize int, secret string) *Tracer
  • func (t *Tracer) WithFile(filename string, conf *FileRotationConfig) *Tracer
  • func (t *Tracer) WithStdout(colored bool) *Tracer
  • func (t *Tracer) WithWriter(w io.Writer) *Tracer

Constants

const (
	FieldID      = "_id"
	FieldService = "_service"

	FieldBranch   = "_branch"
	FieldParent   = "_parent"
	FieldSpan     = "_span"
	FieldDuration = "_duration"

	FieldLevel      = "_level"
	FieldMessage    = "_message"
	FieldError      = "_error"
	FieldErrorStack = "_stack"
	FieldFile       = "_file"
	FieldTime       = "_time"
)

Variables

var DefaultLogger = zerolog.New(os.Stdout).
	Level(zerolog.TraceLevel).
	With().Timestamp().Caller().
	Logger()

Functions

func Check

func Check(ctx context.Context) bool

func WithContext

func WithContext(ctx, spanCtx context.Context) context.Context

Types

type Context

type Context = zerolog.Context

type Event

type Event = zerolog.Event

type FileRotationConfig

type FileRotationConfig struct {
	MaxSizeMB  int  `desc:"max size of active log file in MB"`
	MaxAgeDays int  `desc:"max age days of backups files"`
	MaxBackups int  `desc:"max backups count"`
	Compress   bool `desc:"compress backups files"`
}

type Log

type Log map[string]interface{}

func FetchLogsFromExporter

func FetchLogsFromExporter(client *http.Client, exporterURL, exporterSecret string) ([]Log, error)

func (Log) ConvertTimeToString

func (log Log) ConvertTimeToString()

ConvertTimeToString - because JavaScript not supported big int

func (Log) Fix

func (log Log) Fix()

func (Log) HasDuration

func (log Log) HasDuration() bool

func (Log) NoLevel

func (log Log) NoLevel() bool

func (Log) Valid

func (log Log) Valid() bool

type Logger

type Logger = zerolog.Logger

type Span

type Span interface {
	SpanLogger
	Finish()
}

func Start

func Start(ctx context.Context, spanName string) (context.Context, Span)

func StartSpan

func StartSpan(ctx context.Context, spanName string) Span

type SpanContext

type SpanContext interface {
	Span
	context.Context
}

func FromContext

func FromContext(ctx context.Context) SpanContext

func StartSpanContext

func StartSpanContext(ctx context.Context, spanName string) SpanContext

type SpanLogger

type SpanLogger interface {
	Trace() *Event
	Debug() *Event
	Info() *Event
	Warn() *Event
	Error(error) *Event
	Panic() *Event
	Fatal() *Event

	Forward(Context)
	With() Context
	WithTrace() Context
}

type Storage

type Storage interface {
	Migrate(context.Context) error

	Services(context.Context) ([]string, error)

	Save(ctx context.Context, service string, log Log) error

	Search(ctx context.Context, service, filter string, sortASC bool, offset, limit int64) (logs []Log, total int64, err error)
	Branch(ctx context.Context, service, branchID string, afterTime int64, limit int64) ([]Log, error)
}

func NewStorage

func NewStorage(ctx context.Context, db *mongo.Database, collection string) Storage

type Tracer

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

func New

func New() *Tracer

func (*Tracer) Handler

func (t *Tracer) Handler() http.Handler

func (*Tracer) Start

func (t *Tracer) Start(ctx context.Context, span string) (context.Context, Span)

func (*Tracer) WithExporter

func (t *Tracer) WithExporter(bufferSize int, secret string) *Tracer

func (*Tracer) WithFile

func (t *Tracer) WithFile(filename string, conf *FileRotationConfig) *Tracer

func (*Tracer) WithStdout

func (t *Tracer) WithStdout(colored bool) *Tracer

func (*Tracer) WithWriter

func (t *Tracer) WithWriter(w io.Writer) *Tracer