{"id":13414139,"url":"https://github.com/sinhashubham95/go-actuator","last_synced_at":"2026-01-15T22:53:17.423Z","repository":{"id":40948487,"uuid":"386849365","full_name":"sinhashubham95/go-actuator","owner":"sinhashubham95","description":"Golang production-ready features","archived":false,"fork":false,"pushed_at":"2022-06-22T06:59:02.000Z","size":110,"stargazers_count":15,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-07-31T20:53:34.042Z","etag":null,"topics":["gin","go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sinhashubham95.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-07-17T05:47:50.000Z","updated_at":"2024-02-25T08:13:40.000Z","dependencies_parsed_at":"2022-08-27T21:50:41.260Z","dependency_job_id":null,"html_url":"https://github.com/sinhashubham95/go-actuator","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhashubham95%2Fgo-actuator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhashubham95%2Fgo-actuator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhashubham95%2Fgo-actuator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinhashubham95%2Fgo-actuator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sinhashubham95","download_url":"https://codeload.github.com/sinhashubham95/go-actuator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243642090,"owners_count":20323954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gin","go","golang"],"created_at":"2024-07-30T20:01:58.923Z","updated_at":"2026-01-15T22:53:17.409Z","avatar_url":"https://github.com/sinhashubham95.png","language":"Go","funding_links":[],"categories":["Utilities","公用事业公司","Utility"],"sub_categories":["Utility/Miscellaneous","实用程序/Miscellaneous","Fail injection","HTTP Clients"],"readme":"# GO Actuator\n\n[![GoDoc](https://godoc.org/github.com/sinhashubham95/go-actuator?status.svg)](https://pkg.go.dev/github.com/sinhashubham95/go-actuator)\n[![Release](https://img.shields.io/github/v/release/sinhashubham95/go-actuator?sort=semver)](https://github.com/sinhashubham95/go-actuator/releases)\n[![Report](https://goreportcard.com/badge/github.com/sinhashubham95/go-actuator)](https://goreportcard.com/report/github.com/sinhashubham95/go-actuator)\n[![Coverage Status](https://coveralls.io/repos/github/sinhashubham95/go-actuator/badge.svg?branch=master)](https://coveralls.io/github/sinhashubham95/go-actuator?branch=master)\n[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#utilities)\n\nGO actuator configures the set of actuator endpoints for your application. It is very extensible and can be configured with `Go's native HTTP Server Mux`, or with any `3rd party web framework` as well.\n\n## Project Versioning\n\nGo actuator uses [semantic versioning](http://semver.org/). API should not change between patch and minor releases. New minor versions may add additional features to the API.\n\n## Installation\n\nTo install `Go Actuator` package, you need to install Go and set your Go workspace first.\n\n1. The first need Go installed (version 1.18+ is required), then you can use the below Go command to install Go Actuator.\n\n```shell\ngo get github.com/sinhashubham95/go-actuator\n```\n\n2. Import it in your code:\n\n```go\nimport \"github.com/sinhashubham95/go-actuator\"\n```\n\n## How to Use\n\nThe actuator library exposes a plain native handler function, and it is the responsibility of the application to put this handler to use. This can be used either directly with `Go's native HTTP Server Mux`, or with any `3rd party web framework` as well.\n\n### Configuration\n\nThe configuration contains the following:-\n\n1. **Endpoints** - This is the list of endpoints which will be enabled. This is not a mandatory parameter. If not provided, then only `info` and `ping` endpoints will be enabled. The possible endpoints are - `/env`, `/info`, `/health`, `/metrics`, `/ping`, `/shutdown` and `/threadDump`. You can find the description of each of these endpoints below.\n2. **Env** - This is the environment where the application is running. For example, `dev`, `stg`, `prod`, etc.\n3. **Name** - This is the name of the application which is using this actuator library.\n4. **Port** - This is the port where the application is running.\n5. **Version** - This is the current application version.\n6. **Health** - This is used to provide a set of health checkers to derive the health of an application using its dependencies, some of which might be mandatory and some non-mandatory, which helps maintain a robust eye on the application.\n\n```go\nimport actuator \"github.com/sinhashubham95/go-actuator\"\n\nconfig := \u0026actuator.Config{\n\tEndpoints: []int{\n\t\tactuator.Env,\n\t\tactuator.Info,\n\t\tactuator.Metrics,\n\t\tactuator.Ping,\n\t\tactuator.Shutdown,\n\t\tactuator.ThreadDump,\n    },\n    Env: \"dev\",\n    Name: \"Naruto Rocks\",\n    Port: 8080,\n    Version: \"0.1.0\",\n}\n```\n\n### Using with [Go's Native Server Mux](https://pkg.go.dev/net/http)\n\n```go\nimport (\n    actuator \"github.com/sinhashubham95/go-actuator\"\n    \"net/http\"\n)\n\n// create a server\nmux := \u0026http.ServeMux{}\n\n// get the handler for actuator\nactuatorHandler := actuator.GetActuatorHandler(\u0026actuator.Config{})\n// configure the handler at this base endpoint\nmux.Handle(\"/actuator\", actuatorHandler)\n\n// configure other handlers\n....\n```\n\n### Using with [Fast HTTP](https://github.com/valyala/fasthttp)\n\n```go\nimport (\n\t\"strings\"\n\t\n    \"github.com/valyala/fasthttp\"\n    actuator \"github.com/sinhashubham95/go-actuator\"\n)\n\n// get the handler for actuator\nactuatorHandler := fasthttp.NewFastHTTPHandlerFunc(actuator.GetActuatorHandler(\u0026actuator.Config{}))\n\n// create a fast http handler\nhandler := func(ctx *fasthttp.RequestCtx) {\n    if strings.HasPrefix(ctx.Path(), \"/actuator\") {\n        // use the actuator handler\n    \tactuatorHandler(ctx)\n    \treturn\n    }\n    // other request handler calls\n}\nfasthttp.ListenAndServe(\":8080\", handler)\n```\n\n### Using with [GIN](https://github.com/gin-gonic/gin)\n\n```go\nimport (\n    \"github.com/gin-gonic/gin\"\n    actuator \"github.com/sinhashubham95/go-actuator\"\n\t\"github.com/sinhashubham95/go-actuator/models\"\n)\n\n// create the gin engine\nengine := gin.Default()\n\n// get the handler for actuator\nactuatorHandler := actuator.GetActuatorHandler(\u0026actuator.Config{})\nginActuatorHandler := func(ctx *gin.Context) {\n\tactuatorHandler(ctx.Writer, ctx.Request)\n}\n\nengine.GET(\"/actuator/*endpoint\", ginActuatorHandler)\n```\n\n### Using with [Hertz](https://github.com/cloudwego/hertz)\n\n```go\nimport (\n    \"context\"\n    \"github.com/cloudwego/hertz/pkg/app\"\n    \"github.com/cloudwego/hertz/pkg/app/server\"\n    \"github.com/cloudwego/hertz/pkg/common/adaptor\"\n    \"github.com/sinhashubham95/go-actuator\"\n)\n\nvar actuatorHandler = actuator.GetActuatorHandler(\u0026actuator.Config{})\n\nfunc handleActuator(ctx context.Context, c *app.RequestContext) {\n\trequest, err := adaptor.GetCompatRequest(\u0026c.Request)\n\tif err != nil {\n        c.Status(http.StatusInternalServerError)\n\t\treturn\n\t}\n\tresponse := adaptor.GetCompatResponseWriter(\u0026c.Response)\n\tactuatorHandler(response, request)\n}\n\ns := server.Default()\ns.Any(\"/actuator/*any\", handleActuator)\n```\n\n## Endpoints\n\n### Env - `/actuator/env`\n\nThis is used to get all the environment variables for the runtime where the application is running. Note that to use this, you need to pass the runtime environment as an application flag as follows.\n\n```shell\ngo build\n./${APPLICATION_NAME}\n```\n\n```json\n{\n  \"env_key_1\": \"env_value_1\",\n  \"env_key_2\": \"env_value_2\"\n}\n```\n\n### Info - `/actuator/info`\n\nThis is used to get the basic information for an application. To get the correct and relevant information for your application you need to change the build script as well as the run script for your application as follows.\n\n```shell\nbuildStamp=$(date -u '+%Y-%m-%d_%I:%M:%S%p')\ncommitId=$(git rev-list -1 HEAD)\ncommitTime=$(git show -s --format=%ci \"$commitId\")\ncommitAuthor=$(git --no-pager show -s --format='%an \u003c%ae\u003e' \"$commitId\")\ngitUrl=$(git config --get remote.origin.url)\nuserName=$(whoami)\nhostName=$(hostname)\ngo build -ldflags \"\u003cother linking params\u003e -X github.com/sinhashubham95/go-actuator.BuildStamp=$buildStamp -X github.com/sinhashubham95/go-actuator.GitCommitID=$commitId -X github.com/sinhashubham95/go-actuator.GitPrimaryBranch=$2 -X github.com/sinhashubham95/go-actuator.GitURL=$gitUrl -X github.com/sinhashubham95/go-actuator.Username=$userName -X github.com/sinhashubham95/go-actuator.HostName=$hostName  -X \\\"github.com/sinhashubham95/go-actuator.GitCommitTime=$commitTime\\\" -X \\\"github.com/sinhashubham95/go-actuator.GitCommitAuthor=$commitAuthor\\\"\"\n./${APPLICATION_NAME}\n```\n\n```json\n{\n  \"application\": {\n    \"env\": \"ENVIRONMENT\",\n    \"name\": \"APPLICATION_NAME\",\n    \"version\": \"APPLICATION_VERSION\"\n  },\n  \"git\": {\n    \"username\": \"\",\n    \"hostName\": \"\",\n    \"buildStamp\": \"\",\n    \"commitAuthor\": \"Shubham Sinha \",\n    \"commitId\": \"\",\n    \"commitTime\": \"\",\n    \"branch\": \"\",\n    \"url\": \"\",\n    \"startupStamp\": \"\"\n  },\n  \"runtime\": {\n    \"arch\": \"\",\n    \"os\": \"\",\n    \"port\": 8080,\n    \"runtimeVersion\": \"\"\n  }\n}\n```\n\n### Health - `/actuator/health`\n\nThis is used to provide the most health of an application, validating the underlying dependencies, via the various health checks.\n\nThese health checks might be costly to the application. That's why there is an additional cache which is implemented internally for the same. A successful health check is cached for the provided cache duration(described below). During this duration, the same cached health check will be provided as part of the response.\n\nThe health check can be configured with the following set of details, which needs to be provided only if the `Health` endpoint is enabled.\n1. **CacheDuration** - This is an optional parameter, which defines the duration for which the health check once performed will be served from cache if success. The default value is 1 hour.\n2. **Timeout** - This is an optional parameter, which signifies the time within which the health check should be completed. The context passed in the health check functions, will cancel post this time duration. The implementation of the health check function should honour the context cancellation.\n3. **Checkers** - These are the set of dependencies of the application which needs to be validated as part of the health check. Each health checker can have the following set of configurations.\n   1. **Key** - This is the unique key which can identify the dependency of this application uniquely.\n   2. **Func** - This is the implementation function which will be called as part of the health check.\n   3. **IsMandatory** - This tells whether this dependency is a mandatory dependency for this application or not. If this value is set to false, even if the provided health check function fails, it won't fail the overall health check.\n\n```go\nimport \"github.com/sinhashubham95/go-actuator\"\n\ncfg := \u0026actuator.Config{\n\tEndpoints: []int{actuator.Health},\n    Health: \u0026actuator.HealthConfig{\n\t\tCheckers: []actuator.HealthChecker{\n\t\t    {\n\t\t\t    Key: \"test1\",\n\t\t\t\tFunc: func(ctx context.Context) error {\n\t\t\t\t\t// validate connectivity to database\n\t\t\t\t\t// or validate connectivity to redis\n\t\t\t\t\t// or validate downstream api service\n\t\t\t\t\t// etc\n                },\n\t\t\t\tIsMandatory: true,\n            },\n        },\n    },\n}\n```\n\n```json\n{\n  \"test1\": {\n    \"key\": \"test1\",\n    \"isMandatory\": false,\n    \"success\": false,\n    \"error\": \"some error\"\n  },\n  \"test2\": {\n    \"key\": \"test1\",\n    \"isMandatory\": true,\n    \"success\": true\n  }\n}\n```\n\n### Metrics - `/actuator/metrics`\n\nThis is used to get the runtime memory statistics for your application. You can find the definition of each of the fields [here](./models/memStats.go).\n\n```json\n{\n  \"alloc\": 2047816,\n  \"totalAlloc\": 2850832,\n  \"sys\": 73942024,\n  \"lookups\": 0,\n  \"mAllocations\": 15623,\n  \"frees\": 9223,\n  \"heapAlloc\": 2047816,\n  \"heapSys\": 66551808,\n  \"heapIdle\": 62832640,\n  \"heapInUse\": 3719168,\n  \"heapReleased\": 62570496,\n  \"heapObjects\": 6400,\n  \"stackInUse\": 557056,\n  \"stackSys\": 557056,\n  \"mSpanInUse\": 81056,\n  \"mSpanSys\": 81920,\n  \"MCacheInUse\": 19200,\n  \"mCacheSys\": 32768,\n  \"buckHashSys\": 1446250,\n  \"gcSys\": 4225056,\n  \"otherSys\": 1047166,\n  \"nextGC\": 4194304,\n  \"lastGC\": 1627102938524536000,\n  \"pauseTotalNs\": 35655,\n  \"pauseNs\": [\n    35655\n  ],\n  \"pauseEnd\": [\n    1627102938524536000\n  ],\n  \"numGC\": 1,\n  \"numForcedGC\": 0,\n  \"gcCPUFraction\": 0.000005360999257331059,\n  \"enableGC\": true,\n  \"debugGC\": false,\n  \"BySize\": [\n    {\n      \"Size\": 0,\n      \"MAllocations\": 0,\n      \"Frees\": 0\n    }\n  ]\n}\n```\n\n### Ping - `/actuator/ping`\n\nThis is the lightweight ping endpoint that can be used along with your load balancer. This is used to know the running status of your application.\n\n### Shutdown - `/actuator/shutdown`\n\nThis is used to bring the application down.\n\n### Thread dump - `/actuator/threadDump`\n\nThis is used to get the trace of all the goroutines.\n\n```text\ngoroutine profile: total 1\n1 @ 0x103af45 0x10337fb 0x10688f5 0x10c4de5 0x10c58b5 0x10c5897 0x1117e0f 0x1124391 0x11355e8 0x113576f 0x12037a5 0x1203676 0x1217025 0x1217007 0x121db9a 0x121e5b5 0x106e3e1\n#\t0x10688f4\tinternal/poll.runtime_pollWait+0x54\t\t\t\t/Users/s0s01qp/go/go1.16.6/src/runtime/netpoll.go:222\n#\t0x10c4de4\tinternal/poll.(*pollDesc).wait+0x44\t\t\t\t/Users/s0s01qp/go/go1.16.6/src/internal/poll/fd_poll_runtime.go:87\n#\t0x10c58b4\tinternal/poll.(*pollDesc).waitRead+0x1d4\t\t\t/Users/s0s01qp/go/go1.16.6/src/internal/poll/fd_poll_runtime.go:92\n#\t0x10c5896\tinternal/poll.(*FD).Read+0x1b6\t\t\t\t\t/Users/s0s01qp/go/go1.16.6/src/internal/poll/fd_unix.go:166\n#\t0x1117e0e\tnet.(*netFD).Read+0x4e\t\t\t\t\t\t/Users/s0s01qp/go/go1.16.6/src/net/fd_posix.go:55\n#\t0x1124390\tnet.(*conn).Read+0x90\t\t\t\t\t\t/Users/s0s01qp/go/go1.16.6/src/net/net.go:183\n#\t0x11355e7\tbufio.(*Reader).fill+0x107\t\t\t\t\t/Users/s0s01qp/go/go1.16.6/src/bufio/bufio.go:101\n#\t0x113576e\tbufio.(*Reader).Peek+0x4e\t\t\t\t\t/Users/s0s01qp/go/go1.16.6/src/bufio/bufio.go:139\n#\t0x12037a4\tgithub.com/valyala/fasthttp.(*RequestHeader).tryRead+0x64\t/Users/s0s01qp/go/pkg/mod/github.com/valyala/fasthttp@v1.28.0/header.go:1520\n#\t0x1203675\tgithub.com/valyala/fasthttp.(*RequestHeader).readLoop+0x55\t/Users/s0s01qp/go/pkg/mod/github.com/valyala/fasthttp@v1.28.0/header.go:1506\n#\t0x1217024\tgithub.com/valyala/fasthttp.(*RequestHeader).Read+0x1ae4\t/Users/s0s01qp/go/pkg/mod/github.com/valyala/fasthttp@v1.28.0/header.go:1497\n#\t0x1217006\tgithub.com/valyala/fasthttp.(*Server).serveConn+0x1ac6\t\t/Users/s0s01qp/go/pkg/mod/github.com/valyala/fasthttp@v1.28.0/server.go:2112\n#\t0x121db99\tgithub.com/valyala/fasthttp.(*workerPool).workerFunc+0xb9\t/Users/s0s01qp/go/pkg/mod/github.com/valyala/fasthttp@v1.28.0/workerpool.go:223\n#\t0x121e5b4\tgithub.com/valyala/fasthttp.(*workerPool).getCh.func1+0x34\t/Users/s0s01qp/go/pkg/mod/github.com/valyala/fasthttp@v1.28.0/workerpool.go:195\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinhashubham95%2Fgo-actuator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsinhashubham95%2Fgo-actuator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinhashubham95%2Fgo-actuator/lists"}