alibaba/sentinel-golang: flow control and circuit breaking for Go services

What Sentinel Go actually guards against

The README frames the project around one idea: "flow" as the breakthrough point. Everything else follows from that. Sentinel Go is a Go library that sits inside your process and decides, per request, whether the request should proceed. It covers flow control, traffic shaping, concurrency limiting, circuit breaking and system adaptive overload protection. Those are five different failure modes, and they are worth separating. Flow control caps how many requests pass in a window. Concurrency limiting caps how many are in flight at once, which matters when downstream latency rises and goroutines pile up. Circuit breaking stops calling a dependency that is already failing. System adaptive overload protection watches machine-level signals and sheds load before the process falls over.

The intended user is a Go service author in a microservice topology. The README says the project has been used at Alibaba and covered core scenarios in Double-11 shopping festivals, including burst traffic limiting and circuit breaking for unreliable downstream services. That is a claim about the origin of the design, not a benchmark you can reproduce, and it is worth reading that way. The practical question for an adopter is narrower: do you have Go services where a slow downstream or a traffic spike can take down the caller, and do you want the mitigation in-process rather than in a proxy? If yes, this is the right shape of tool.

How the resource, entry and rule model fits together

Sentinel Go is built around resources. A resource is a named thing you want to protect, usually a function call or an outbound dependency. Around that name you attach rules, and the library evaluates those rules each time the resource is entered. The repository layout reflects this: api/ holds the interfaces, core/ holds the rule evaluation and statistics machinery, ext/ holds optional pieces, exporter/ holds metrics export, and logging/ holds the logger. If you want to know whether a feature is part of the core contract or an add-on, that directory split is the fastest way to find out.

The data flow is local first. Rules are loaded into the process, statistics are accumulated in the process, and decisions are made in the process. Nothing in the README describes a control plane that must be reachable for enforcement to work, which is a meaningful property: a network partition does not stop your rate limiting. The trade-off is equally real. Rule state lives per instance unless you push it from outside, so a fleet of N pods has N independent counters. If your limit is meant to be global across the fleet, in-process counting will not give you that, and the README does not present distributed coordination as a core feature.

Dynamic configuration is handled by a separate set of modules. The README points to "Sentinel Go dynamic data-source modules" as a sub-project, and go.mod shows the dependencies that support this: fsnotify for file watching and yaml.v2 for parsing. That combination suggests the intended pattern is rules stored in a file that the library watches and reloads, rather than rules fetched from a remote service. The README does not document rollback behaviour when a reloaded rule set is invalid, so treat that as something to verify against the source before you depend on it.

Installing Sentinel Go and running a first flow rule

The module path is github.com/alibaba/sentinel-golang, and go.mod declares go 1.18 as the minimum. The repository ships runnable examples under example/, and the flow example is the shortest path to a working setup. Clone the repository and run it from the module root so the internal imports resolve:

git clone https://github.com/alibaba/sentinel-golang.git
cd sentinel-golang
go run ./example/flow

The example programs load rules and enter a resource, printing whether each call was allowed or blocked. Read example/flow/main.go alongside the output; the rule struct fields are what you will be editing in your own service. The other example directories map to the other capabilities: example/circuitbreaker, example/hotspot_param_flow, example/isolation and example/outlier. Running each one is a faster orientation than reading the wiki top to bottom, because the examples compile against the current master rather than against the last release tag.

For production use, the pattern the README describes is to keep rules outside the binary. The dynamic data-source modules, backed by fsnotify and yaml.v2 in go.mod, are the documented route. The README does not give a full YAML schema, so take the structure from the data-source module source rather than guessing at key names.

Where in-process enforcement stops being the right answer

The clearest limitation is scope. Sentinel Go is a Go library. If your fleet includes Java, Python or Node services, you are not protecting them with this repository, and the README's own sub-project list points at separate adapters rather than a language-neutral agent. Teams that want one policy across many runtimes should be looking at a proxy or a service mesh, where enforcement happens outside the process. Sentinel Go will not do that job, and trying to make it do so means rebuilding the control plane yourself.

The second limitation is release cadence. The most recent release listed is v1.0.4 from 2022-01-07, with v1.0.3 in 2021 and v1.0.2 in 2021. The repository is not archived, and the last push to the default branch was on 2026-07-02, so work has continued on master. But an adopter pinning to a tagged release is pinning to code that is several years old. That gap between tags and branch commits is the single thing I would resolve before writing Sentinel Go into an architecture document. Either you track master, which means tracking unreleased behaviour, or you pin v1.0.4, which means accepting whatever has been fixed since.

Third, the README is thin on operational detail. It documents the feature list and points to the wiki for full documentation, but the README itself does not describe rule persistence, rollback of bad rule sets, or what happens to in-flight statistics when rules change. Those are exactly the questions that come up during an incident.

Sentinel Go compared with Hystrix-go

Hystrix-go is the other Go library people reach for in this space, and the two take different positions. Hystrix-go is centred on the circuit breaker and the command pattern: you wrap a call in a command, and the library tracks success and failure to decide whether to open the circuit. Its model is about isolating one dependency call. Sentinel Go starts from flow instead, and treats the circuit breaker as one of several rule types alongside flow control, concurrency limiting and system adaptive overload protection. The entry point is a named resource rather than a command wrapper, and the metrics and rule machinery are shared across all rule types.

The practical difference shows up when you need more than a breaker. If your only requirement is "stop calling this dependency when it fails," Hystrix-go's narrower surface is easier to reason about. If you also need to cap concurrency, shape burst traffic, or shed load based on machine state, Sentinel Go covers those in one library with one configuration path, which avoids running two overlapping mechanisms in the same process. The cost is a larger API and more concepts to learn before your first rule works.

One thing neither approach gives you is cross-language policy. Both are Go libraries, so a polyglot fleet still needs a proxy layer if the goal is uniform enforcement.

Licence and the cost of staying current

Sentinel Go is licensed under Apache-2.0, and the LICENSE file sits at the repository root. Apache-2.0 includes an express patent grant and permits commercial use, modification and redistribution provided you keep the licence and notice files. That is the standard permissive position and it is unlikely to be the deciding factor in an adoption review. I am not a lawyer and this is not legal advice; if your organisation has a licence review process, the file to hand over is LICENSE.

Upgrade cost is the more interesting question here. Because the release tags stop at v1.0.4 from 2022-01-07 while commits continued on master through 2026-07-02, the upgrade path is not a sequence of small tagged jumps. You are choosing between a stable but old tag and a moving branch. The go.mod requires go 1.18, so the toolchain floor is modest, and the direct dependency list is short: fsnotify, google/uuid, pkg/errors, prometheus/client_golang, gopsutil, testify, multierr and yaml.v2. A short direct dependency list keeps the transitive upgrade surface smaller than it would be for a framework-scale library, which is a genuine point in its favour for teams with strict dependency policies. The indirect list in go.mod is longer, as it usually is, and includes the usual protobuf and golang.org/x entries.

Editorial conclusion

Adopt Sentinel Go if you write Go services and want flow control, concurrency limiting and circuit breaking inside the process, configured either in code or through the dynamic data-source modules. Do not adopt it if you need a traffic proxy that works for services in other languages, or if you expect frequent tagged releases: the newest release listed is v1.0.4 from 2022-01-07. Before you commit, read example/flow and example/circuitbreaker in the repository, confirm whether the feature you need sits behind the ext/ module boundary, and check the commits on master after 2026-07-02 rather than assuming the release tags describe the current code.

Frequently asked questions

Official sources

1. alibaba/sentinel-golang on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases