scout

README

scout-go

The official Go SDK for Scout. Read the docs at https://docs.getscout.dev/sdks/go/overview

Usage

Require package:

go get github.com/scout-inc/scout-go

In your entrypoint function:

import "github.com/scout-inc/scout-go"

func main() {
	// some code

	scout.Init(
		scout.WithProjectID(SCOUT_PROJECT_ID)
	)
	defer scout.Stop()
	
	// some code
}

Scout provides middleware for the more common Go server frameworks:

go-chi/chi:

import (
	"github.com/scout-inc/scout-go"
	s "github.com/scout-inc/scout-go/middleware/chi"
)

func main() {
	// some code
	scout.Init(
		scout.WithProjectID(SCOUT_PROJECT_ID)
	)
	defer scout.Stop()

	r := chi.NewMux()
	r.Use(s.Middleware)
	// some code
}

gin-gonic/gin:

import (
	"github.com/scout-inc/scout-go"
	s "github.com/scout-inc/scout-go/middleware/gin"
)

func main() {
	// some code
	scout.Init(
		scout.WithProjectID(SCOUT_PROJECT_ID)
	)
	defer scout.Stop()

	r := chi.NewMux()
	r.Use(s.Middleware())
	// some code
}

See https://docs.getscout.dev/sdks/go/frameworks for more examples.

To manually record an error:

import (
	...
	"go.opentelemetry.io/otel/attribute"
)

func LoginWithOAuth(ctx context.Context, email string) {
	value, err := doSomething()
	if err != nil {
		// tags can be used to enrich errors and traces with additional information
		errorTags := []attribute.KeyValue{
			{
				Key: attribute.Key("user.email"),
				Value: attribute.StringValue(email)
			}
		}
		scout.RecordError(ctx, err, errorTags...)
	}
	// some code
}

Documentation

Index

• Constants
• Variables
• func EndTrace(span trace.Span)
• func ExtractIdsFromRequest(requestDetails string) (string, string, error)
• func GetMetricSamplingRate() float64
• func GetProjectID() string
• func Init(opts ...Option)
• func InterceptRequest(r *http.Request) context.Context
• func InterceptRequestWithContext(ctx context.Context, r *http.Request) context.Context
• func IsRunning() bool
• func RecordError(ctx context.Context, err error, tags ...attribute.KeyValue) context.Context
• 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 ScopedKey(key string, separator *string) string
• func SetDebugMode(l Logger)
• func SetOtelEndpoint(newotelEndpoint 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 StartTraceWithoutResourceAttributes(ctx context.Context, name string, opts []trace.SpanStartOption, ...) (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 WithMetricSamplingRate(samplingRate float64) 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 (
	Scout           contextKey = "scout"
	RequestID                  = Scout + "RequestID"
	SessionSecureID            = Scout + "SessionSecureID"
)

const (
	ScoutInternalLogTag = "[scout-go]"
	RequestTracerHeader = "X-Scout-Request"
)

const ErrorURLAttribute = "URL"

const LogEvent = "log"

const LogMessageAttribute = "log.message"

const LogSeverityAttribute = "log.severity"

const MetricEvent = "metric"

const MetricEventName = "metric.name"

const MetricEventValue = "metric.value"

const OTLPDefaultEndpoint = "https://otel.getscout.us:4318"

const ProjectIDAttribute = "scout.project_id"

const RequestIDAttribute = "scout.trace_id"

const SessionIDAttribute = "scout.session_id"

const SourceAttribute = "scout.source"

const TraceKeyAttribute = "scout.key"

const TraceTypeAttribute = "scout.type"

Variables

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

Functions

func EndTrace

func EndTrace(span trace.Span)

func ExtractIdsFromRequest

func ExtractIdsFromRequest(requestDetails string) (string, string, error)

func GetMetricSamplingRate

func GetMetricSamplingRate() float64

func GetProjectID

func GetProjectID() string

func Init

func Init(opts ...Option)

Initialise telemetry collector

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 and request ID for a particular request from the request headers, adding the values to the provided context.

func IsRunning

func IsRunning() bool

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.

Scout session and trace are inferred from the context.

If sessionID is not set, then the error is associated with the project without a session context.

func RecordMetric

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

RecordMetric is used to record arbitrary metrics in your Go backend.

Scout will process these metrics in the context of your session and expose them through charts.

For example, you may want to record the latency of a database query as a metric that you can graph and monitor.

func RecordSpanError

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

func RecordSpanErrorWithStack

func RecordSpanErrorWithStack(span trace.Span, err ErrorWithStack)

func ScopedKey

func ScopedKey(key string, separator *string) string

func SetDebugMode

func SetDebugMode(l Logger)

func SetOtelEndpoint

func SetOtelEndpoint(newotelEndpoint string)

SetOtelEndpoint allows you to override the otlp address used for sending errors and traces. Use the root http url. Eg: https://otel.scout.us:4318

func SetProjectID

func SetProjectID(id string)

func Start

func Start(opts ...Option)

Start readies Scout to start collecting telemetry.

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 StartTraceWithoutResourceAttributes

func StartTraceWithoutResourceAttributes(ctx context.Context, name string, opts []trace.SpanStartOption, tags ...attribute.KeyValue) (trace.Span, context.Context)

func StartWithContext

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

StartWithContext is used to start Scout's telemetry collection service, but allows the user to pass in their own context.Context. This allows the user kill the Scout worker by invoking context.CancelFunc.

func Stop

func Stop()

Flush buffers and stop collecting telemetry

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 WithMetricSamplingRate

func WithMetricSamplingRate(samplingRate float64) 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 TraceTypeNetworkRequest TraceType = "http.request"

const TraceTypeScoutInternal TraceType = "scout.internal"