tel

package module
v2.0.1 Latest Latest
Warning

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

 Go to latest Published: Feb 20, 2022 License: MIT Imports: 41 Imported by: 17

README 

= Telemetry.V2 Otel Protocol

Framework which aims to ease logging affair: `Logs`, `Traces` and `Metrics` .

V2 version launch usage of OpenTelemetry specification for all logging directions. This mean that all logging propagators uses `OTEL` protocol.

Tel use `zap.Logger` as the heart of system. That why it's pass all zap functions through.

== Motto
Ony context all logs.

Decrease external dependencies as match as possible.

== Logging stack
Logging data exported via `OTEL's` GRPC protocol. `tel` developed to trespass it via https://github.com/open-telemetry/opentelemetry-collector[open-telemetry collector] which should route log data up to any desired log receivers.

Keep in mind that collector has plugin version https://github.com/open-telemetry/opentelemetry-collector-contrib[collector contrib] - this is gateway-adapter to numerous protocols which not yet  support `OTEL`, for example grafana loki.


For instance,  you can use `opentelemetry-collector-contrib` as `tel` receiver and route logging data to `Grafana Loki`, trace data to `Grafana Tempo` and metric data to `Prometheus + Grafana ;)`

== Features

* `OTEL` logs implementation

== Env

.OTEL_SERVICE_NAME
service name

.PROJECT
obsolete but mean the same as `OTEL_SERVICE_NAME`

`type`: string

.NAMESPACE
project namespace

`type`: string

.LOG_LEVEL
info log

.LOG_ENCODE
valid options: `console` and `json` or "none"

none - disable print to console (only OTEL or critical errors)

`type`: string
NOTE:  debug, info, warn, error, dpanic, panic, fatal

.DEBUG
for IsDebug() function

`type`: bool

.SENTRY_DSN
sentry dns

`type`: string

.MONITOR_ADDR
address where `health`, `prometheus` would be listen

NOTE: address logic represented in net.Listen description

.OTEL_COLLECTOR_GRPC_ADDR
Address to otel collector server via GRPC protocol

.OTEL_EXPORTER_WITH_INSECURE
With insecure ...

.OTEL_RESOURCE_ATTRIBUTES
This optional variable, handled by open-telemetry SDK. Separator is semicolon. Put additional resources variables, very suitable!

== Modules, Plugins and ect
Some plugins require external packages,  we don'ty like unnecessary increasing dependencies. Thus offer sub-modules which should be added separately

=== Middlewares
 github.com/d7561985/tel/v2/middleware/natsmw

==== Propagators
.github.com/d7561985/tel/v2/propagators/natsprop
Just helper which uses any TextMapPropagator (by default globally declared or via WithPropagators option).
Suitable propagate traces (`propagation.TraceContext`) or baggage(`propagation.Baggage`).

=== Plugins
==== Logging
 github.com/d7561985/tel/v2/plugins/pgx

== ToDo

* [ ] Expose health check to specific metric
* [ ] Duplicate trace messages for root - ztrace.New just add to chain tree

== Usage

Tale look in `example/demo` folder.

Documentation

Overview

Package tel represent Telemetry service we support context as source of Telemetry for gracefully support middleware we not pass ref to Telemetry for better handling different log instances

Index

Constants

View Source 
const (
	MonitorEndpoint     = "/metrics"
	HealthEndpoint      = "/health"
	PprofIndexEndpoint  = "/debug/pprof"
	EchoShutdownTimeout = 5 * time.Second
)
View Source 
const DisableLog = "none"

Variables

View Source 
var (
	Any        = zap.Any
	Binary     = zap.Binary
	ByteString = zap.ByteString
	Bool       = zap.Bool
	Duration   = zap.Duration
	Float32    = zap.Float32
	Float64    = zap.Float64
	Int        = zap.Int
	Int64      = zap.Int64
	Int32      = zap.Int32
	Int16      = zap.Int16
	Int8       = zap.Int8
	String     = zap.String
	Time       = zap.Time
	Uint       = zap.Uint
	Uint64     = zap.Uint64
	Uint32     = zap.Uint32
	Uint16     = zap.Uint16
	Uint8      = zap.Uint8
	Uintptr    = zap.Uintptr
	Error      = zap.Error
)
View Source 
var (
	Strings = zap.Strings
	Ints    = zap.Ints
)
View Source 
var (
	ErrEmptyHandler = fmt.Errorf("unable to add nil health to monitoring")
)
View Source 
var (
	GenServiceName = defaultServiceFmt
)

Functions

func CreateRes 

func CreateRes(ctx context.Context, l Config) *resource.Resource

func SetGlobal 

func SetGlobal(t Telemetry)

func SetInstanceIDGenerator 

func SetInstanceIDGenerator(fn func(string) string)

SetInstanceIDGenerator set generator for instance name

func SetLogOutput 

func SetLogOutput(log *Telemetry) *bytes.Buffer

SetLogOutput debug function for duplicate input log into bytes.Buffer

func StartSpanFromContext 

func StartSpanFromContext(ctx context.Context, name string, opts ...trace.SpanStartOption) (
	trace.Span, context.Context)

StartSpanFromContext start telemetry span witch create or continue existent trace for gracefully continue trace ctx should contain both span and tele

func UpdateTraceFields 

func UpdateTraceFields(ctx context.Context)

UpdateTraceFields during session start good way to update tracing fields @prefix - for split different inter-service calls: kafka, grpc, db and etc

func WithContext 

func WithContext(ctx context.Context, l Telemetry) context.Context

func WrapContext 

func WrapContext(ctx context.Context, l *Telemetry) context.Context

Types

type Config 

