trpc.group/trpc-go/trpc-go@v1.0.3/admin/README.zh_CN.md (about)

     1  [English](README.md) | 中文
     2  
     3  # 前言
     4  
     5  管理命令（admin）是服务内部的管理后台，它是框架在普通服务端口之外额外提供的 http 服务，通过这个 http 接口可以给服务发送指令，如查看日志等级，动态设置日志等级等，具体命令可以看下面的命令列表。
     6  
     7  admin 一般用于查询服务内部状态信息，用户也可以自己定义任意的命令。 
     8  
     9  admin 内部使用标准 restful 协议对外提供 http 服务。
    10  
    11  框架默认不会开启 admin 能力，需要配置才会启动（生成配置时，可以默认配置好 admin，这样就能默认打开 admin 了）：
    12  
    13  ```yaml
    14  server:
    15    app: app       # 业务的应用名，注意要改成你自己的业务应用名
    16    server: server # 进程服务名，注意要改成你自己的服务进程名
    17    admin:
    18      ip: 127.0.0.1 # admin 的 ip，配置网卡 nic 也可以
    19      port: 11014   # admin 的 port，必须同时配置这里的 ip port 才会启动 admin
    20      read_timeout: 3000 # ms. 请求被接受到请求信息被完全读取的超时时间设置，防止慢客户端
    21      write_timeout: 60000 # ms. 处理的超时时间
    22  ```
    23  
    24  # 管理命令列表
    25  
    26  框架已经内置以下命令，注意：命令中的`ip:port`是上述 admin 配置的地址，不是 service 配置的地址。
    27  
    28  ## 查看所有管理命令
    29  
    30  ```shell
    31  curl http://ip:port/cmds
    32  ```
    33  返回结果
    34  ```shell
    35  {
    36    "cmds":[
    37      "/cmds",
    38      "/version",
    39      "/cmds/loglevel",
    40      "/cmds/config"
    41    ],
    42    "errorcode":0,
    43    "message":""
    44  }
    45  ```
    46  
    47  ## 查看框架版本信息
    48  
    49  ```shell
    50  curl http://ip:port/version
    51  ```
    52  返回结果
    53  ```shell
    54  {
    55    "errorcode": 0,
    56    "message": "",
    57    "version": "v0.1.0-dev"
    58  }
    59  ```
    60  
    61  ## 查看框架日志级别
    62  
    63  ```shell
    64  curl -XGET http://ip:port/cmds/loglevel?logger=xxx&output=0
    65  ```
    66  说明：logger 是为了支持多日志，不填即为框架的 default 日志，output 同一个 logger 下的不同输出，数组下标，不填即为 0，第一个 output。
    67  
    68  返回结果
    69  ```shell
    70  {
    71    "errorcode":0,
    72    "loglevel":"info",
    73    "message":""
    74  }
    75  ```
    76  
    77  ## 设置框架日志级别
    78  
    79  (value 为日志级别，值为：trace debug info warn error fatal)
    80  ```shell
    81  curl http://ip:port/cmds/loglevel?logger=xxx -XPUT -d value="debug"
    82  ```
    83  说明：logger 是为了支持多日志，不填即为框架的 default 日志，output 同一个 logger 下的不同输出，数组下标，不填即为 0，第一个 output。
    84  
    85  注意：这里是设置的服务内部的内存数据，不会更新到配置文件中，重启即失效。
    86  
    87  返回结果
    88  ```shell
    89  {
    90    "errorcode":0,
    91    "level":"debug",
    92    "message":"",
    93    "prelevel":"info"
    94  }
    95  ```
    96  
    97  ## 查看框架配置文件
    98  
    99  ```shell
   100  curl http://ip:port/cmds/config
   101  ```
   102  返回结果
   103  
   104  content 为 json 化的配置文件内容
   105  ```shell
   106  {
   107    "content":{
   108    
   109    },
   110    "errorcode":0,
   111    "message":""
   112  }
   113  ```
   114  
   115  # 自定义管理命令
   116  
   117  ## 定义函数
   118  
   119  首先自己定义一个 http 接口形式的处理函数，你可以在任何文件位置自己定义：
   120  ```go
   121  // load 触发加载本地文件更新内存特定值
   122  func load(w http.ResponseWriter, r *http.Request) {
   123    reader, err := ioutil.ReadFile("xxx.txt")
   124    if err != nil {
   125      w.Write([]byte(`{"errorcode":1000, "message":"read file fail"}`))  // 错误码，错误信息自己定义
   126      return
   127    }
   128    
   129    // 业务逻辑。..
   130    
   131    // 返回成功错误码
   132    w.Write([]byte(`{"errorcode":0, "message":"ok"}`))
   133  }
   134  ```
   135  
   136  ## 注册路由
   137  
   138  init 函数或者自己的内部函数注册 admin：
   139  ```go
   140  import (
   141    "trpc.group/trpc-go/trpc-go/admin"
   142  )
   143  func init() {
   144    admin.HandleFunc("/cmds/load", load)  // 路径自己定义，一般在/cmds 下面，注意不要重复，不然会相互覆盖
   145  }
   146  ```
   147  
   148  ## 触发命令
   149  
   150  触发执行自定义命令
   151  ```shell
   152  curl http://ip:port/cmds/load
   153  ```
   154  
   155  # pprof 性能分析
   156  
   157  pprof 是 go 语言自带的性能分析工具，默认跟 admin 服务同一个端口号，只要开启了 admin 服务，即可以使用服务的 pprof。 
   158  
   159  配置好 admin 配置以后，有以下几种方式使用 pprof：
   160  
   161  ## 使用配置有 go 环境并且与服务网络连通的机器
   162  
   163  ```shell
   164  go tool pprof http://{$ip}:${port}/debug/pprof/profile?seconds=20
   165  ```
   166  
   167  ## 将 pprof 文件下载到本地，本地 go 工具进行分析
   168  
   169  ```shell
   170  curl http://${ip}:{$port}/debug/pprof/profile?seconds=20 > profile.out
   171  go tool pprof profile.out
   172  
   173  curl http://${ip}:{$port}/debug/pprof/trace?seconds=20 > trace.out
   174  go tool trace trace.out
   175  ```
   176  
   177  # 内存管理命令 debug/pprof/heap
   178  
   179  另外，trpc-go 会自动帮你去掉 golang http 包 DefaultServeMux 上注册的 pprof 路由，规避掉 golang net/http/pprof 包的安全问题（这是 go 本身的问题）。
   180  
   181  所以，使用 trpc-go 框架搭建的服务直接可以用 pprof 命令，但用`http.ListenAndServe("xxx", xxx)`方式起的服务会无法用 pprof 命令。
   182  
   183  在安装了 go 命令的内网机器进行内存分析：
   184  
   185  ```shell
   186  go tool pprof -inuse_space http://xxx:11029/debug/pprof/heap
   187  go tool pprof -alloc_space http://xxx:11029/debug/pprof/heap
   188  ```