上报接口#

LogTap 的客户端 SDK（Browser/Node、Go、Flutter）统一使用如下 HTTP 接口与 JSON 数据模型进行「日志」与「埋点/事件」上报。没有 SDK 的语言直接按本文协议调用 HTTP 即可。

基本约定#

Base URL：你的 LogTap 网关地址，例如 http://localhost:8080
Project ID：项目 ID（控制台项目页可见），作为路径参数 /api/:projectId/...
鉴权（设置 AUTH_SECRET 后强制）：上报必须携带项目 Key，以下三种方式任选：
- X-Project-Key: pk_...
- Authorization: Bearer pk_...
- Sentry SDK 的 X-Sentry-Auth（sentry_key=...）
批量：同一路径支持「单条对象」或「JSON 数组」
压缩：支持 Content-Encoding: gzip
成功响应：202 Accepted（网关只做校验和入队，写库由消费者异步完成）

1. 结构化日志#

端点：POST /api/:projectId/logs/

json

{
  "level": "info",
  "message": "hello",
  "timestamp": "2025-01-01T00:00:00Z",
  "device_id": "d1",
  "trace_id": "t1",
  "span_id": "s1",
  "fields": { "k": "v" },
  "tags": { "env": "prod" },
  "user": { "id": "u1" },
  "contexts": { "app": { "version": "1.2.3" } }
}

字段说明：

message：必填
level：建议值 debug / info / warn / error / fatal，为空时服务端默认 info
timestamp：RFC3339；不传则服务端补当前时间（UTC）
user.id：用于用户去重口径（DAU/MAU、漏斗等）；不传时回退到 device_id
fields：自定义结构化字段，建议把业务维度放这里
tags / contexts：标签与应用上下文，随日志入库可在控制台过滤

批量上报示例（同一路径，JSON 数组）：

json

[
  { "level": "info", "message": "hello-1", "user": { "id": "u1" }, "fields": { "k": "v1" } },
  { "level": "info", "message": "hello-2", "user": { "id": "u1" }, "fields": { "k": "v2" } }
]

2. 埋点/事件#

端点：POST /api/:projectId/track/

json

{
  "name": "signup",
  "timestamp": "2025-01-01T00:00:00Z",
  "user": { "id": "u1" },
  "device_id": "d1",
  "properties": { "plan": "pro", "ab": "b" }
}

name：事件名，必填
properties：事件属性，用于漏斗过滤与属性分布分析

服务端落库规则：事件写入 logs 表（level = "event"，message = name，fields = properties），因此事件分析只统计 level="event" 的记录，不会被普通日志污染。

批量上报示例：

json

[
  { "name": "signup", "user": { "id": "u1" }, "properties": { "plan": "pro" } },
  { "name": "purchase", "user": { "id": "u1" }, "properties": { "sku": "s1" } }
]

3. 检索与查询#

日志与事件查询、关键词全文检索、时序聚合、漏斗与留存分析均通过控制台完成
Sentry 错误上报走独立协议，见Sentry 兼容

建议#

「日志」与「埋点事件」分开上报：日志走 /logs/，埋点走 /track/
高频场景优先使用批量数组 + gzip，减少请求数与网络开销
把业务维度放进 fields / properties，控制台的过滤与漏斗都基于结构化字段