对外暴露的 Restful API

在 Pandora.js 中，我们提供了一批将内置的 EndPoint 汇聚的数据通过 Http 对外暴露的能力，每一个 EndPoint 都可以有配套的 Resource 资源对外输出，这里的数据格式是通过 koa 和 koa-router 来简单扩展的。

通用行为

这些接口可以通过 http://127.1:7002/ 来访问，比如 curl http://127.1:7002/info。 该接口只监听了本地回环（127.0.0.1），外部无法访问，无安全问题。

所有的接口都是通过统一的结构进行封装，真正的数据都是在 data 字段中。

{
    data: {
      // xxxx
    }
    timestamp: Date.now(),
    success: false,    // true or false
    message: 'some fail message'
}

每个接口都可以传递 appName 参数来访问特定应用自己的数据。

GET /error?appName=yourAppName
GET /metris/list?appName=yourAppName

列举一些常见的 Resource

Pandora.js 中埋入了一些默认的 EndPoint 和Resource，具体可以参考 Pandora.js 的默认配置文件，这些 Resource 列举的数据并不一定完全一致，所有的 key 会根据应用当前执行的 Indicator 变化。

注意，下面所有列举的 Resource 都去除了外面的包装，只展示 data 字段的部分

DaemonResource

暴露 Daemon 的一些数据。

GET /daemon
[
  {
    "cwd": "xxx",
    "pid": 12321,
    "uptime": 232,
    "loadedGlobalConfigPaths": [
      "/xxx/xxx/xxx"
    ]
  }
]

InfoResource

暴露 InfoEndPoint 的数据，返回应用名等信息。

GET /info
[
  {
    "appName": "xxx",
    "appDir": "xxxx",
    "node": {
      "node": "8.9.1",
      "alinode": "2.3.0",
      "versions": {
        "http_parser": "2.7.0",
        "node": "6.9.4",
        "v8": "5.1.281.89",
        "uv": "1.9.1",
        "zlib": "1.2.8",
        "ares": "1.10.1-DEV",
        "icu": "57.1",
        "modules": "48",
        "openssl": "1.0.2j"
      },
      "features": {
        "debug": false,
        "uv": true,
        "ipv6": true,
        "tls_npn": true,
        "tls_alpn": true,
        "tls_sni": true,
        "tls_ocsp": true,
        "tls": true
      }
    }
  }
]

HealthResource

提供暴露 HealthEndPoint 的能力，简单做了一些格式化。

GET /health
{
  "status": "DOWN",
  "disk_space": {
    "status": "UP"
  },
  "port": {
    "status": "DOWN"
  }
}

ErrorResource

暴露 ErrorEndPoint 的数据，提供访问错误数据的能力。

GET /error
[
  {
    "method": "error",
    "timestamp": 1346846400,
    "errType": "TypeError",
    "message": "Cannot read property 'name' of null",
    "stack": "2017-11-29 15:01:20   Error: read ECONNRESET",
    "traceId": "1231455",
    "path": "/xxx/xx.log"
  }
]

ProcessResource

暴露 ProcessEndPoint 的数据。

GET /process
[
  {
    "pid": "72795",
    "title": "/Users/harry/.nvm/versions/node/v6.9.4/bin/node",
    "argv": [
      "/Users/harry/.nvm/versions/node/v6.9.4/bin/node",
      "/Users/harry/project/pandora.js/packages/cluster/dest/application/entry.js",
      "--entry",
      "/Users/harry/project/node/pandora-app/dest/entry/app.js"
    ],
    "execArgv": [],
    "execPath": "/Users/harry/.nvm/versions/node/v6.9.4/bin/node",
    "cpu": 4.6,
    "memory": 90796032,
    "uptime": 267.667
  } 
]

MetricsResource

对外暴露 MetricsEndPoint 的数据，这里的接口不止一个。

1、列出所有的 metrics，该接口不会进行过滤，会把应用下的所有 metrics 指标罗列出来

GET /metrics/list
[
  {
    "metric": "sys.cpu.nice",
    "timestamp": 1346846400,
    "value": 18,
    "type": "COUNTER",
    "level": "CRITICAL",
    "tags": {
         "host": "web01",
      "dc": "lga"
      }
  },
  {
    //xxx
  }
]

2、列出特定分组的 metrics，比如列出 system 组下的数据，/metrics/system

GET /metrics/:group
[
  {
    "metric": "sys.cpu.nice",
    "timestamp": 1346846400,
    "value": 18,
    "type": "COUNTER",
    "level": "CRITICAL",
    "tags": {
         "host": "web01",
      "dc": "lga"
      }
  },
  {
    //xxx
  }
]

TraceResource

暴露 TraceEndPoint 采集的数据。

GET /trace
[
  {
    "timestamp": "1511977377963",
    "appName": "DEFAULT_APP",
    "traceId": "1e084d5515118598316151001dd73d",
    "duration": 139,
    "pid": "23131",
    "ip": "127.0.0.1",
    "spans": [
      {
        "name": "http",
        "startMs": 1511859831616,
        "duration": 138,
        "context": {
          "traceId": "1e084d5515118598316151001dd73d",
          "spanId": "6f0f2be0d9e9a9e9"
        },
        "references": [],
        "tags": {
          "http.method": {
            "value": "GET",
            "type": "string"
          },
          "http.url": {
            "value": "/",
            "type": "string"
          },
          "http.client": {
            "value": false,
            "type": "bool"
          },
          "rpc_type": {
            "value": 0,
            "type": "number"
          },
          "http.status_code": {
            "type": "number",
            "value": 200
          }
        },
        "logs": [],
      }
  }
]

自定义 Resource

Resource 基础类型定义如下，只需要提供 prefix 和 route 方法即可。

export interface ActuatorResource {
  prefix: string;
  route(routers);
}

如下是一个简单的实现类，构造函数中接受一个 endPointService 用来获取启用的 EndPoint ，通过路由方法对外暴露接口即可。

prefix 是路由前缀，这里必须对每个不同的 Resource 定义路由前缀，以避免出错。

export class ErrorResource implements ActuatorResource {
  prefix = '/error';
  endPointService: EndPointService;
  constructor(endPointService) {
    this.endPointService = endPointService;
  }
  route(router) {
    const errorEndPoint = this.endPointService.getEndPoint('error');
    router.get('/', async (ctx, next) => {
      try {
        ctx.ok(await errorEndPoint.invoke(ctx.query['appName']));
      } catch (err) {
        ctx.fail(err.message);
      }
      await next();
    });
  }
}

我们对 koa2 的上下文 ctx 提供了一个快捷返回结构的函数，通过 ok() 和 fail() 函数即可将最后的结果返回出去。

返回的格式基本如下

{
    data: {
      // xxxx
    }
    timestamp: Date.now(),
    success: false,    // true or false
    message: 'some fail message'
}

除了在代码中定义之外，还需要在 Pandora.js 的配置中加载，具体格式如下。

actuator: {
    endPoints: {
      info: {
        enabled: true,
        target: InfoEndPoint,
        resource: InfoResource,
      },
      process: {
        enabled: true,
        target: ProcessEndPoint,
        resource: ProcessResource,
      },
    },
  },

每个 Resource 只能放到相应的 EndPoint 层级下，目前 EndPoint 和 Resource 是一一对应的，你无法单独创建 Resource 暴露接口。