SDK#

LogTap 提供三端官方 SDK，用于向网关上报「结构化日志」与「埋点/事件」，统一封装批量缓冲、gzip 压缩、失败重试与上下文合并。其他语言直接按上报接口调用 HTTP 即可。

共同配置#

baseUrl：网关地址
projectId：项目 ID
projectKey：启用 AUTH_SECRET 时必填（X-Project-Key: pk_...）
gzip：可选，不支持的平台自动降级

统一能力：内部队列按 flushIntervalMs 定时或攒够 minBatchSize 立即发送；失败自动指数退避重试（上限 30s）；globalTags / globalContexts 合并进每条 payload；identify() 设置用户上下文；beforeSend 钩子可用于脱敏或丢弃。

JavaScript / TypeScript（Browser / Node）#

包名：logtap-sdk（仓库目录 sdks/js/logtap/）

bash

npm i logtap-sdk

import { LogtapClient } from "logtap-sdk";

const client = new LogtapClient({
  baseUrl: "https://your-logtap-host",
  projectId: 1,
  projectKey: "pk_xxx",
  gzip: true,
  flushIntervalMs: 5000, // 最大延迟（到时间也会发）
  minBatchSize: 20,      // 达到条数立即发
  immediateEvents: ["purchase", "payment_succeeded"],
  globalTags: { env: "prod" },
  globalContexts: { app: { version: "1.2.3" } },
});

client.captureBrowserErrors(); // browser 可选
client.captureNodeErrors();    // node 可选

client.identify("u1", { plan: "pro" });
client.info("hello", { k: "v" }, { tags: { req: "1" } });
client.track("signup", { from: "landing" });

await client.close();

Go#

bash

go get github.com/aak1247/logtap/sdks/go/logtap

client, err := logtap.NewClient(logtap.ClientOptions{
	BaseURL:    "https://your-logtap-host",
	ProjectID:  1,
	ProjectKey: "pk_xxx",
	Gzip:       true,
	GlobalTags: map[string]string{"env": "prod"},
	GlobalContexts: map[string]any{
		"app": map[string]any{"version": "1.2.3"},
	},
})
if err != nil {
	panic(err)
}
defer client.Close(context.Background())
defer client.Recover(true) // 可选：捕获 panic 上报

client.Identify("u1", map[string]any{"plan": "pro"})
client.Info("hello", map[string]any{"k": "v"}, nil)
client.Track("signup", map[string]any{"from": "landing"}, nil)

Flutter#

包名：logtap_flutter（仓库目录 sdks/flutter/logtap_flutter/）

dart

final client = await LogtapClient.create(
  const LogtapClientOptions(
    baseUrl: "https://your-logtap-host",
    projectId: 1,
    projectKey: "pk_xxx",
    gzip: true, // Web 自动降级为非 gzip
    globalTags: {"env": "prod"},
    globalContexts: {"app": {"version": "1.2.3"}},
  ),
);

client.captureFlutterErrors(); // 可选：捕获未处理异常

client.identify("u1", {"plan": "pro"});
client.info("hello", {"k": "v"});
client.track("signup", {"from": "landing"});

await client.close();

其他语言#

不引入 SDK 也可以直接用 HTTP 上报（见上报接口）。以 Python 为例：

python

import requests

requests.post(
    "https://your-logtap-host/api/1/logs/",
    headers={"X-Project-Key": "pk_xxx"},
    json=[{"level": "info", "message": "hello", "user": {"id": "u1"}}],
)

更多语言集成示例（Python、Java、PHP、Ruby、.NET）见仓库 docs/integrations/ 目录。

异常监控怎么办？#

异常监控优先复用 Sentry SDK（零改动改 DSN，见Sentry 兼容）；各端 SDK 的 capture*Errors() 适合在没有 Sentry SDK 的轻量场景里捕获未处理异常。