Package list golang-github-go-kit-kit / 08156ec
Merge pull request #62 from go-kit/readmes More updates to READMEs Peter Bourgon 6 years ago
6 changed file(s) with 110 addition(s) and 35 deletion(s). Raw diff Collapse all Expand all
0 # gokit [![Circle CI](https://circleci.com/gh/go-kit/kit.svg?style=svg)](https://circleci.com/gh/go-kit/kit) [![Drone.io](https://drone.io/github.com/go-kit/kit/status.png)](https://drone.io/github.com/go-kit/kit/latest) [![Travis CI](https://travis-ci.org/go-kit/kit.svg?branch=master)](https://travis-ci.org/go-kit/kit) [![GoDoc](https://godoc.org/github.com/go-kit/kit?status.svg)](https://godoc.org/github.com/go-kit/kit)
0 # Go kit [![Circle CI](https://circleci.com/gh/go-kit/kit.svg?style=svg)](https://circleci.com/gh/go-kit/kit) [![Drone.io](https://drone.io/github.com/go-kit/kit/status.png)](https://drone.io/github.com/go-kit/kit/latest) [![Travis CI](https://travis-ci.org/go-kit/kit.svg?branch=master)](https://travis-ci.org/go-kit/kit) [![GoDoc](https://godoc.org/github.com/go-kit/kit?status.svg)](https://godoc.org/github.com/go-kit/kit)
11
22 **Go kit** is a **distributed programming toolkit** for microservices in the modern enterprise. We want to make Go a viable choice for application (business-logic) software in large organizations.
33
66
77 ## Motivation
88
9 See [the motivating blog post](http://peter.bourgon.org/go-kit) and [the video of the talk](https://www.youtube.com/watch?v=iFR_7AKkJFU).
9 Go has emerged as the language of the server, but it remains underrepresented
10 in large, consumer-focused tech companies like Facebook, Twitter, Netflix, and
11 SoundCloud. These organizations have largely adopted JVM-based stacks for
12 their business logic, owing in large part to libraries and ecosystems that
13 directly support their microservice architectures.
14
15 To reach its next level of success, Go needs more than simple primitives and
16 idioms. It needs a comprehensive toolkit, for coherent distributed programming
17 in the large. Go kit is a set of packages and best practices, leveraging years
18 of production experience, and providing a comprehensive, robust, and trustable
19 platform for organizations of any size.
20
21 In short, Go kit brings Go to the modern enterprise.
22
23 For more details, see
24 [the motivating blog post](http://peter.bourgon.org/go-kit) and
25 [the video of the talk](https://www.youtube.com/watch?v=iFR_7AKkJFU).
1026
1127 ## Goals
1228
1329 - Operate in a heterogeneous SOA — expect to interact with mostly non-Go-kit services
1430 - RPC as the primary messaging pattern
1531 - Pluggable serialization and transport — not just JSON over HTTP
16 - Zipkin-compatible request tracing
32 - Operate within existing infrastructures — no mandates for specific tools or technologies
1733
1834 ## Non-goals
1935
20 - Supporting messaging patterns other than RPC (in the initial release) — pub/sub, CQRS, etc.
36 - Supporting messaging patterns other than RPC (in the initial release) — MPI, pub/sub, CQRS, etc.
37 - Re-implementing functionality that can be provided by wrapping existing packages
2138 - Having opinions on deployment, orchestration, process supervision, etc.
2239 - Having opinions on configuration passing — flags, env vars, files, etc.
2340
3653 - Service discovery — pending
3754 - Example [addsvc](https://github.com/go-kit/kit/tree/master/addsvc) — **implemented**
3855
56 ### Dependency management
57
58 Users who import Go kit into their `package main` are responsible to organize
59 and maintain all of their dependencies to ensure code compatibility and build
60 reproducibility. Go kit makes no direct use of dependency management tools like
61 [Godep](https://github.com/tools/godep).
62
63 We will use a variety of continuous integration providers to find and fix
64 compatibility problems as soon as they occur.
65
3966 ## Contributing
4067
4168 Please see [CONTRIBUTING.md]. Thank you, [contributors]!
4269
4370 [CONTRIBUTING.md]: /CONTRIBUTING.md
4471 [contributors]: https://github.com/go-kit/kit/graphs/contributors
45
46 ### Dependency management
47
48 Users who import Go kit into their `package main` are responsible to organize
49 and maintain all of their dependencies to ensure code compatibility and build
50 reproducibility. Gokit makes no direct use of dependency management tools like
51 [Godep](https://github.com/tools/godep).
52
53 We will use a variety of continuous integration providers to find and fix
54 compatibility problems as soon as they occur.
5572
5673 ### API stability policy
5774
00 # addsvc
11
2 addsvc is an example service, used to illustrate the mechanics of gokit.
3 It exposes simple functionality on a variety of transports and endpoints.
2 addsvc is an example service, used to illustrate the mechanics of Go kit. It
3 exposes a single method to add two integers on a variety of transports and
4 endpoints.
5
6 ## Highlights
7
8 ### Configuration via flags
9
10 Go kit has no strong opinions about how to pass configuration to your service.
11 If your organization has established conventions to pass configuration into
12 your service, Go kit won't stand in your way. That said, package flag is a
13 good default: it's simple, well-understood, and provides a self-documenting
14 configuration surface area. Keeping with
15 [best practices](http://peter.bourgon.org/go-in-production/#configuration), flags
16 are defined in func main.
17
18 ### Declarative composition
19
20 Go kit strongly favors explicit, declarative composition of interacting
21 components via a comprehensive func main. Time spent in keystrokes is made up
22 many, many times over when returning to the code and understanding exactly
23 what's happening, without having to unravel indirections or abstractions.
24
25 ### Multiple transports
26
27 Go kit treats transports — HTTP, Thrift, gRPC, etc. — as pluggable. The same
28 service can be exposed on any, or multiple, available transports. The addsvc
29 example demonstrates how to make the same business logic available over
30 multiple transports simultaneously.
31
32 ### Daemonizing
33
34 Go kit has no strong opinions about how to daemonize, supervise, or run your
35 service. If your organization has established conventions for running
36 services. Go kit won't stand in your way. Go kit services run equally well as
37 manually-copied binaries; applications provisioned with configuration
38 management tools like [Chef][], [Puppet][], or [Ansible][]; in containers like
39 [Docker][] or [rkt][]; or as part of a comprehensive scheduling platform like
40 [Kubernetes][], [Mesos][], [OpenStack][], [Deis][], etc.
41
42 [Chef]: https://www.chef.io
43 [Puppet]: https://puppetlabs.com
44 [Ansible]: http://www.ansible.com
45 [Docker]: http://docker.com
46 [rkt]: https://github.com/coreos/rkt
47 [Kubernetes]: http://kubernetes.io
48 [Mesos]: https://mesosphere.com
49 [OpenStack]: https://www.openstack.org
50 [Deis]: http://deis.io
451
552 ## Server
653
754 To build and run addsvc,
855
956 ```
10 $ go install
11 $ addsvc
57 go install
58 addsvc
1259 ```
1360
1461 ## Client
1717
1818 // proxyAdd returns an implementation of Add that invokes a remote Add
1919 // service.
20 func proxyAdd(e endpoint.Endpoint, logger log.Logger) Add {
20 func proxyAdd(remote endpoint.Endpoint, logger log.Logger) Add {
2121 return func(ctx context.Context, a, b int64) int64 {
22 resp, err := e(ctx, reqrep.AddRequest{A: a, B: b})
22 resp, err := remote(ctx, reqrep.AddRequest{A: a, B: b})
2323 if err != nil {
2424 logger.Log("err", err)
2525 return 0
4747 thriftBufferSize = fs.Int("thrift.buffer.size", 0, "0 for unbuffered")
4848 thriftFramed = fs.Bool("thrift.framed", false, "true to enable framing")
4949
50 proxyHTTPAddr = fs.String("proxy.http.url", "", "if set, proxy requests over HTTP to this addsvc")
50 proxyHTTPURL = fs.String("proxy.http.url", "", "if set, proxy requests over HTTP to this addsvc")
5151
5252 zipkinServiceName = fs.String("zipkin.service.name", "addsvc", "Zipkin service name")
5353 zipkinCollectorAddr = fs.String("zipkin.collector.addr", "", "Zipkin Scribe collector address (empty will log spans)")
108108
109109 // Our business and operational domain
110110 var a Add = pureAdd
111 if *proxyHTTPAddr != "" {
111 if *proxyHTTPURL != "" {
112112 var e endpoint.Endpoint
113 e = httpclient.NewClient("GET", *proxyHTTPAddr, zipkin.ToRequest(zipkinSpanFunc))
113 e = httpclient.NewClient("GET", *proxyHTTPURL, zipkin.ToRequest(zipkinSpanFunc))
114114 e = zipkin.AnnotateClient(zipkinSpanFunc, zipkinCollector)(e)
115115 a = proxyAdd(e, logger)
116116 }
00 package reqrep
11
2 // The request and response types should be annotated sufficiently for all
2 // The concrete request and response types are defined for each method our
3 // service implements. Request types should be annotated sufficiently for all
34 // transports we intend to use.
45
56 // AddRequest is a request for the add method.
00 # package tracing
11
2 `package tracing` provides [Dapper-style][dapper] request tracing to services.
2 `package tracing` provides [Dapper][]-style request tracing to services.
33 An implementation exists for [Zipkin][]; [Appdash][] support is planned.
44
5 [dapper]: http://research.google.com/pubs/pub36356.html
5 [Dapper]: http://research.google.com/pubs/pub36356.html
66 [Zipkin]: https://blog.twitter.com/2012/distributed-systems-tracing-with-zipkin
77 [Appdash]: https://sourcegraph.com/blog/117580140734
88
99 ## Rationale
1010
11 TODO
11 Request tracing is a fundamental building block for large distributed
12 applications. It's instrumental in understanding request flows, identifying
13 hot spots, and diagnosing errors. All microservice infrastructures will
14 benefit from request tracing; sufficiently large infrastructures will require
15 it.
1216
1317 ## Usage
1418
15 Wrap a [server.Endpoint][] so that it emits traces to a Zipkin collector.
19 Wrap a server- or client-side [endpoint][] so that it emits traces to a Zipkin
20 collector.
1621
17 [server.Endpoint]: http://godoc.org/github.com/go-kit/kit/server#Endpoint
22 [endpoint]: http://godoc.org/github.com/go-kit/kit/endpoint#Endpoint
1823
1924 ```go
2025 func main() {
2429 scribeHost = "scribe.internal.net"
2530 timeout = 50 * time.Millisecond
2631 batchSize = 100
27 batchInterval = 3 * time.Second
32 batchInterval = 5 * time.Second
2833 )
29
3034 spanFunc := zipkin.NewSpanFunc(myHost, myMethod)
3135 collector, _ := zipkin.NewScribeCollector(scribeHost, timeout, batchSize, batchInterval)
3236
33 var e server.Endpoint
34 e = makeEndpoint() // for your service
35 e = zipkin.AnnotateEndpoint(spanFunc, collector)
37 // Server-side
38 var server endpoint.Endpoint
39 server = makeEndpoint() // for your service
40 server = zipkin.AnnotateServer(spanFunc, collector)(server)
41 go serveViaHTTP(server)
3642
37 serve(e)
43 // Client-side
44 before := httptransport.ClientBefore(zipkin.ToRequest(spanFunc))
45 var client endpoint.Endpoint
46 client = httptransport.NewClient(addr, codec, factory, before)
47 client = zipkin.AnnotateClient(spanFunc, collector)(client)
3848 }
3949 ```