LogHarbor Collector API 文档
工具概述
LogHarbor Collector 是一款面向开发人员的日志采集与接收服务，提供基于 HTTP 的统一日志写入 API。应用、服务或边车代理可将结构化日志批量发送到 Collector，Collector 负责校验、缓冲并将日志安全地投递至后端存储或下游处理管道。
本文件为标准开发者 API 文档，覆盖接口定义、请求/响应格式、错误码、限流与重试、幂等性与安全要求等。
注意：文档中的示例域名与数值仅用于说明，实际以您部署的环境与配置为准。
核心特性
- 标准化日志写入
- 支持单条 JSON、批量 JSON 数组、NDJSON（换行分隔 JSON）
- 支持 gzip 压缩传输
- 批量与部分接受
- 幂等性保障
- 通过 X-Request-Id 去重，避免重复入队
- 明确的模式约束
- 统一字段定义（timestamp、level、message、service、attributes 等）
- 运行状态可观测
- 安全与配额
- 基于 API Key 的鉴权，支持速率限制与请求大小限制
- 版本化 API
快速开始
- 前提条件
- 基础信息
- Base URL: https://collector.example.com
- API 版本: v1
- 认证方式: X-Api-Key: <YOUR_API_KEY>
- 支持的内容类型: application/json, application/x-ndjson
- 可选压缩: Content-Encoding: gzip
示例 1：发送单条日志
curl -X POST "https://collector.example.com/v1/logs" \
-H "X-Api-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"timestamp": "2025-01-10T08:30:15.123Z",
"level": "info",
"message": "user login success",
"service": {"name": "auth-service", "version": "1.4.2"},
"host": {"name": "node-12"},
"attributes": {"user_id": "u-123", "ip": "203.0.113.10"}
}'
示例 2：批量 JSON 数组
curl -X POST "https://collector.example.com/v1/logs" \
-H "X-Api-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '[
{"timestamp": "2025-01-10T08:30:15.123Z", "level": "info", "message": "a"},
{"timestamp": "2025-01-10T08:30:16Z", "level": "error", "message": "b", "attributes": {"code": 502}}
]'
示例 3：NDJSON + gzip
printf '%s\n' \
'{"timestamp":"2025-01-10T08:30:15Z","level":"info","message":"line1"}' \
'{"timestamp":"2025-01-10T08:30:16Z","level":"warn","message":"line2"}' \
| gzip -c \
| curl -X POST "https://collector.example.com/v1/logs" \
-H "X-Api-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/x-ndjson" \
-H "Content-Encoding: gzip" \
--data-binary @-
示例 4：幂等请求（避免重复入队）
curl -X POST "https://collector.example.com/v1/logs" \
-H "X-Api-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-H "X-Request-Id: 1b3c1e02-a7e1-4eb3-91f2-115aa0e51d0f" \
-d '{"timestamp":"2025-01-10T08:30:15Z","level":"info","message":"idempotent"}'
架构说明
- Ingestion API
- 接收 HTTP 请求，执行鉴权、内容协商与速率限制
- Validator
- 对每条日志进行 JSON 与模式校验、字段标准化（如时间戳解析）
- Buffer/Queue
- Processor
- Sink/Exporter
- 转发到下游（如对象存储、搜索引擎、消息队列或内部处理管道）
- Observability
语义保障：
- 写入为“至少一次”语义；客户端需容忍偶发重复并在消费端去重或通过幂等键减少重复
配置指南
- 认证与安全
- 所有请求必须使用 HTTPS
- 在请求头中携带 API Key
- X-Api-Key: <YOUR_API_KEY>
- 可选幂等键
- X-Request-Id: <UUID或其他稳定唯一值>
- 作用：同一 24 小时窗口内重复请求（且负载一致）将复用同一 ingestion_id；若负载不同返回 409 Conflict
- 接口定义
POST /v1/logs
- 描述：写入单条或批量日志
- 请求头
- Content-Type: application/json 或 application/x-ndjson
- Content-Encoding: gzip（可选）
- X-Api-Key: 必填
- X-Request-Id: 可选（启用幂等）
- 请求体
- 三种等价格式：
- 单条 JSON 对象
- JSON 数组（每个元素为一条日志）
- NDJSON（每行一个 JSON 对象）
- 响应
- 成功：202 Accepted
- Body:
{
"ingestion_id": "ing-01HYY4ZK9V8Z2M2TQ1E9S8WQ3B",
"accepted": 98,
"rejected": 2,
"errors": [
{"index": 0, "error_code": "schema_violation", "message": "missing message"},
{"index": 7, "error_code": "invalid_timestamp", "message": "invalid RFC3339 format"}
]
}
- 典型错误码
- 400 Bad Request：无效 JSON/不支持的字段类型/不支持的 Content-Type
- 401 Unauthorized：鉴权失败或缺失 API Key
- 409 Conflict：X-Request-Id 冲突且负载不同
- 413 Payload Too Large：请求体超限
- 415 Unsupported Media Type：Content-Type 不支持
- 429 Too Many Requests：触发限流
- 500/503：服务器内部错误/暂时性不可用
GET /v1/ingestions/{ingestion_id}
- 描述：查询入队处理状态（可用于异步确认）
- 响应示例：
{
"ingestion_id": "ing-01HYY4ZK9V8Z2M2TQ1E9S8WQ3B",
"status": "completed", // processing|completed|partial|failed
"accepted": 98,
"rejected": 2,
"errors": [
{"index": 0, "error_code": "schema_violation", "message": "missing message"}
],
"received_at": "2025-01-10T08:30:17.004Z",
"expires_at": "2025-01-11T08:30:17.004Z"
}
GET /v1/health
- 描述：Collector 运行健康检查
- 响应：200 OK
{ "status": "ok" }
- 日志记录模式（LogRecord）
- 通用 JSON 对象，字段如下（未标注必填均为可选）
- timestamp: string
- RFC3339/ISO-8601 格式，建议使用 UTC（Z）
- 若缺省，系统使用接收时间
- level: string
- 允许值：trace|debug|info|warn|error|fatal（大小写不敏感）
- 默认：info
- message: string（建议提供）
- service: object
- name: string（如 "auth-service"）
- version: string（如 "1.4.2"）
- host: object
- name: string（如 "node-12"）
- logger: string（记录器名称）
- thread: string（线程或协程标识）
- trace_id: string
- span_id: string
- attributes: object
- 任意键值对，值类型支持 string | number | boolean
- labels: object
- source: string
示例 LogRecord：
{
"timestamp": "2025-01-10T08:30:15.123456Z",
"level": "error",
"message": "payment failed",
"service": {"name": "payment-api", "version": "2.3.1"},
"host": {"name": "vm-23"},
"trace_id": "6b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e",
"span_id": "1a2b3c4d5e6f7a8b",
"attributes": {"order_id":"o-8876","amount":199.99,"currency":"USD","retry":false},
"labels": {"env":"prod","region":"us-east-1"},
"source": "gateway"
}
- 大小与配额限制（默认建议值，实际以部署配置为准）
- 单请求最大 body：5 MB
- 单请求最大日志条数：10,000
- 单条日志中 attributes 键数量：≤ 256
- 单个字段最大长度：64 KB（message 建议 ≤ 32 KB）
- 速率限制：返回头包含以下可选字段（如启用）
- X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
- 内容类型与编码
- Content-Type:
- application/json（单条或数组）
- application/x-ndjson（换行分隔）
- Content-Encoding:
- 错误模型
- 重试与幂等
- 网络/5xx/429 建议带指数退避重试；初始退避 200–500ms，最大退避 10s，抖动随机化
- 使用 X-Request-Id 提供去重能力
- 同一 request id + 相同负载：返回相同 ingestion_id，不重复入队
- 同一 request id + 不同负载：409 Conflict
- 客户端应对 413/400 修正负载后再发送，避免盲目重试
- 时间与时区
- 建议使用 UTC（Z）时间戳
- 允许纳秒精度（若超出系统精度，将按支持精度截断/舍入）
最佳实践
- 批量发送
- 优先使用批量（JSON 数组或 NDJSON）以减少连接与开销；建议每批 100–1000 条，或按 256KB–1MB 的未压缩体积分批
- 压缩传输
- 字段规范化
- 保持稳定的 service.name 与 labels.env，用于后续路由与索引
- 使用 attributes 承载业务键值，不要在 message 中混合结构化信息
- 幂等与可恢复
- 为每个请求生成稳定的 X-Request-Id（如 UUID v4），在客户端重试时复用
- 错误处理
- 对 207 式的“部分成功”（通过 errors 数组体现）进行逐条修正重发，避免整批重复
- 速率与背压
- 监控 429 与 X-RateLimit-* 头，动态调整批大小与发送速率
- 安全
- API Key 保存在安全存储，避免写入应用日志
- 仅通过 HTTPS 发送，验证证书链
- 观测性
- 在客户端记录发送量、失败量、重试次数、平均批大小与延迟，便于容量规划
- 数据质量
- 保证 timestamp 单调不倒退（尽量与 NTP 同步）
- 限制 attributes 键数量与长度，避免过度高基数字段
如需更多示例或 SDK 适配建议，请根据您的语言栈实现以下要点：统一 HTTP 客户端、批处理缓冲、gzip 压缩、指数退避重试、X-Request-Id 幂等与可观测指标上报。
