highlight

README

highlight-go

Official implementation of the Highlight backend client in Go.

Usage

First, import the package

go get -u github.com/BrewingCoder/holdfast/sdk/highlight-go

Then, add the following lines to your applications main function:

import (
	"github.com/BrewingCoder/holdfast/sdk/highlight-go"
)

func main() {
	//...application logic...
	highlight.Start()
	defer highlight.Stop()
	//...application logic...
}

Then, use a highlight middleware in your apps router:

if you're using go-chi/chi:

import (
	highlightChi "github.com/BrewingCoder/holdfast/sdk/highlight-go/middleware/chi"
)

func main() {
	//...
	r := chi.NewMux()
	r.Use(highlightChi.Middleware)
	//...
}

if you're using gin-gonic/gin:

import (
	highlightGin "github.com/BrewingCoder/holdfast/sdk/highlight-go/middleware/gin"
)

func main() {
	//...
	r := gin.New()
	r.Use(highlightGin.Middleware())
	//...
}

Finally, it's time to consume errors. Add the following line to your error handling:

func someEndpoint() {
	err := someFuntionCall()
	if err != nil {
		highlight.ConsumeError(err)
		// including optional tags:
		highlight.ConsumeError(err, "environment:dev", "important")
	}
}

Documentation

Index

• Constants
• Variables
• func CreateLoggerProvider(ctx context.Context, endpoint string, opts ...sdklog.LoggerProviderOption) (*sdklog.LoggerProvider, error)
• func CreateMeterProvider(ctx context.Context, endpoint string, opts ...sdkmetric.Option) (*sdkmetric.MeterProvider, error)
• func CreateTracerProvider(ctx context.Context, endpoint string, opts ...sdktrace.TracerProviderOption) (*sdktrace.TracerProvider, error)
• func EndTrace(span trace.Span)
• func GetProjectID() string
• func InterceptRequest(r *http.Request) context.Context
• func InterceptRequestWithContext(ctx context.Context, r *http.Request) context.Context
• func IsRunning() bool
• func RecordCount(ctx context.Context, name string, value int64, tags ...attribute.KeyValue)
• func RecordError(ctx context.Context, err error, tags ...attribute.KeyValue) context.Context
• func RecordHistogram(ctx context.Context, name string, value float64, tags ...attribute.KeyValue)
• func RecordLog(ctx context.Context, record log.Record, tags ...log.KeyValue) error
• func RecordLogWithLogger(ctx context.Context, lg log.Logger, record log.Record, tags ...log.KeyValue) error
• func RecordMetric(ctx context.Context, name string, value float64, tags ...attribute.KeyValue)
• func RecordSpanError(span trace.Span, err error, tags ...attribute.KeyValue)
• func RecordSpanErrorWithStack(span trace.Span, err ErrorWithStack)
• func SetDebugMode(l Logger)
• func SetFlushInterval(_ time.Duration)
• func SetOTLPEndpoint(newOtlpEndpoint string)
• func SetProjectID(id string)
• func Start(opts ...Option)
• func StartTrace(ctx context.Context, name string, tags ...attribute.KeyValue) (trace.Span, context.Context)
• func StartTraceWithTimestamp(ctx context.Context, name string, t time.Time, opts []trace.SpanStartOption, ...) (trace.Span, context.Context)
• func StartTraceWithTracer(ctx context.Context, tracer trace.Tracer, name string, t time.Time, ...) (trace.Span, context.Context)
• func StartWithContext(ctx context.Context, opts ...Option)
• func Stop()
• type ErrorWithStack
• type Logger
• type OTLP
  • func StartOTLP() (*OTLP, error)
• type Option
  • func WithEnvironment(environment string) Option
  • func WithProjectID(projectID string) Option
  • func WithSamplingRate(samplingRate float64) Option
  • func WithSamplingRateMap(rates map[trace.SpanKind]float64) Option
  • func WithServiceName(serviceName string) Option
  • func WithServiceVersion(serviceVersion string) Option
• type TraceType

Constants

const (
	Highlight       contextKey = "highlight"
	RequestID                  = Highlight + "RequestID"
	SessionSecureID            = Highlight + "SessionSecureID"
)

const DeprecatedProjectIDAttribute = "highlight_project_id"

const DeprecatedRequestIDAttribute = "highlight_trace_id"

const DeprecatedSessionIDAttribute = "highlight_session_id"

const DeprecatedSourceAttribute = "Source"

const EnvironmentAttribute = "environment"

const ErrorSpanName = "highlight.error"

const ErrorURLAttribute = "URL"

const LogEvent = "log"

const LogMessageAttribute = "log.message"

const LogMessageLegacyAttribute = "message"

const LogSeverityAttribute = "log.severity"

const LogSeverityDefaultAttribute = "level"

const LogSeverityLegacyAttribute = "severity"

const LogSpanName = "highlight.log"

const LogrusSpanName = "highlight.go.log"

const MetricEvent = "metric"

const MetricEventName = "metric.name"

const MetricEventValue = "metric.value"

const MetricSpanName = "highlight-metric"

const OTLPDefaultEndpoint = "http://localhost:4318"

const ProjectIDAttribute = "highlight.project_id"

const ProjectIDHeader = "x-highlight-project"

const RequestIDAttribute = "highlight.trace_id"

const SessionIDAttribute = "highlight.session_id"

const SourceAttribute = "highlight.source"

const TraceKeyAttribute = "highlight.key"

const TraceTypeAttribute = "highlight.type"

const Version string = "v0.12.0"

Variables

