唯杰地图 logo唯杰地图
VJMAP
EN

系统

vjmap-service/references/api/11-system.md 5.4 KB216 行
原文

分类代号：C.11 本章共 4 个接口

这几个接口是运维和监控最常看的：

  • heart：心跳
  • version：版本与构建信息
  • runstatus：当前进程 / 连接 / 切片状态
  • viewlogs：读最近 N 条日志

生产环境完全可以周期性采集 runstatus 做监控告警，不需要登进后端机器。

快速索引

序号 SDK 方法 URL
64 heart / heart GET /heart
65 version / version GET /version
66 run_status / runStatus GET /api/v1/map/cmd/runstatus/_/v1?detail=true
67 view_logs / viewLogs GET /api/v1/map/cmd/viewlogs/_/v1?record=N

64 · 心跳 /heart

直接挂 Gateway 上（不走 /api/v1/... 前缀），用来判断进程是否活着。

响应（实采）

{
  "status": "ok",
  "timestamp": "2026-04-22T12:37:54.501381+08:00"
}

Python / Node.js

svc.heart()

await svc.heart();

用作健康检查

# docker-compose healthcheck 片段
healthcheck:
  test: ["CMD", "curl", "-f", "http://127.0.0.1:27660/heart"]
  interval: 30s
  timeout: 3s
  retries: 3

65 · 版本 /version

响应（实采）

{
  "arch":    "amd64",
  "os":      "windows",
  "status":  "ok",
  "time":    "2026-04-22 12:37:54",
  "version": "2026041001"
}
  • version 是 service 的 build id（yyyyMMDD + 计数）
  • time 是服务器当前时间，可用来校时
  • 图形服务的版本在 runstatus → application.version 里（本例是 "20260305"）

66 · 运行状态 runstatus

查询参数

字段 默认 说明
detail false true 时额外返回 activeRequests 列表

响应（实采 detail=true）

{
  "application": {
    "pid":                   "11996",
    "runtime":               24063,
    "taskActiveThreadCount": 0,
    "threadId":              "12000",
    "version":               "20260305"
  },
  "process": {
    "activeProcesss":            {},
    "activeRequestCount":        0,
    "activeRequests":            [],
    "curParallelProcessGeomNum": 0,
    "maxParallelProcessGeomNum": 2,
    "recycleProcesss":           [],
    "reqTimeout":                600000,
    "waitWorkMapIds":            []
  },
  "slice": {},
  "store": {
    "connectionNames":        "_cache_map",
    "storeLastAccessTime":    [],
    "storeNoActiveCloseTime": 60,
    "storeStatus":            []
  }
}

字段速查

字段 含义
application.runtime 进程启动毫秒数
process.activeRequestCount 当前在处理的请求数
process.activeRequests detail=true 时的 URL 列表，排查"卡在什么请求上"
process.curParallelProcessGeomNum 当前并行几何任务
process.maxParallelProcessGeomNum 并发上限
process.recycleProcesss 被回收的子进程
slice 切片缓存状态（按 layer）
store KV 存储连接

Python

status = svc.run_status(detail=True)
assert status["application"]["pid"]
print(status["process"]["activeRequestCount"], "个并发请求")

Node.js

const st = await svc.runStatus(true);

67 · 查看日志 viewlogs

查询参数

字段 默认 说明
record 100 读取最近多少条记录
time 60 只看最近 N 分钟内的日志

响应（实采，部分片段）

{
  "logs": [
    "       *** log260422_0x115f4_2026-04-22.log ***  ",
    "[2026-04-22 11:58:01.625] [daily_logger] [info] File:() Line:(0) Msg: (\"process app started..._null_@>v1_1571__||__11996__||__28011__||__D:/Program Files/vjmapserver/data\")\n",
    "[2026-04-22 11:58:01.697] [daily_logger] [info] File:() Line:(0) Msg: (openMap begin... \"_null_@>v1\")\n",
    ...
  ]
}

每一条都是一行日志（带行尾 \n）；多子进程时会用 *** log....log *** 分隔不同文件。

⚠️ record 是"每个日志文件最近 N 条"而非全局 N 条（record=1/5/100 分别回 32/63/162 行——每个子进程日志文件各贡献 ≤N 条 + *** 文件头行）。本地有十几个 worker 日志文件时返回值远大于 N，按 *** 头切段分组解析。

Python

lines = svc.view_logs(record=200)["logs"]
for line in lines[-20:]:
    print(line.rstrip())

Node.js

const { logs } = await svc.viewLogs(200);

⚠️ 这是最近 N 条，不是整个日志文件；想做审计请定时拉并本地存档。

监控样例：Python 拉取 → Prometheus

from time import sleep
def poll():
    while True:
        try:
            s = svc.run_status(detail=False)
            metrics = {
                "vjmap_up":             1,
                "vjmap_active_reqs":    s["process"]["activeRequestCount"],
                "vjmap_runtime_ms":     s["application"]["runtime"],
                "vjmap_store_count":    len(s["store"].get("storeStatus") or []),
            }
        except Exception:
            metrics = {"vjmap_up": 0}
        push_to_prometheus(metrics)
        sleep(15)