RFC: Golang Support

[thomasklinger1234]

Key information

• RFC PR: (leave this empty)
• Related issue(s), if known:
• Area: (i.e. Tracer, Metrics, Logger, etc.) Tracer, Metrics, Logger, Batch
• Meet tenets: Yes
• Approved by: ''
• Reviewed by: ''

Summary

Add support for Golang to make the awesome powertools ecosystem available to Go developers.

Motivation

As Go developers, we currently cannot benefit from the powertools, thus needing to re-implement the same functionality over and over. I have an internal implementation already setup but would like to contribute it to the wider community.

Proposal

This is the bulk of the RFC.

Explain the design in enough detail for somebody familiar with Powertools to understand it, and for somebody familiar with the implementation to implement it.

If this feature should be available in other runtimes (e.g. Java), how would this look like to ensure consistency?

User Experience

How would customers use it?

First, install the dependency via

go get github.com/awslabs/aws-lambda-powertools-go

Next step would be to have a Lambda handler wrapper (similar to the @Logging/@Metrics annotations for Java or the context managers for Python) to run some preprocessing / setup based on the POWERTOOLS_ environment variables.

package main 

import (
    "github.com/aws/aws-lambda-go/pkg/powertools"
        "github.com/awslabs/aws-lambda-powertools-go"
)

type input struct{}
type output struct{}

func handleRequest(ctx context.Context, event input) (output, error) {
    res, err := doSomething()
    return res, err
}

func main() {
   // create a new wrapper accepting the actual Lambda handler as the first parameter
   handler := powertools.NewLambdaHandler(handleRequest)
   lambda.Start(handler.HandleRequest)
}

The LambdaHandler definition could look something like this

type LambdaHandler struct {
   handlerFunc interface{}
}

func (h *LambdaHandler) HandleRequest(ctx context.Context, event interface{}) (interface{}, error) {
    // setup some internal settings
    ....
    // run middlewares
    ....
    // run the actual handler
    res, err := h.handlerFunc(ctx, event)
    // do some post-processing like logging output etc
    ....
    return res, err
}

Developers also want to use the Logger, Tracer and Metrics capabilities to enhance their experience.

Logger

The Logger capability will provide a standard logging facade with structured log support and leveled logging.

var logger = powertoolslog.NewLogger()

func operation() {
    logger.AppendKey("event_id", "1234")
    logger.AppendKey("event_payload", map[string]string{
      "key": "value",
      "num": 4,
    })
    logger.Info("A message!")

    powertoolslog.Info("Using the globally registered logger")
}

The output will be the same as in Powertools Python.

Metrics

The Metrics capability provides standard EMF metrics (maybe based on prozz/aws-embedded-metrics-golang.

var metricsLogger = powertoolsmetrics.NewMetricsLogger()

func operation() {
    defer metricsLogger.Log()

    metricsLogger.PutDimension("dimKey", "dimValue")
    metricsLogger.PutMetadata("metaKey", "metaValue")
    metricsLogger.PutMetric("metricName", 1, emf.Count)

    // use a context-manager like variant. will flush the logger automatically
    powertoolsmetrics.WithMetricsLogger(context.TODO(), func(ml *powertools.MetricsLogger) {
       ml.PutMetric("metric2", 1, emf.Count)
    })
}

Tracer

Tracer will provide capabilities for using X-Ray (based on aws/aws-xray-sdk-go)

func operation(ctx context.Context) {
    powertoolstracing.Capture(ctx, "operation", func(c context.Context) {
        cfg, err := config.LoadDefaultConfig(c)
        powertoolstracing.InstrumentAWSv2(&cfg)
        ssm := ssm.NewFromConfig(cfg)
        ssm.GetParameter(c, &ssm.GetParameterInput{})
    })
}

Also, the LambdaHandler will automatically setup tracing when the appropriate POWERTOOLS_ environment variables are set.

Any configuration or corner cases you'd expect?

Demonstration of before and after on how the experience will be better

• Before: No Powertools
• After: Powertools :)

Drawbacks

Why should we not do this?

Do we need additional dependencies? Impact performance/package size?

For the initial implementation (and maybe in general), we should use establishes libraries like

• Go XRay SDK for Tracing
• Zap or Logrus as logging libraries
• aws-embedded-metrics-golang as a starting point for implementing EMF

Rationale and alternatives

• What other designs have been considered? Why not them?

The design for the UX needs to be fleshed out and check if it is ideomatic enough.

• What is the impact of not doing this?

Unresolved questions

Optional, stash area for topics that need further development e.g. TBD

• Package design: Multiple distinct Go packages (similar to AWS SDK, individually go gettable), one package powertools or multiple packages in one project (like powertools, powertoolsmetrics etc).
• APIs for the core packages

[jason-riddle]

While zerolog and logrus are both excellent libraries, it would be nice if logging didn't bring in a third-party dependency.

Another package to consider is the newly proposed slog package. Parts of the slog package could be implemented for Powertools logging usage.

The proposal is available here: https://go.googlesource.com/proposal/+/master/design/56345-structured-logging.md.

[ewd-bft]

very interested in go powertools also!