Java 后端 SDK 快速开始
让 Java 后端服务（Spring / Servlet / 批处理 / 数据管道）上报应用日志 + 分布式 trace span，并经
W3C traceparent 与端上 SDK 端到端贯通。HMAC 使用 JDK 的 javax.crypto, JSON 使用自研序列化;
内置 HTTP 使用 Apache HttpClient 5.6.4, 最低编译目标为 Java 8, 不依赖 OpenTelemetry。
Maven / Gradle 会解析 httpcore5、httpcore5-h2 和 slf4j-api 等传递依赖, 不需要手动复制依赖 JAR。
对应 SDK：sdks/java-backend（坐标 com.argusplatform:argus-backend）。
跨语言 API 对照见 后端 SDK API 矩阵 。
引入依赖
在 Maven / Gradle 引入 com.argusplatform:argus-backend，并配置数据源名称（DSN）——格式详见
DSN 与 HMAC 签名：
export ARGUS_DSN='argus://<public_key>:<secret_key>@<host:port>/<project_id>'初始化
import com.argusplatform.argus.ArgusClient;
import com.argusplatform.argus.Span;
import java.util.Collections;
// 读 ARGUS_DSN 环境变量
ArgusClient argus = ArgusClient.fromEnv();
// 或显式 + 调参：
// ArgusClient argus = ArgusClient.builder("argus://pub:sec@ingest.argus-tools.app/proj")
// .serviceName("checkout-api").flushIntervalMs(5000).maxBatch(512).maxBuffer(10000).build();上报日志与 trace span
argus.log("info", "order created", Collections.singletonMap("order_id", "o-123"), null);
argus.log("error", "payment failed");
// trace span：try-with-resources 自动 end；错误状态显式 setStatus
try (Span span = argus.startSpan("process_payment", "server",
Collections.singletonMap("order.id", "o-123"), null)) {
// 子 span：传 span.context() 继承同一条 trace
Span child = argus.startSpan("charge_card", "client", null, span.context());
child.end();
}
argus.close(); // 停止后台 flush 并最后上报一次（实现 AutoCloseable，可 try-with-resources）端到端 Trace：把链路传给下游
startSpan 产生的 span 上下文可注入出站请求头，下游服务的 Argus SDK 会继承同一条 trace。trace span
经 JSON EventBatch 统一上报到 POST /v1/events（channel="trace"），与 go / node 后端 SDK
的 wire 格式一致。详见
分布式追踪。
行为约定
| 方面 | 行为 |
|---|---|
| 批量 | log() 只入缓冲，后台线程按 flushIntervalMs 批量上报，或显式 flush() |
| HTTP 期限 | 单次网络调用共享 10 秒取消期限, 持续零星响应字节不能刷新期限; 同步 DNS/JVM 暂停不承诺硬实时中断, 整个 retry/close 不等于 10 秒完成 |
| 重试 | 网络错误、408/425/429/5xx 由 Argus 队列按 jitter 指数退避, 默认额外重试 3 次, 解析 Retry-After 并限制等待最长 30 秒; 耗尽回队后再尝试, 其他 4xx 永久丢弃. HTTP 库自身不自动重试 |
| 背压 | 缓冲超 maxBuffer 时 drop-oldest（保留最新窗口），dropped() 可查丢弃数 |
| HMAC | 每批按 METHOD\nPATH\nTS\nsha256hex(BODY) canonical 做 HMAC-SHA256 签名 |
所有上报均为 best-effort: 暂时失败按退避保留, 永久错误或背压淘汰通过 diagnostics 计数可查; 有界缓冲和异常隔离用于保护业务路径。