axiom

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Axiom

Axiom is a cloud-native observability platform for storing, querying, and analyzing log and event data at scale. Use the REST API to ingest data, run queries using APL (Axiom Processing Language), and manage datasets programmatically.

Official docs:

https://axiom.co/docs/restapi/introduction

Axiom是一款云原生可观测性平台，可用于大规模存储、查询和分析日志与事件数据。你可以使用其REST API摄入数据、通过APL（Axiom Processing Language）运行查询，以及通过编程方式管理数据集。

官方文档：

https://axiom.co/docs/restapi/introduction

When to Use

何时使用

Use this skill when you need to:

Send logs, metrics, or event data to Axiom
Query and analyze data using APL (Axiom Processing Language)
Manage datasets, monitors, and annotations
Build observability pipelines and dashboards

当你需要完成以下操作时可使用本技能：

向Axiom发送日志、指标或事件数据
使用APL（Axiom Processing Language）查询和分析数据
管理数据集、监控器和注解
搭建可观测性管道和仪表盘

Prerequisites

前置要求

Create an Axiom account at https://app.axiom.co/register
Create an API token with appropriate permissions (Settings > API Tokens)
Create a dataset to store your data

在 https://app.axiom.co/register 创建Axiom账号
创建具有对应权限的API令牌（设置 > API Tokens）
创建用于存储数据的数据集

Token Types

令牌类型

Axiom supports two token types:

Type	Prefix	Use Case
API Token	`xaat-`	Most operations (datasets, ingest, queries, monitors)
Personal Access Token (PAT)	`xapt-`	Full account access (required for `/v2/user` endpoint)

Set environment variables:

bash

undefined

Axiom支持两种令牌类型：

类型	前缀	适用场景
API Token	`xaat-`	绝大多数操作（数据集管理、数据摄入、查询、监控器管理）
Personal Access Token (PAT)	`xapt-`	完整账号权限（调用 `/v2/user` 接口时需要）

设置环境变量：

bash

undefined

Required: API Token for most operations

必选：绝大多数操作使用的API令牌

export AXIOM_TOKEN="xaat-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"


---


> **Important:** When using `$VAR` in a command that pipes to another command, wrap the command containing `$VAR` in `bash -c '...'`. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
> ```bash
> bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'
> ```

export AXIOM_TOKEN="xaat-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"


---


> **重要提示：** 当你在通过管道传输到其他命令的指令中使用`$VAR`时，请将包含`$VAR`的命令包裹在`bash -c '...'`中。由于Claude Code的一个bug，直接使用管道时环境变量会被静默清除。
> ```bash
> bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'
> ```

How to Use

使用方法

Base URLs

基础URL

Ingest (US East):
```
https://us-east-1.aws.edge.axiom.co
```
Ingest (EU Central):
```
https://eu-central-1.aws.edge.axiom.co
```
API:
```
https://api.axiom.co
```

数据摄入（美东）:
```
https://us-east-1.aws.edge.axiom.co
```
数据摄入（欧中）:
```
https://eu-central-1.aws.edge.axiom.co
```
通用API:
```
https://api.axiom.co
```

1. List Datasets

1. 列出数据集

bash

bash -c 'curl -s "https://api.axiom.co/v2/datasets" -H "Authorization: Bearer ${AXIOM_TOKEN}"'

bash

bash -c 'curl -s "https://api.axiom.co/v2/datasets" -H "Authorization: Bearer ${AXIOM_TOKEN}"'

2. Get Dataset Info

2. 获取数据集信息

bash

bash -c 'curl -s "https://api.axiom.co/v2/datasets/my-logs" -H "Authorization: Bearer ${AXIOM_TOKEN}"'

bash

bash -c 'curl -s "https://api.axiom.co/v2/datasets/my-logs" -H "Authorization: Bearer ${AXIOM_TOKEN}"'

3. Create Dataset

3. 创建数据集

Write to

/tmp/axiom_request.json

json

{
  "name": "my-logs",
  "description": "Application logs"
}

