教程 / 后端集成 / 使用 Axiom 管理日志
📝 文字 ● 中级 更新于 2026-05-13

使用 Axiom 管理日志

将任何后端的结构化日志发送到 Axiom,用 APL(类 SQL 语言)检索,免费层保留 30 天。Sentry 负责捕获异常,Axiom 负责记录你打印的其他一切。

何时选用 Axiom

0
  • 选用 Axiom 的场景 — 你需要一个真正可用的免费层(每月 0.5 TB 写入、30 天保留),一个不像上个世纪的查询语言,且不按席位收费。
  • 备选方案Better Stack Logs(与 Better Stack 可用性监控同一厂商)、Datadog(功能强大得多,价格也贵得多)、Elastic(适合自托管)、Loki(开源,需自行运维)、SigNoz(开源可观测性平台)。
  • 不适合用 Axiom 的场景 — 带分组和告警的异常捕获。那种需求请用 Sentry,两者面向不同的问题形态。
  • 注册app.axiom.co/register,无需绑定信用卡。

创建数据集

1

数据集是日志的落地桶。进入 Dashboard → Datasets → New dataset,按服务命名:api-prodweb-prodworker-prod。每个服务独立数据集,查询成本更低,且可按服务分别配置保留策略。

不要把所有日志都塞进一个 logs 数据集——等你积累到一千万条事件时就会后悔。

获取 API 令牌

2

Settings → API tokens → New API token。权限范围:应用侧只需选 Ingest(写入)。如果需要从仪表盘查询,另外单独创建一个 Query(查询)令牌。

添加到 .env

AXIOM_TOKEN=xaat-…
AXIOM_DATASET=api-prod
AXIOM_ORG_ID=your-org-id  # under Settings → Organization

从 Node 发送日志

3

安装 SDK:

npm install @axiomhq/js

接入方式——推荐搭配 pino,这样你的业务代码不与 Axiom 强绑定:

import pino from "pino";
import { AxiomJSTransport } from "@axiomhq/pino";
import { Axiom } from "@axiomhq/js";

const axiom = new Axiom({ token: process.env.AXIOM_TOKEN });

const logger = pino(
  { level: "info" },
  new AxiomJSTransport({
    axiom,
    dataset: process.env.AXIOM_DATASET,
  }),
);

// Usage
logger.info({ userId: user.id, action: "signup" }, "user signed up");
logger.error({ err, requestId: req.id }, "stripe webhook failed");

该传输层每 1 秒或 1 MB 批量上传一次,单条日志的额外开销几乎为零。崩溃安全:关机时调用同步的 flushSync() 可确保尾部日志不丢失。

官方文档:从 Node.js 发送数据

从 Vercel / Cloudflare / Fly 发送日志

4

这些平台不需要 SDK——直接安装集成插件即可,原生日志引流,无需改代码。

  • VercelVercel Axiom 集成,一键安装,所有 console.log 和请求日志自动流入你的数据集。
  • Cloudflare WorkersWorkers Logpush 指南,配置一次,每次 Worker 调用均自动记录日志。
  • Fly.ioFly 日志推送器,以 sidecar 方式运行。
  • Railway / Render / DO App Platform — 暂无原生集成,在应用代码中使用 SDK。
  • Kubernetes / VPS — 以守护进程方式安装 Vector,将其指向 Axiom 的 HTTP 端点。参考 Vector + Axiom 指南

使用 APL 查询

5

APL = Axiom Processing Language,形似 SQL,专为时序数据优化。打开 Datasets → api-prod → Query

// Last hour of errors
['api-prod']
| where _time > ago(1h) and level == "error"
| project _time, msg, requestId, userId

// Top 10 endpoints by error rate
['api-prod']
| where _time > ago(24h)
| summarize errors=countif(level == "error"), total=count() by route
| extend errorRate = round(100.0 * errors / total, 2)
| top 10 by errorRate

// Drill into one user's session
['api-prod']
| where userId == "u_abc123" and _time > ago(7d)
| order by _time asc

将常用查询保存为星标查询(显示在侧边栏),将高价值查询转为 Monitor(监控告警,见下一步)。

APL 参考文档:axiom.co/docs/apl/introduction

基于日志模式设置告警(Monitor)

6

Monitors → New monitor,选择查询、阈值和时间窗口。示例:

  • countif(level == "error") > 50,5 分钟内 → 呼叫值班人员
  • countif(msg contains "OOM") > 0 → 发送至 Slack #infra 频道
  • countif(path == "/api/checkout" and status >= 500) > 5 → 通知创始人

通知渠道支持:Slack、PagerDuty、Discord、邮件、Webhook。如有值班轮转需求,可通过 Webhook 接入 OpsgeniePagerDuty

常见问题

7
  • 日志缺少字段 — pino 传入纯字符串(logger.info("user signed up"))只会生成一个 msg 字段。应先传对象:logger.info({ userId }, "user signed up"),字段才会变成可查询的列。
  • 隐私数据泄漏 — 不要在日志中记录原始邮箱地址、支付令牌或认证请求头。Axiom 是第三方服务,有访问权限。在 pino 中添加脱敏层:redact: ["req.headers.authorization", "*.email", "*.password"]
  • 写入配额突发 — 失控的 debug 日志可能在一分钟内消耗 100 MB。在 Settings → Datasets 中为每个数据集设置写入上限。超出配额后 Axiom 会丢弃数据并给出警告,不会产生账单惊喜。
  • 日志延迟约 10 秒 — 这是批量上传间隔,不是 bug。如需"实时尾随"的效果,可将 flushInterval 降低到 500ms,或使用仪表盘的 Live 模式(每 2 秒轮询一次)。
  • 自托管服务器时钟偏差 — Axiom 使用事件载荷中的 _time 字段。如果主机时钟偏差数小时,日志会出现在错误的时间桶中。请运行 chronytimesyncd 进行时钟同步。

定价实况

8
  • 免费版 — 每月 0.5 TB 写入、30 天保留、3 个 Monitor。对于请求量低于 100 req/s 的服务完全够用。
  • Team 版 — $25/月,超出配额部分按 $0.30/GB 计费,保留 95 天,Monitor 数量不限。
  • 横向对比 — Datadog Logs 写入价格为 $0.10/GB,但保留费用为 $1.70/百万事件;对于日志量较大的工作负载,Axiom 的固定写入定价通常便宜 5–20 倍。Loki 开源免费,但需自行运维(S3 存储费用由你承担)。

定价页面:axiom.co/pricing

官方参考资料

与 Sentry 搭配使用。 Sentry 负责"带分组和告警的异常堆栈追踪",Axiom 负责"你打印的所有日志,事后需要检索时用得上"。两者约有 5% 的功能重叠,95% 互为补充。