Axon - GitLite

KO | EN

gitlite — search

#python #react #ai #go #machine-learning #rust #macos #cli #kubernetes #awesome-list #vue #security #mcp #open-source

Axon

(★ 155)

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

파일 탐색기

최종 버전 다운로드 (.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

# 설치 가이드

1. 코드 내려받기

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

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd Axon

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. 공식 설치 스크립트

쉬움 추천

사전 준비물

Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다.
Python 3 pip 명령어를 쓰려면 Python이 필요합니다.

npm install -g @axon-ai/cli

npm 레지스트리에 배포된 패키지를 전역으로 설치합니다. 소스 클론이 필요 없습니다.

pip install traceloop-sdk

PyPI에 배포된 패키지를 바로 설치합니다. 소스 클론이 필요 없습니다.

✅ 설치 후 새 터미널을 열고, 프로그램의 버전 확인 명령(예: --version)으로 정상 설치됐는지 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

3. Docker

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Docker Desktop 컨테이너를 빌드하고 실행하려면 필요합니다. 설치 후 실행해서 백그라운드에 켜두세요.

docker volume rm axon_axon-data

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ 터미널에 docker compose ps 를 입력해 컨테이너들이 Up 상태인지 확인하세요. README에 포트 번호가 적혀있다면 브라우저에서 http://localhost:포트번호 로 접속해보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

4. Node.js

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

npm install -g @axon-ai/cli

npm 레지스트리에 배포된 패키지를 전역으로 설치합니다. 소스 클론이 필요 없습니다.

npm install @axon-ai/langchain-tracer

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

5. Make

보통

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Make Linux/macOS는 보통 기본 설치되어 있습니다. Windows는 별도 설치(예: MSYS2, WSL)가 필요합니다.

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

생성된 빌드 설정을 바탕으로 실제 컴파일을 진행해 실행 파일을 만듭니다.

✅ 에러 없이 끝나면 성공입니다. 생성된 실행 파일을 직접 실행해보세요.

이 레포의 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).