Description
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 packagepowertoolsor multiple packages in one project (likepowertools,powertoolsmetricsetc). - APIs for the core packages