axiom-apl

Axiom has its own language for asking questions of the logs it stores, and this is the reference for writing those questions correctly the first time.

WHEN TO USE

SCOPE

USE FOR

Write a new APL query against an Axiom dataset without guessing at field names.
Look up the right operator or function partway through building a query.
Fix an APL query that returns an error or unexpected results.
Work out the correct time filter for a relative or absolute time range.
Translate OpenTelemetry field names, like service.name, into Axiom's bracket syntax.

NOT FOR

Skip this for a single field lookup — run getschema directly instead.
Skip this if you already have a working query; there is no need for syntax help again.
Real-time or continuous alerting is Axiom Monitors' job, not a query written here.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (7)

Axiom Processing Language (APL)

APL is Axiom's query language for analyzing observability data. This skill provides comprehensive guidance for writing, debugging, and optimizing APL queries.

Quick Reference

Documentation: https://axiom.co/docs/apl/introduction

CLI usage: See references/cli.md

Core Workflow

1. List Available Datasets

axiom dataset list -f json

2. Discover Schema (CRITICAL - Always Do First)

['<dataset>'] | getschema

Never guess field names. The schema shows all fields with their types.

3. Sample Data

['<dataset>'] | limit 10

4. Write Query

See references for operators, functions, and patterns.

APL Syntax Essentials

Dataset Reference

['dataset-name']           // Bracket notation (required for names with dots/dashes)
dataset_name               // Plain identifier (only for simple names)

Field Reference

field_name                 // Plain field
['field.with.dots']        // Bracket notation for dotted fields
['service.name']           // OTel data (see references/otel.md for field mappings)

Basic Query Structure

['dataset']
| where <condition>
| extend <new_field> = <expression>
| summarize <aggregation> by <grouping>
| project <fields>
| sort by <field> desc
| limit 100

Time Handling

Always filter by time first - it's the most selective filter.

// Relative time
| where _time >= ago(1h)
| where _time >= ago(24h) and _time < ago(1h)

// Absolute time
| where _time >= datetime(2024-01-15T10:00:00Z)
| where _time between (datetime(2024-01-15) .. datetime(2024-01-16))

Time functions:

ago(timespan) - Relative past time
now() - Current time
datetime(string) - Parse datetime
bin(_time, 5m) - Time bucketing
bin_auto(_time) - Automatic bucketing

When NOT to Use

Simple field lookup: Use getschema directly instead of invoking the full skill
Known query patterns: If you already have a working query, don't re-invoke for syntax help
Real-time alerting: Use Axiom Monitors for continuous alerting, not ad-hoc queries

References

CLI Usage - Command flags and execution
Operators - Tabular and scalar operators
Functions - String, datetime, aggregation functions
Patterns - Query patterns by use case
Common Gotchas - Mistakes and fixes
OpenTelemetry - OTel field mappings and trace patterns

Account or credentials required

1 FOR YOU

01
Install and sign in to the Axiom CLI
Queries run through the axiom command (dataset list, query), so the Axiom CLI must be installed locally and authenticated to your Axiom account.

Listed as free: Connected services may require an account or charge fees.

This skill ships inside the Axiom CLI Skills plugin. Listed package contents include hooks. Installed components and skill versions may vary by AI tool.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add axiomhq/cli --skill "axiom-apl" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install the whole plugin

This route installs the Axiom CLI Skills plugin package selected for your AI tool.

PLUGIN MARKETPLACE

Add the marketplace, then install the plugin

Typed inside the agent's own prompt, not in a terminal. The marketplace is called axiom-cli, which is the part after the @.

01
```
/plugin marketplace add axiomhq/cli
```
02
```
/plugin install axiom-cli@axiom-cli
```

Open plugin page ↗

What's inside

Files included with this skill.

View on GitHub

The repository is licensed under MIT — use, modification, and redistribution are allowed under that license’s terms.

View the repository’s license file on GitHub →