Then run:

bash

bash -c 'curl -s -X POST "https://api.axiom.co/v2/datasets" -H "Authorization: Bearer ${AXIOM_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json'

写入

/tmp/axiom_request.json

：

json

{
  "name": "my-logs",
  "description": "Application logs"
}

然后运行：

bash

bash -c 'curl -s -X POST "https://api.axiom.co/v2/datasets" -H "Authorization: Bearer ${AXIOM_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json'

4. Ingest Data (JSON)

4. 摄入数据（JSON格式）

Write to

/tmp/axiom_request.json

json

[
  {"message": "User logged in", "user_id": "123", "level": "info"}
]

Then run:

bash

bash -c 'curl -s -X POST "https://us-east-1.aws.edge.axiom.co/v1/ingest/my-logs" -H "Authorization: Bearer ${AXIOM_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json'

写入

/tmp/axiom_request.json

：

json

[
  {"message": "User logged in", "user_id": "123", "level": "info"}
]

然后运行：

bash

bash -c 'curl -s -X POST "https://us-east-1.aws.edge.axiom.co/v1/ingest/my-logs" -H "Authorization: Bearer ${AXIOM_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json'

5. Ingest Data (NDJSON)

5. 摄入数据（NDJSON格式）

Write to

/tmp/axiom_ndjson.ndjson

{"message": "Event 1", "level": "info"}
{"message": "Event 2", "level": "warn"}

Then run:

bash

bash -c 'curl -s -X POST "https://us-east-1.aws.edge.axiom.co/v1/ingest/my-logs" -H "Authorization: Bearer ${AXIOM_TOKEN}" -H "Content-Type: application/x-ndjson" -d @/tmp/axiom_ndjson.ndjson'

写入

/tmp/axiom_ndjson.ndjson

：

{"message": "Event 1", "level": "info"}
{"message": "Event 2", "level": "warn"}

然后运行：

bash

bash -c 'curl -s -X POST "https://us-east-1.aws.edge.axiom.co/v1/ingest/my-logs" -H "Authorization: Bearer ${AXIOM_TOKEN}" -H "Content-Type: application/x-ndjson" -d @/tmp/axiom_ndjson.ndjson'

6. Query Data with APL

6. 使用APL查询数据

Write to

/tmp/axiom_request.json

json

{
  "apl": "[\"my-logs\"] | where level == \"error\" | limit 10",
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2025-12-31T23:59:59Z"
}

Then run:

bash

bash -c 'curl -s -X POST "https://api.axiom.co/v1/datasets/_apl?format=tabular" -H "Authorization: Bearer ${AXIOM_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json'

写入

/tmp/axiom_request.json

：

json

{
  "apl": "[\"my-logs\"] | where level == \"error\" | limit 10",
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2025-12-31T23:59:59Z"
}

然后运行：

bash

bash -c 'curl -s -X POST "https://api.axiom.co/v1/datasets/_apl?format=tabular" -H "Authorization: Bearer ${AXIOM_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json'

7. Query with Aggregation

7. 聚合查询

Write to

/tmp/axiom_request.json

json

{
  "apl": "[\"my-logs\"] | summarize count() by level",
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2025-12-31T23:59:59Z"
}

Then run:

bash

bash -c 'curl -s -X POST "https://api.axiom.co/v1/datasets/_apl?format=tabular" -H "Authorization: Bearer ${AXIOM_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json'

写入

/tmp/axiom_request.json

：

json

{
  "apl": "[\"my-logs\"] | summarize count() by level",
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2025-12-31T23:59:59Z"
}

然后运行：

bash

bash -c 'curl -s -X POST "https://api.axiom.co/v1/datasets/_apl?format=tabular" -H "Authorization: Bearer ${AXIOM_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json'

8. Create Annotation

8. 创建注解

Write to

/tmp/axiom_request.json

json

{
  "datasets": ["my-logs"],
  "type": "deployment",
  "title": "v1.2.0 deployed",
  "time": "2024-12-24T10:00:00Z"
}

