Axon - GitLite

KO | EN

gitlite — search

#react #ai #llm #android #rust #deep-learning #linux #docker #nodejs #java #kubernetes #vue #awesome-list #security

Axon

(★ 155)

OpenTelemetry-native LLM observability CLI. Point any OTEL exporter at it and watch your LLM/agent traces in real time.

File Explorer

Download Latest Version (.zip)

- launch.json
- - publish.yml
- - server.ts
  - sse.ts
  - static.ts
- .dockerignore
- .env
- .gitignore
- Dockerfile
- Dockerfile.dev
- package.json
- README.md
- tsconfig.json
- - Axon-Web-Favicon.svg
  - AXON.svg
  - favicon.svg
  - logo-latest.svg
  - logo-n.png
- - App.tsx
  - index.css
  - main.tsx
  - types.ts
- .dockerignore
- .gitignore
- Dockerfile
- Dockerfile.dev
- index.html
- nginx.conf
- package.json
- postcss.config.js
- README.md
- tailwind.config.js
- tsconfig.json
- vite.config.ts
- - overview.png
  - Raw.png
  - transcript.png
  - tree.png
  - waterfall.png
- axon-logo.svg
- - package.json
  - README.md
  - tsconfig.json
- - .eslintrc.cjs
  - .gitignore
  - package.json
  - README.md
  - tsconfig.json
  - vite.config.ts
- - package.json
  - README.md
  - tsconfig.json
.dockerignore
.gitignore
.nvmrc
Axon-Product-Design.pdf
docker-compose.dev.yml
docker-compose.yml
DOCKER_IMPLEMENTATION_SUMMARY.md
DOCKER_QUICKSTART.md
DOCKER_SETUP.md
LICENSE
Makefile
package-lock.json
package.json
README.md
tsconfig.json

# Installation Guide

1. Get the code

git clone https://github.com/langchain-tracer/Axon

Downloads the entire project code from GitHub to your computer.

cd Axon

Moves into the project folder you just downloaded.

2. Official Install Script

Easy Recommended

Prerequisites

Node.js Node.js must be installed to use npm.
Python 3 Python is required to use pip.

npm install -g @axon-ai/cli

Installs the package published on the npm registry globally — no need to clone the source.

pip install traceloop-sdk

Installs the package published on PyPI directly — no need to clone the source.

✅ After installing, open a new terminal and run the program's version command (e.g. --version) to confirm it worked.

Pulled directly from this repo's README.

3. Docker

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Docker Desktop Needed to build and run containers. Install it and keep it running in the background.

docker volume rm axon_axon-data

Type this command into your terminal and run it.

✅ Run docker compose ps to check the containers are Up. If the README mentions a port, open http://localhost:PORT in your browser.

Pulled directly from this repo's README.

4. Node.js

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm install -g @axon-ai/cli

Installs the package published on the npm registry globally — no need to clone the source.

npm install @axon-ai/langchain-tracer

Downloads and installs the libraries listed in package.json.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

Pulled directly from this repo's README.

5. Make

Medium

Prerequisites

Git Needed to download the project code from GitHub.
Make Usually pre-installed on Linux/macOS. On Windows, install separately (e.g. via MSYS2 or WSL).

make start # start backend and dashboard

Compiles the code based on the generated build configuration to produce an executable.

make stop # stop all services

Compiles the code based on the generated build configuration to produce an executable.

make logs # stream logs from all containers

Compiles the code based on the generated build configuration to produce an executable.

make restart # restart services

Compiles the code based on the generated build configuration to produce an executable.

make clean # remove containers and volumes

Compiles the code based on the generated build configuration to produce an executable.

✅ If it finishes without errors, it worked. Try running the generated executable directly.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Axon

<p align="center">
  <img src="dashboard/public/favicon.svg" alt="Axon Logo" width="240"/>
</p>

Axon is a local observability tool for LangChain and OpenTelemetry-instrumented AI agents. It receives trace data from your application, stores it on your machine, and gives you a real-time dashboard to monitor and debug every LLM call, tool invocation, and chain execution. No cloud account is required and no data leaves your environment.

---

### Features

