Go kit: the road ahead

[peterbourgon]

Go kit: the road ahead

• This is a tracking issue for broad changes to the Go kit project
• Expect edits and updates
• No ETA at this time

Context

• The microservices ecosystem has matured since Go kit's introduction
• Many responsibilities have, sensibly, moved to the platform/infrastructure
• Go kit has, accordingly, reduced its scope of responsibilities in practice
• Go kit is less about specific components or integrations, more about good application architecture
• The next iteration of the project should reflect this reality
• Keep and refocus on the good and useful parts, deprecate the less-useful parts

Keep

• package transport - necessary and valuable
• package endpoint - required for service/transport interop, pending generics
• package log - has clearly proved its value in the test of time
• package tracing - has also proved its value
• package examples - move to new or individual repos

Undecided

• package metrics - pending broader re-think and refactor
• kitgen - ownership is unclear
• package auth - I can't easily judge usefulness; seeking comment

Sunset

• package ratelimit - less useful in modern platforms, easy to bolt-on with generic middleware
• package circuitbreaker - less useful in modern platforms, easy to bolt-on with generic middleware
• package sd - less useful in modern platforms, many test flakes, a maintenance headache

Additional changes

• Rewrite website with new focus on architectural design and best practice
• New, expanded tutorial(s) based on lessons learned in my consulting work

Coda: repos

• One option is to break each package (or package-group) into its own repo under the go-kit org
• Another is to retain the existing kit repo, and use version tagging
• The latter is slightly more appealing to me, for continuity and visibility reasons

Coda: generics

• Generics, if/when they come, will change relationship between transport and service
• I expect the endpoint layer will no longer be necessary
• It's too early to say more

Errata

• Do transport- and service-level errors need to be kept so distinct? #807

[sagikazarmark]

package metrics - pending broader re-think and refactor

With OpenCensus and OpenTelemetry the abstraction is kinda moved to the platform layer. I would say the same is true for tracing.

package auth - I can't easily judge usefulness; seeking comment

I think the implemented auth methods are useful, but need a bit of work. They are also great reference implementations for how auth in a go-kit environment should work. Since auth (sadly) is rarely as simple as basic auth or JWT, chances are people will use customized versions (for example I extended the jwt package with additional token validation).

Do transport- and service-level errors need to be kept so distinct?

This is a huge pain point for me. Not the separation of transport and service level errors, but the fact that the way they are handled is quite inconsistent.

Service level errors are supposed to be encoded by the transport's response encoder, transport level errors are usually encoded by a dedicated error encoder (at least in case of the HTTP server). There is another dimension of errors as well: errors that are "internal" and errors returned to the caller. Both sources (service, transport) can produce both types of errors, but they are "handled" (logged or returned to the caller) separately.

Furthermore, server level error handlers (a third way of error handling, where I usually want to log fatal, internal errors only) receive both encoding/decoding errors (which are still transport errors, but not originated from endpoints, so I guess they are a third type of errors?) and transport level errors returned from endpoints.

The way I see it, errors are either returned to the caller (usually not logged, because they are business/client errors) or logged (and the caller receives a generic "internal" error). Both service and transport level can produce both types of errors.

I opened a separate issue with an example: #923

[basvanbeek]

Disagree with punting native tracing plugability for standard OTel middleware. OTel is a giant shitshow so far.

[sagikazarmark]

TBH I've seen more marketing than actually working features so far, so moving towards OTel might indeed be a bad idea at this point. Just wanted to point out that tracing and metrics packages might both get deprecated over time in favor of solutions like OpenCensus or OpenTelemetry.

[basvanbeek]

They won't because the abstractions made are often political compromises and not based on actual value. As an example the Zipkin native ecosystem is very extensive, well tested and continues to be under active development. Having Go kit native tracing abstractions allows for better granularity and consistency across different transports within Go kit as well as better interop in brown field. Even if using OTel there is a place for Go kit native hooks and logic.

[sagikazarmark]

Okay, I think I've just understood that the tracing abstraction layer is actually just integrations for different tracing frameworks, while the metrics package actually provides a separate abstraction layer. I was confused why those two would be treated differently, but I guess having integrations with different systems makes sense.

[yiv]

How to understand "I expect the endpoint layer will no longer be necessary"

[ppipada]

package examples - move to new or individual repos

go modules supports multiple modules per repository. Can we consider examples being a sub module that depends on the go-kit main module? A pain point when doing this is adding versions to individual modules separately. But for examples package it could be fine.

[sagikazarmark]

Here is a Go kit example with the latest generics proposal: https://go2goplay.golang.org/p/vpUyP0j6cwH

Update: new version reflecting the latest proposal: https://go2goplay.golang.org/p/3wpdReO7leW

[mcesar]

Here is a Go kit example with the latest generics proposal: https://go2goplay.golang.org/p/vpUyP0j6cwH

I fiddled a little bit with the example in order to use a service interface and to highlight the code that can be generated by a tool:
https://go2goplay.golang.org/p/HcHSbBHAVd4

[monmohan]

Sunset
package ratelimit - less useful in modern platforms, easy to bolt-on with generic middleware

I think one of the reasons is that in practice, with microservices, per-node fine-grained rate limiting is rarely used (as with https://godoc.org/golang.org/x/time/rate ) . Additionally depending on one's infrastructure, it could be challenging to implement token bucket (or leaky bucket) with their fixed rate token addition requirement. When doing global rate limiting (needed for pretty much any real world use case), latency and storage overhead per request, are important constraints at scale.

In our org, we use this implementation, https://github.com/monmohan/rate-limiting and it has worked really well for us. We handle ~400K rpm traffic consistently with this rate limiter with extremely low overhead. Its based on a report by Cloudflare, where they use this implementation to handle a tonne of traffic (way higher than ours)

IMHO, One option is that the go-kit package should contain a real world production ready rate-limiter. Another option is to have a separate project where some of these real-world "third-party" packages are kept. Users of go-kit can pick and chose them as bolt-on middleware

M

[sev3ryn]

my 5 cents here - I believe package log should be separated to its own repo. Its imported by external projects much more than other packages from go-kit. But right now importing just log package adds lots of unwanted entries to go.sum which is quite bothering for everyone who care about "dependency hygiene".

E.g. see related issue from Prometheus (who is user of kit/log package) prometheus/common#255

[peterbourgon]

We will probably extract log to its own package, but two notes about your comment:

• Importing go-kit/kit/log does bring in the whole Go kit module as a dependency, but your compiled artifact should only include the specific packages you use, so it's not really an issue at that level
• go.sum is an append-only log of checksums used to verify module integrity in general, it really has no relationship to the actual dependencies of a module or dependency hygiene, as a user you should just ignore it

[sagikazarmark]

but your compiled artifact should only include the specific packages you use, so it's not really an issue at that level

True, but there are two major issues with Go modules dependencies download:

• Packages without go.mod are always downloaded, no matter what (even if they won't be in the resulting binary)
• go mod download downloads everything. It is commonly used for populating caches (eg. in docker builds)

These two can dramatically increase build times and affect a lot of users.