Then run:

bash

bash -c 'curl -s -X POST "https://api.axiom.co/v2/annotations" -H "Authorization: Bearer ${AXIOM_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json'

写入

/tmp/axiom_request.json

：

json

{
  "datasets": ["my-logs"],
  "type": "deployment",
  "title": "v1.2.0 deployed",
  "time": "2024-12-24T10:00:00Z"
}

然后运行：

bash

bash -c 'curl -s -X POST "https://api.axiom.co/v2/annotations" -H "Authorization: Bearer ${AXIOM_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json'

9. List Monitors

9. 列出监控器

bash

bash -c 'curl -s "https://api.axiom.co/v2/monitors" -H "Authorization: Bearer ${AXIOM_TOKEN}"'

bash

bash -c 'curl -s "https://api.axiom.co/v2/monitors" -H "Authorization: Bearer ${AXIOM_TOKEN}"'

10. Delete Dataset

10. 删除数据集

bash

bash -c 'curl -s -X DELETE "https://api.axiom.co/v2/datasets/my-logs" -H "Authorization: Bearer ${AXIOM_TOKEN}"'

bash

bash -c 'curl -s -X DELETE "https://api.axiom.co/v2/datasets/my-logs" -H "Authorization: Bearer ${AXIOM_TOKEN}"'

APL Query Examples

APL查询示例

APL (Axiom Processing Language) is similar to Kusto Query Language (KQL). Use

["dataset-name"]

syntax for dataset names with special characters.

Query	Description
`["dataset"] \| limit 10`	Get first 10 events
`["dataset"] \| where level == "error"`	Filter by field value
`["dataset"] \| where message contains "timeout"`	Search in text
`["dataset"] \| summarize count() by level`	Count by group
`["dataset"] \| summarize avg(duration_ms) by bin(_time, 1h)`	Hourly average
`["dataset"] \| sort by _time desc \| limit 100`	Latest 100 events
`["dataset"] \| where _time > ago(1h)`	Events in last hour

APL（Axiom Processing Language）语法与Kusto Query Language（KQL）类似。对于名称包含特殊字符的数据集，请使用

["数据集名称"]

语法。

查询语句	说明
`["dataset"] \| limit 10`	获取前10条事件
`["dataset"] \| where level == "error"`	按字段值过滤
`["dataset"] \| where message contains "timeout"`	文本内容搜索
`["dataset"] \| summarize count() by level`	按分组统计数量
`["dataset"] \| summarize avg(duration_ms) by bin(_time, 1h)`	每小时平均值统计
`["dataset"] \| sort by _time desc \| limit 100`	最新的100条事件
`["dataset"] \| where _time > ago(1h)`	最近1小时的事件

Guidelines

使用指南

Use Edge URLs for Ingest: Always use the edge endpoint (
```
us-east-1.aws.edge.axiom.co
```
or
```
eu-central-1.aws.edge.axiom.co
```
) for data ingestion, not
```
api.axiom.co
```
Batch Events: Send multiple events in a single request for better performance
Include Timestamps: Events without timestamps will use server receive time
Rate Limits: Check
```
X-RateLimit-Remaining
```
header to avoid hitting limits
APL Time Range: Always specify
```
startTime
```
and
```
endTime
```
for queries to improve performance
Data Formats: JSON array is recommended; NDJSON and CSV are also supported

数据摄入使用边缘URL：数据摄入请始终使用边缘端点（
```
us-east-1.aws.edge.axiom.co
```
或
```
eu-central-1.aws.edge.axiom.co
```
），不要使用
```
api.axiom.co
```
批量发送事件：单次请求发送多个事件可提升性能
包含时间戳：未携带时间戳的事件会使用服务器接收时间
速率限制：检查
```
X-RateLimit-Remaining
```
响应头避免触发限流
APL时间范围：查询时始终指定
```
startTime
```
和
```
endTime
```
可提升查询性能
数据格式：推荐使用JSON数组，同时也支持NDJSON和CSV格式