lumigotracer

README

go-tracer (BETA)

This is lumigo/go-tracer-beta, Lumigo's Golang agent for distributed tracing and performance monitoring.

Installation

go-tracer-beta can be installed like any other Go library through go get:

$ go get github.com/lumigo-io/go-tracer-beta

Or, if you are already using Go Modules, you may specify a version number as well:

$ go get github.com/lumigo-io/go-tracer-beta@master

Configuration

Lumigo Go tracer offers several different configuration options. Pass these to the Lambda function as environment variables:

Name	Type	Description	Required
LUMIGO_USE_TRACER_EXTENSION	bool	Enables usage of Go tracer	true
LUMIGO_DEBUG	bool	Enables debug logging	false

Usage

You need a lumigo token which you can find under the Project Settings and Tracing tab in lumigo platform. Then you need just to wrap your Lambda:

import (
  //other imports

  lumigotracer "github.com/lumigo-io/go-tracer-beta"
)

type MyEvent struct {
  Name string `json:"name"`
}

func HandleRequest(ctx context.Context, name MyEvent) (string, error) {
  return fmt.Sprintf("Hello %s!", name.Name ), nil
}

func main() {
	wrappedHandler := lumigotracer.WrapHandler(HandleRequest, &lumigotracer.Config{
		Token:       "<your-token>",
	})
	lambda.Start(wrappedHandler)
}

For tracing AWS SDK v2.0 calls check the following example:

  client := &http.Client{
    Transport: lumigotracer.NewTransport(http.DefaultTransport),
  }

  // for AWS SDK v1.x
  sess := session.Must(session.NewSession(&aws.Config{
    HTTPClient: client,
  }))

  svc := s3.New(sess)
  
  // for AWS SDK v2.x
  cfg, _ := config.LoadDefaultConfig(context.Background(), config.WithHTTPClient(client))
	svc := s3.NewFromConfig(cfg)

For tracing HTTP calls check the following example:

  client := &http.Client{
    Transport: lumigotracer.NewTransport(http.DefaultTransport),
  }
	req, _ := http.NewRequest("GET", "https://<your-url>", nil)

  // for net/http
	res, err := client.Do(req)

  // for golang.org/x/net/context/ctxhttp
	res, err := ctxhttp.Do(context.Background(), client, req)

In your lambda environment variables you need to set LUMIGO_USE_TRACER_EXTENSION: true and use the following layer for us-east-1: arn:aws:lambda:us-east-1:114300393969:layer:lumigo-tracer-extension:36. The layer will be available in more regions soon.

Contributing

Contributions to this project are welcome from all! Below are a couple pointers on how to prepare your machine, as well as some information on testing.

Required Tools:

• go v1.16 and later
• make

If you want to deploy the example lambda for real testing you need:

• terraform 0.14.5

Lint

Linting the codebase:

make lint

Test suite

Run the test suite:

make test

Check styles

Runs go vet and lint in parallel

make checks

Deploy example

Deploys in AWS a lambda function wrapped by tracer and prints tracing in logs (stdout):

export AWS_PROFILE=<your-profile>
make deploy-example

After you finished testing just destroy the AWS infrastructure resources for Lambda:

export AWS_PROFILE=<your-profile>
make destroy-example

Releases

Everytime we merge in master we push a new release version. Based on the semantic versioning we use the follow format:

Patch Release

Example commit message:

patch: fix a buf for spans

Minor Release

Example commit message:

minor: add a feature for tracking http

Major Release

Example commit message:

major: upgrade telemetry sdk

After merging, a new tag will be pushed on the previous available version. IN parallel a Github Release will be pushed automatically.

Documentation

Index

• Constants
• Variables
• func NewTracer(ctx context.Context, cfg Config, payload json.RawMessage) (retTracer *tracer, err error)
• func WrapHandler(handler interface{}, conf *Config) interface{}
• type Config
• type Exporter
  • func (e *Exporter) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error
  • func (e *Exporter) Shutdown(ctx context.Context) error
• type Transport
  • func NewTransport(transport http.RoundTripper) *Transport
  • func (t *Transport) RoundTrip(req *http.Request) (resp *http.Response, err error)

Constants

const SPANS_DIR = "/tmp/lumigo-spans"

Variables

var ErrInvalidToken = errors.New("invalid Token. Go to Lumigo Settings to get a valid token")

ErrInvalidToken an error about a missing token

Functions

func NewTracer

func NewTracer(ctx context.Context, cfg Config, payload json.RawMessage) (retTracer *tracer, err error)

func WrapHandler

func WrapHandler(handler interface{}, conf *Config) interface{}

WrapHandler wraps the lambda handler

Types

type Config

type Config struct {

	// Token is used to interact with Lumigo API
	Token string

	// PrintStdout prints in stdout
	PrintStdout bool
	// contains filtered or unexported fields
}

Config describes the struct about the configuration of the wrap handler for tracer

type Exporter

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

Exporter exports OpenTelemetry data to Lumigo.

func (*Exporter) ExportSpans

func (e *Exporter) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error

ExportSpans writes spans in json format to file.

func (*Exporter) Shutdown

func (e *Exporter) Shutdown(ctx context.Context) error

Shutdown is called to stop the exporter, it preforms no action.

type Transport

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

func NewTransport

func NewTransport(transport http.RoundTripper) *Transport

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (resp *http.Response, err error)