type Config struct {
	Service   string `env:"OTEL_SERVICE_NAME"`
	Namespace string `env:"NAMESPACE"`
	Version   string `env:"VERSION"`
	LogLevel  string `env:"LOG_LEVEL" envDefault:"info"`
	// Valid values are "json", "console" or "none"
	LogEncode string `env:"LOG_ENCODE" envDefault:"json"`
	Debug     bool   `env:"DEBUG" envDefault:"false"`

	MonitorAddr string `env:"MONITOR_ADDR" envDefault:"0.0.0.0:8011"`

	OtelConfig
}

func DefaultConfig 

func DefaultConfig() Config

func DefaultDebugConfig 

func DefaultDebugConfig() Config

func GetConfigFromEnv 

func GetConfigFromEnv() Config

GetConfigFromEnv uses DefaultConfig and overwrite only variables present in env

type HealthChecker 

type HealthChecker struct {
	Name    string
	Handler health.Checker
}

type HealthHandler 

type HealthHandler struct {
	health.CompositeChecker
}

func NewHealthHandler 

func NewHealthHandler() *HealthHandler

NewHealthHandler returns a new Handler

func (*HealthHandler) ServeHTTP 

func (h *HealthHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP returns a json encoded health set the status to http.StatusServiceUnavailable if the check is down

type Logger 

type Logger interface {
	Check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry

	Debug(msg string, fields ...zap.Field)
	Info(msg string, fields ...zap.Field)
	Warn(msg string, fields ...zap.Field)
	Error(msg string, fields ...zap.Field)
	Panic(msg string, fields ...zap.Field)
	Fatal(msg string, fields ...zap.Field)

	Sync() error

	Core() zapcore.Core
}

type Monitor 

type Monitor interface {
	AddMetricTracker(ctx context.Context, metrics ...metrics.MetricTracker) Monitor
	AddHealthChecker(ctx context.Context, handlers ...HealthChecker) Monitor

	Start(ctx context.Context)
	GracefulStop(ctx context.Context)
}

type OtelConfig 

type OtelConfig struct {
	// OtelAddr address where grpc open-telemetry exporter serve
	Addr         string `env:"OTEL_COLLECTOR_GRPC_ADDR" envDefault:"0.0.0.0:4317"`
	WithInsecure bool   `env:"OTEL_EXPORTER_WITH_INSECURE" envDefault:"true"`
}

type Telemetry 

type Telemetry struct {
	*zap.Logger
	// contains filtered or unexported fields
}

func FromCtx 

func FromCtx(ctx context.Context) *Telemetry

FromCtx retrieves from ctx tel object

func Global 

func Global() Telemetry

func New 

func New(ctx context.Context, cfg Config) (Telemetry, func())

New create full featured telemetry instance and register it as global

func NewNull 

func NewNull() Telemetry

func (Telemetry) Copy 

func (t Telemetry) Copy() Telemetry

Copy resiver instance and give us more convenient way to use pipelines

func (Telemetry) Ctx 

func (t Telemetry) Ctx() context.Context

Ctx initiate new ctx with Telemetry

func (Telemetry) IsDebug 

func (t Telemetry) IsDebug() bool

IsDebug if ENV DEBUG was true

func (Telemetry) LogLevel 

func (t Telemetry) LogLevel() zapcore.Level

LogLevel safe pars log level, in case of error return InfoLevel

func (Telemetry) M 

func (t Telemetry) M() Monitor

M returns monitoring instance

func (Telemetry) MM 

func (t Telemetry) MM() metric.Meter

func (*Telemetry) Printf 

func (t *Telemetry) Printf(msg string, items ...interface{})

Printf expose fx.Printer interface as debug output

func (*Telemetry) PutAttr 

func (t *Telemetry) PutAttr(attr ...attribute.KeyValue) *Telemetry

PutAttr opentelemetry attr

func (*Telemetry) PutFields 

func (t *Telemetry) PutFields(fields ...zap.Field) *Telemetry

PutFields update current logger instance with new fields, which would affect only on nest write log call for current tele instance Because reference it also affect context and this approach is covered in Test_telemetry_With

func (*Telemetry) StartMonitor 

func (t *Telemetry) StartMonitor()

StartMonitor is blocking operation

func (*Telemetry) StartSpan 

func (t *Telemetry) StartSpan(name string, opts ...trace.SpanStartOption) (trace.Span, context.Context)

StartSpan start absolutely new trace telemetry span keep in mind than that function don't continue any trace, only create new for continue span use StartSpanFromContext

return context where embed telemetry with span writer

func (Telemetry) T 

func (t Telemetry) T() trace.Tracer

T returns opentracing instance

func (Telemetry) WithContext 

func (t Telemetry) WithContext(ctx context.Context) context.Context

WithContext put new copy of telemetry into context

func (Telemetry) WithSpan 

func (t Telemetry) WithSpan(s trace.Span) *Telemetry

WithSpan create span logger where we can duplicate messages both tracer and logger Furthermore we create new log instance with trace fields

Source Files

View all Source files

Directories

Path Synopsis
example
demo/pkg/demo
middleware
grpc
http
Package httpclient implement tel http.client wrapper which help to handle error The most important approach: perform logs by itself DEPRECATED: use transport inside http.client
 Package httpclient implement tel http.client wrapper which help to handle error The most important approach: perform logs by itself DEPRECATED: use transport inside http.client
mq
Package mq common package for any MQ system Based on Kafka Stream but everything what you need is -
 Package mq common package for any MQ system Based on Kafka Stream but everything what you need is -
monitoring
checkers
heallth
metrics
connection
logskd
logskd/logprocmocks
otlpconfig
otlploggrpc
retry
pkg
grpcerr
logtransform
otelerr
tracetransform
zlogfmt
ztrace

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.