var (
	ContextKeys = struct {
		RequestID       contextKey
		SessionSecureID contextKey
	}{
		RequestID:       RequestID,
		SessionSecureID: SessionSecureID,
	}
)

Functions

func CreateLoggerProvider

func CreateLoggerProvider(ctx context.Context, endpoint string, opts ...sdklog.LoggerProviderOption) (*sdklog.LoggerProvider, error)

func CreateMeterProvider

func CreateMeterProvider(ctx context.Context, endpoint string, opts ...sdkmetric.Option) (*sdkmetric.MeterProvider, error)

func CreateTracerProvider

func CreateTracerProvider(ctx context.Context, endpoint string, opts ...sdktrace.TracerProviderOption) (*sdktrace.TracerProvider, error)

func EndTrace

func EndTrace(span trace.Span)

func GetProjectID

func GetProjectID() string

func InterceptRequest

func InterceptRequest(r *http.Request) context.Context

InterceptRequest calls InterceptRequestWithContext using the request object's context

func InterceptRequestWithContext

func InterceptRequestWithContext(ctx context.Context, r *http.Request) context.Context

InterceptRequestWithContext captures the highlight session and request ID for a particular request from the request headers, adding the values to the provided context.

func IsRunning

func IsRunning() bool

func RecordCount

func RecordCount(ctx context.Context, name string, value int64, tags ...attribute.KeyValue)

func RecordError

func RecordError(ctx context.Context, err error, tags ...attribute.KeyValue) context.Context

RecordError processes `err` to be recorded as a part of the session or network request. Highlight session and trace are inferred from the context. If no sessionID is set, then the error is associated with the project without a session context.

func RecordHistogram

func RecordHistogram(ctx context.Context, name string, value float64, tags ...attribute.KeyValue)

func RecordLog

func RecordLog(ctx context.Context, record log.Record, tags ...log.KeyValue) error

RecordLog is used to record arbitrary logs in your golang backend. This function is under active development as the OpenTelemetry logging API is still in beta.

func RecordLogWithLogger

func RecordLogWithLogger(ctx context.Context, lg log.Logger, record log.Record, tags ...log.KeyValue) error

func RecordMetric

func RecordMetric(ctx context.Context, name string, value float64, tags ...attribute.KeyValue)

RecordMetric is used to record arbitrary metrics in your golang backend. Highlight will process these metrics in the context of your session and expose them through dashboards. For example, you may want to record the latency of a DB query as a metric that you would like to graph and monitor. You'll be able to view the metric in the context of the session and network request and recorded it.

func RecordSpanError

func RecordSpanError(span trace.Span, err error, tags ...attribute.KeyValue)

func RecordSpanErrorWithStack

func RecordSpanErrorWithStack(span trace.Span, err ErrorWithStack)

func SetDebugMode

func SetDebugMode(l Logger)

func SetFlushInterval

func SetFlushInterval(_ time.Duration)

SetFlushInterval allows you to override the amount of time in which the Highlight client will collect errors before sending them to our backend. - newFlushInterval is an integer representing seconds Deprecated - this is managed by the opentelemetry SDK.

func SetOTLPEndpoint

func SetOTLPEndpoint(newOtlpEndpoint string)

SetOTLPEndpoint allows you to override the otlp address used for sending errors and traces. Use the root http url. Eg: http://localhost:4318

func SetProjectID

func SetProjectID(id string)

func Start

func Start(opts ...Option)

Start is used to start the Highlight client's collection service.

func StartTrace

func StartTrace(ctx context.Context, name string, tags ...attribute.KeyValue) (trace.Span, context.Context)

func StartTraceWithTimestamp

func StartTraceWithTimestamp(ctx context.Context, name string, t time.Time, opts []trace.SpanStartOption, tags ...attribute.KeyValue) (trace.Span, context.Context)

func StartTraceWithTracer

func StartTraceWithTracer(ctx context.Context, tracer trace.Tracer, name string, t time.Time, opts []trace.SpanStartOption, tags ...attribute.KeyValue) (trace.Span, context.Context)

func StartWithContext

func StartWithContext(ctx context.Context, opts ...Option)

StartWithContext is used to start the Highlight client's collection service, but allows the user to pass in their own context.Context. This allows the user kill the highlight worker by canceling their context.CancelFunc.

func Stop

func Stop()

Stop flushes and shuts down the SDK.

Types

type ErrorWithStack

type ErrorWithStack interface {
	Error() string
	StackTrace() errors.StackTrace
}

type Logger

type Logger interface {
	Error(v ...interface{})
	Errorf(format string, v ...interface{})
}

Logger is an interface that implements Log and Logf

type OTLP

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

func StartOTLP

func StartOTLP() (*OTLP, error)

type Option

type Option interface {
	// contains filtered or unexported methods
}

func WithEnvironment

func WithEnvironment(environment string) Option

func WithProjectID

func WithProjectID(projectID string) Option

func WithSamplingRate

func WithSamplingRate(samplingRate float64) Option

func WithSamplingRateMap

func WithSamplingRateMap(rates map[trace.SpanKind]float64) Option

func WithServiceName

func WithServiceName(serviceName string) Option

func WithServiceVersion

func WithServiceVersion(serviceVersion string) Option

type TraceType

type TraceType string

const TraceTypeFrontendConsole TraceType = "frontend.console"

const TraceTypeHighlightInternal TraceType = "highlight.internal"

const TraceTypeNetworkRequest TraceType = "http.request"

const TraceTypePhoneHome TraceType = "highlight.phonehome"

const TraceTypeWebSocketRequest TraceType = "http.request.ws"