**Overview - shows your OTLP endpoint and integration snippets the moment Axon starts**
![Overview](https://raw.githubusercontent.com/langchain-tracer/Axon/main/docs/screenshots/overview.png)

### Trace Views

**Transcript — renders the run as a conversation with tool call inputs and outputs inline**
![Transcript](https://raw.githubusercontent.com/langchain-tracer/Axon/main/docs/screenshots/transcript.png)

**Waterfall — each span as a horizontal bar on a shared time axis with a detail panel**
![Waterfall](https://raw.githubusercontent.com/langchain-tracer/Axon/main/docs/screenshots/waterfall.png)

**Tree — parent-child span hierarchy with type icons, model names, and token counts**
![Tree](https://raw.githubusercontent.com/langchain-tracer/Axon/main/docs/screenshots/tree.png)

**Raw — full JSON of every span with a copy button**
![Raw](https://raw.githubusercontent.com/langchain-tracer/Axon/main/docs/screenshots/Raw.png)

---

## How it works

Axon runs entirely on your machine. When you start it, a single server comes up that handles two responsibilities: it accepts incoming OTLP trace data from your application, and it serves the dashboard that visualises those traces. The server writes all trace data to a local SQLite database scoped to your project directory. The dashboard connects to the server over Server-Sent Events so new spans appear in real time as your agent runs.

The tool is distributed as three packages that work together. `@axon-ai/cli` is the command-line interface you interact with. `@axon-ai/backend` is the Express server and database layer. `@axon-ai/dashboard` is the React web interface. When you install the CLI, it bundles the other two so you only need one install.

---

## Getting started

**Prerequisites**

- Node.js 18 or higher
- A LangChain or OpenTelemetry-instrumented application running in development

**Install the CLI**

```bash
npm install -g @axon-ai/cli
```

**Initialise your project**

Run this inside your project directory. It creates a `.axon-ai/` folder that holds your configuration and local trace database.

```bash
axon-ai init --project my-app
```

**Start Axon**

```bash
axon-ai start
```

This launches the backend server and opens the dashboard in your browser. By default the server runs on port 4000. The OTLP ingest endpoint is available at `http://localhost:4000/v1/traces`.

**Point your application at Axon**

For Node.js applications using `@axon-ai/langchain-tracer`:

```bash
npm install @axon-ai/langchain-tracer
```

```js
import { createAutoTracer } from '@axon-ai/langchain-tracer';
createAutoTracer({ endpoint: 'http://localhost:4000' });
```

For Python applications using OpenLLMetry:

```bash
pip install traceloop-sdk
```

```python
from traceloop.sdk import Traceloop
Traceloop.init(
  app_name="my-agent",
  api_endpoint="http://localhost:4000",
)
```

Run your application and switch to the dashboard. Traces appear automatically as your agent executes.

---

## CLI reference

| Command | Description |
|---|---|
| `axon-ai init` | Initialise Axon in the current directory |
| `axon-ai start` | Start the backend and dashboard |
| `axon-ai status` | Check whether services are running |
| `axon-ai stop` | Stop all running services |
| `axon-ai version` | Show version information |

**Options for `axon-ai init`**

- `--project <name>` sets the project name used to group traces. Defaults to `default`.
- `--auto-start` launches the dashboard immediately after initialisation.

**Options for `axon-ai start`**

- `--port <number>` sets the port for both the server and dashboard. Defaults to `4000`.
- `--no-open` prevents the browser from opening automatically.
- `--project <name>` tags incoming traces with a project name.

---

## Configuration

`axon-ai init` creates a `.axon-ai/config.json` file in your project root. You can edit it directly.

```json
{
  "project": "my-app",
  "backend": {
    "port": 4000,
    "host": "localhost"
  }
}
```

Trace data is stored in `.axon-ai/traces.db`. This file is local to your machine and is not committed to source control. Add `.axon-ai/traces.db` to your `.gitignore` if you want to keep it out of your repository.

---

## Docker

If you prefer not to install Node.js, you can run the full stack with Docker Desktop.

```bash
make start      # start backend and dashboard
make stop       # stop all services
make logs       # stream logs from all containers
make restart    # restart services
make clean      # remove containers and volumes
```

The dashboard is available at `http://localhost:8080` and the OTLP endpoint at `http://localhost:3000/v1/traces`.

To reset the trace database:

```bash
make stop
docker volume rm axon_axon-data
make start
```

---

## Troubleshooting

**Port already in use**

Another process is using the default port. Pass a different port with `axon-ai start --port 5000`.

**Dashboard does not open**

Run `axon-ai status` to confirm the server started successfully. If it did, open `http://localhost:4000` manually in your browser.

**Traces are not appearing**

Confirm your application's OTLP exporter is pointing at the correct endpoint (`http://localhost:<port>/v1/traces`). Check the terminal where `axon-ai start` is running for any ingestion errors.

**Database issues**

If the database becomes corrupted, stop Axon, delete `.axon-ai/traces.db`, and restart. All historical traces will be lost but the service will recover cleanly.

---

## Contributing

Contributions are welcome from developers of all experience levels.

To get started, fork the repository. The project is a Node.js monorepo with three workspaces: `packages/cli`, `backend`, and `dashboard`. Install dependencies from the root with `npm install`. You can run the full stack in development mode with `npm run dev`, which starts the backend and dashboard in parallel with hot reload.

When making changes, run `npm test` to execute the test suite before submitting a pull request. Please keep pull requests focused on a single concern and include a clear description of what the change does and why.

---

## License

This project is licensed under the [MIT License](LICENSE).