README
¶
English | 中文
Introduction
The management command (admin) is the internal management background of the service. It is an additional http service provided by the framework in addition to the normal service port. Through this http interface, instructions can be sent to the service, such as viewing the log level, dynamically setting the log level, etc. The specific command See the list of commands below.
Admin is generally used to query the internal status information of the service, and users can also define arbitrary commands.
Admin provides HTTP services to the outside world using the standard RESTful protocol.
By default, the framework does not enable the admin capability and needs to be configured to start it. When generating the configuration, admin can be configured by default, so that admin can be opened by default.
server:
app: app # The application name of the business, be sure to change it to your own business application name
server: server # The process service name, be sure to change it to your own service process name
admin:
ip: 127.0.0.1 # The IP address of admin, you can also configure the network card NIC
port: 11014 # The port of admin, admin will only start when the IP and port are configured here at the same time
read_timeout: 3000 # ms. Set the timeout for accepting requests and reading the request information completely to prevent slow clients
write_timeout: 60000 # ms. Timeout for processing
List of management commands
The following commands are already built into the framework. Note: the IP:port in the commands is the address configured in the admin, not the address configured in the service.
View all management commands
curl http://ip:port/cmds
Return results
{
"cmds":[
"/cmds",
"/version",
"/cmds/loglevel",
"/cmds/config"
],
"errorcode":0,
"message":""
}
View framework version information
curl http://ip:port/version
Return results
{
"errorcode": 0,
"message": "",
"version": "v0.1.0-dev"
}
View framework log level
curl -XGET http://ip:port/cmds/loglevel?logger=xxx&output=0
Note: logger is used to support multiple logs. If not specified, it will use the default log of the framework. Output refers to different outputs under the same logger, with the array index starting at 0. If not specified, it will use the first output.
Return results
{
"errorcode":0,
"loglevel":"info",
"message":""
}
Set framework log level
(The value is the log level, and the possible values are: trace debug info warn error fatal)
curl http://ip:port/cmds/loglevel?logger=xxx -XPUT -d value="debug"
Note: The logger is used to support multiple logs. If not specified, the default log of the framework will be used. The 'output' parameter refers to different outputs under the same logger, with the array index starting at 0. If not specified, the first output will be used.
Note: This sets the internal memory data of the service and will not update the configuration file. It will become invalid after a restart.
Return results
{
"errorcode":0,
"level":"debug",
"message":"",
"prelevel":"info"
}
View framework configuration file
curl http://ip:port/cmds/config
Return results
The 'content' parameter refers to the JSON-formatted content of the configuration file.
{
"content":{
},
"errorcode":0,
"message":""
}
Customize management commands
Define a function
First, define your own HTTP interface processing function, which can be defined in any file location.
// load Trigger loading a local file to update a specific value in memory
func load(w http.ResponseWriter, r *http.Request) {
reader, err := ioutil.ReadFile("xxx.txt")
if err != nil {
w.Write([]byte(`{"errorcode":1000, "message":"read file fail"}`)) // Define error codes and error messages by yourself
return
}
// Business logic...
// Return a success error code
w.Write([]byte(`{"errorcode":0, "message":"ok"}`))
}
Register a route
Register admin in the init function or in your own internal function:
import (
"trpc.group/trpc-go/trpc-go/admin"
)
func init() {
admin.HandleFunc("/cmds/load", load) // Define the path yourself, usually under /cmds. Be careful not to duplicate, otherwise they will overwrite each other.
}
Trigger a command
Trigger the execution of a custom command
curl http://ip:port/cmds/load
Pprof performance analysis
Pprof is a built-in performance analysis tool in Go language, which shares the same port number with the admin service by default. As long as the admin service is enabled, the pprof of the service can be used.
After configuring admin, there are a few ways to use pprof:
To use pprof on a machine with a configured Go environment and network connectivity to the server
go tool pprof http://{$ip}:${port}/debug/pprof/profile?seconds=20
To download pprof files to the local machine and analyze them using local Go tools
curl http://${ip}:{$port}/debug/pprof/profile?seconds=20 > profile.out
go tool pprof profile.out
curl http://${ip}:{$port}/debug/pprof/trace?seconds=20 > trace.out
go tool trace trace.out
Memory management commands debug/pprof/heap
In addition, trpc-go will automatically remove the pprof route registered on the golang http package DefaultServeMux for you, avoiding the security issues of the golang net/http/pprof package (this is a problem of go itself).
Therefore, the service built using the trpc-go framework can directly use the pprof command, but the service started with the http.ListenAndServe("xxx", xxx) method will not be able to use the pprof command.
Perform memory analysis on intranet machines with the go command installed:
go tool pprof -inuse_space http://xxx:11029/debug/pprof/heap
go tool pprof -alloc_space http://xxx:11029/debug/pprof/heap
Documentation
¶
Overview ¶
Package admin provides management capabilities for trpc services, including but not limited to health checks, logging, performance monitoring, RPCZ, etc.
Index ¶
- Constants
- func ErrorOutput(w http.ResponseWriter, error string, code int)
- func HandleFunc(pattern string, handler http.HandlerFunc)
- type Option
- func WithAddr(addr string) Option
- func WithConfigPath(configPath string) Option
- func WithReadTimeout(readTimeout time.Duration) Option
- func WithSkipServe(isSkip bool) Option
- func WithTLS(isTLS bool) Option
- func WithVersion(version string) Option
- func WithWriteTimeout(writeTimeout time.Duration) Option
- type Server
- func (s *Server) Close(ch chan struct{}) error
- func (s *Server) HandleFunc(pattern string, handler http.HandlerFunc)
- func (s *Server) Register(serviceDesc interface{}, serviceImpl interface{}) error
- func (s *Server) RegisterHealthCheck(serviceName string) (unregister func(), update func(healthcheck.Status), err error)
- func (s *Server) Serve() error
- func (s *Server) WatchStatus(serviceName string, onStatusChanged func(healthcheck.Status))
Constants ¶
const ServiceName = "admin"
ServiceName is the service name of admin service.
Variables ¶
This section is empty.
Functions ¶
func ErrorOutput ¶
func ErrorOutput(w http.ResponseWriter, error string, code int)
ErrorOutput normalizes the error output.
func HandleFunc ¶
func HandleFunc(pattern string, handler http.HandlerFunc)
HandleFunc registers the handler function for the given pattern. Each time NewServer is called, all handlers registered through HandleFunc will be in effect. Therefore, please prioritize using Server.HandleFunc.
Types ¶
type Option ¶
type Option func(*configuration)
Option Service configuration options.
func WithAddr ¶
WithAddr returns an Option which sets the address bound to admin, default: ":9028". Supported formats: 1. :80 2. 0.0.0.0:80 3. localhost:80 4. 127.0.0.0:8001
func WithConfigPath ¶
WithConfigPath returns an Option which sets the framework configuration file path.
func WithReadTimeout ¶
WithReadTimeout returns an Option which sets read timeout.
func WithSkipServe ¶
WithSkipServe sets whether to skip starting the admin service.
func WithVersion ¶
WithVersion returns an Option which sets the version number.
func WithWriteTimeout ¶
WithWriteTimeout returns an Option which sets write timeout.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server structure provides utilities related to administration. It implements the server.Service interface.
func (*Server) HandleFunc ¶
func (s *Server) HandleFunc(pattern string, handler http.HandlerFunc)
HandleFunc registers the handler function for the given pattern.
func (*Server) RegisterHealthCheck ¶
func (s *Server) RegisterHealthCheck( serviceName string, ) (unregister func(), update func(healthcheck.Status), err error)
RegisterHealthCheck registers a new service and returns two functions, one for unregistering the service and one for updating the status of the service.
func (*Server) WatchStatus ¶
func (s *Server) WatchStatus(serviceName string, onStatusChanged func(healthcheck.Status))
WatchStatus HealthCheck proxy, registers health status watcher for service.
Source Files