Torrix: AI 관측성 (Observability)

모든 LLM 요청을 추적하세요: 토큰 (tokens), 비용 (cost), 지연 시간 (latency), 전체 프롬프트 트레이스 (full prompt traces), 추론 토큰 캡처 (reasoning token capture), 그리고 개인정보 (PII) 마스킹 (masking). OpenAI, Anthropic, Google Gemini, Groq, Mistral, Azure OpenAI, DeepSeek, Perplexity, Fireworks, Together AI, Cohere, HuggingFace, Replicate, Ollama 및 모든 HTTP 엔드포인트 (endpoint)와 함께 작동합니다. 셀프 호스팅 (Self-hosted) 방식이며, 데이터가 사용자의 기기를 벗어나지 않습니다.

demo.torrix.ai에서 라이브 데모를 체험해 보세요. 회원가입은 필요하지 않습니다. 데이터는 읽기 전용이며 샘플 실행 데이터가 미리 로드되어 있습니다.

시작하기

유일한 요구 사항은 Docker Desktop입니다.

Mac

터미널 (Terminal)을 열고 다음을 실행하세요:

curl -o docker-compose.yml https://raw.githubusercontent.com/torrix-ai/install/main/docker-compose.community.yml
docker compose up

이는 커뮤니티 에디션 (community edition) 설정을 다운로드하여 docker-compose.yml로 저장하므로, Docker가 이를 자동으로 인식합니다.

Windows

PowerShell을 열고 다음을 실행하세요:

curl.exe -o docker-compose.yml https://raw.githubusercontent.com/torrix-ai/install/main/docker-compose.community.yml
docker compose up

이는 커뮤니티 에디션 (community edition) 설정을 다운로드하여 docker-compose.yml로 저장하므로, Docker가 이를 자동으로 인식합니다.

또는 파일을 수동으로 다운로드하세요:

1. github.com/torrix-ai/install로 이동합니다.
2. docker-compose.community.yml을 클릭한 다음 Raw를 클릭합니다.
3. 파일을 docker-compose.yml로 저장합니다.
4. 해당 폴더에서 터미널을 열고 docker compose up을 실행합니다.

시작 후

1. http://localhost:8088을 엽니다.
2. 계정을 생성합니다.
3. 설정 (Settings)에서 API 키 (API key)를 복사합니다.
4. 프록시 (proxy) 또는 SDK를 통해 LLM 호출을 보내기 시작합니다.

설정 확인

서버가 실행 중인지 확인합니다 (API 키 불필요):

curl http://localhost:8088/health

예상 응답:

{"ok":true,"name":"Torrix","version":"2.0.0"}

실행 로그가 기록되고 있는지 확인합니다 (설정에서 가져온 API 키 필요):

Mac / Linux:

curl http://localhost:8088/api/runs -H "Authorization: Bearer <your-torrix-api-key>"

Windows (PowerShell):

Invoke-WebRequest http://localhost:8088/api/runs -Headers @{Authorization="Bearer <your-torrix-api-key>"} | Select-Object -ExpandProperty Content

기록된 모든 실행 (runs) 목록을 반환합니다. 빈 배열 []은 서버는 작동 중이지만 아직 전송된 실행이 없음을 의미합니다.

테스트 실행 전송하기

Torrix 프록시 (proxy)를 통해 실제 요청을 보내 대시보드에 실행이 나타나는지 확인합니다. OpenAI 키가 유효하지 않더라도 Torrix는 해당 시도를 기록합니다.

Mac / Linux:

curl -X POST http://localhost:8088/proxy \
  -H "Authorization: Bearer <your-torrix-api-key>" \
  -H "x-target-url: https://api.openai.com/v1/chat/completions" \
...

Windows (PowerShell):

Invoke-WebRequest -Method Post http://localhost:8088/proxy `
  -Headers @{
    "Authorization"="Bearer <your-torrix-api-key>";
...

그 다음 http://localhost:8088을 엽니다. 실행 결과가 대시보드에 나타나야 합니다.

Torrix로 데이터 전송하기

옵션 1: Python SDK

pip install torrix

OpenAI:

import torrix
from openai import OpenAI

...

Anthropic:

from anthropic import Anthropic

client = torrix.wrap(Anthropic(api_key="<your-anthropic-key>"))
...

스트리밍 (Streaming):

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}],
...

옵션 2: Node.js SDK

npm install torrix openai
# 또는: npm install torrix @anthropic-ai/sdk

OpenAI:

import * as torrix from 'torrix'
import OpenAI from 'openai'

...

Anthropic:

import Anthropic from '@anthropic-ai/sdk'

const client = torrix.wrap(new Anthropic({ apiKey: '<your-anthropic-key>' }))
...

옵션 3: Go SDK

go get torrix.ai/sdk/go

package main

import (
...

전체 레퍼런스는 docs/go-sdk.md를 참조하세요.

옵션 4: C# / .NET SDK

dotnet add package Torrix

using TorrixAI;

Torrix.Init("<your-torrix-api-key>", new TorrixOptions
...

.NET 6 이상을 대상으로 합니다. 외부 의존성(external dependencies)이 전혀 없습니다. OpenAI, Azure OpenAI, 그리고 SAP AI Core와 함께 사용할 수 있습니다.

Azure OpenAI, SAP AI Core 예제 및 전체 API 레퍼런스는 docs/csharp-sdk.md를 참조하세요.

옵션 5: Java SDK

Maven:

<dependency>
  <groupId>ai.torrix</groupId>
  <artifactId>torrix</artifactId>
...

Gradle: implementation 'ai.torrix:torrix:0.2.0'

import ai.torrix.*;

Torrix.init(System.getenv("TORRIX_API_KEY"),
...

Java 11 이상을 대상으로 합니다. 외부 의존성(external dependencies)이 전혀 없습니다. Spring AI, LangChain4j, OpenAI Java SDK 및 모든 Java HTTP 클라이언트와 함께 사용할 수 있습니다.

전체 레퍼런스는 docs/java-sdk.md를 참조하세요.

옵션 6: LangChain 콜백 (callback)

TorrixCallbackHandler를 사용하여 LangChain LLM 또는 ChatModel을 통해 이루어지는 모든 LLM 호출을 추적(trace)하세요.

pip install torrix langchain-core

import torrix
from torrix.wrappers.langchain_callback import TorrixCallbackHandler
from langchain_openai import ChatOpenAI
...

모든 호출은 모델, 토큰 수(token counts), 지연 시간(latency), 프롬프트(prompt) 및 응답(response)과 함께 Torrix에 기록됩니다. 모든 LangChain LLM 또는 ChatModel과 함께 사용할 수 있습니다.

옵션 7: HTTP 프록시 (HTTP Proxy) (모든 언어 또는 도구)

모든 HTTP 요청을 Torrix를 통해 라우팅하세요. Google Gemini, Azure OpenAI, Groq, Mistral, DeepSeek, Perplexity, Fireworks, Together AI, Cohere, HuggingFace, Replicate, SAP AI Core, GitHub Copilot, n8n, Make, curl 및 모든 OpenAI 호환 API와 함께 사용할 수 있습니다.

curl -X POST http://localhost:8088/proxy \
  -H "Authorization: Bearer <your-torrix-api-key>" \
  -H "x-target-url: https://api.openai.com/v1/chat/completions" \
...

헤더 (Header)

Google Gemini (Bearer 토큰 대신 ?key= 사용):

import requests

response = requests.post(
...

Azure OpenAI:

curl -X POST http://localhost:8088/proxy \
  -H "Authorization: Bearer <your-torrix-api-key>" \
  -H "x-target-url: https://<your-resource>.openai.azure.com/openai/deployments/<your-deployment>/chat/completions?api-version=2024-02-01" \
...

Groq:

curl -X POST http://localhost:8088/proxy \
  -H "Authorization: Bearer <your-torrix-api-key>" \
  -H "x-target-url: https://api.groq.com/openai/v1/chat/completions" \
...

Mistral:

curl -X POST http://localhost:8088/proxy \
  -H "Authorization: Bearer <your-torrix-api-key>" \
  -H "x-target-url: https://api.mistral.ai/v1/chat/completions" \
...

DeepSeek:

curl -X POST http://localhost:8088/proxy \
  -H "Authorization: Bearer <your-torrix-api-key>" \
  -H "x-target-url: https://api.deepseek.com/chat/completions" \
...

Ollama (로컬 모델):

curl -X POST http://localhost:8088/proxy \
  -H "Authorization: Bearer <your-torrix-api-key>" \
  -H "x-target-url: http://host.docker.internal:11434/v1/chat/completions" \
...

Ollama의 경우 API 키가 필요하지 않습니다. x-upstream-authorization는 생략합니다. Mac 또는 Windows에서 Docker를 사용하여 Torrix를 실행할 때는 localhost 대신 host.docker.internal을 사용하십시오. Linux에서는 실제 장치 IP 주소(예: 172.17.0.1)를 사용하십시오.

사용자별 비용 추적 (Per-user cost tracking)

요청마다 사용자 식별자를 전달하여 실행을 최종 사용자에게 속하게 할 수 있습니다.

프록시 헤더를 통해:

curl -X POST http://localhost:8088/proxy \
  -H "Authorization: Bearer <your-torrix-api-key>" \
  -H "x-target-url: https://api.openai.com/v1/chat/completions" \
...

Python SDK 수집 (ingest)을 통해:

torrix.ingest(model="gpt-4o-mini", ..., user_id="alice")

Analytics (분석) 페이지에는 사용자별 요청 횟수, 총 토큰 사용량 및 비용 내역이 포함된 By User (사용자별) 테이블이 표시됩니다.

n8n 워크플로우 (workflow): 다음 헤더를 포함하여 http://host.docker.internal:8088/proxy를 가리키는 HTTP Request 노드를 사용하세요:

n8n 커뮤니티 노드 (Community Node)

네이티브 드래그 앤 드롭 (drag-and-drop) 경험을 위해 n8n에 공식 Torrix 노드를 직접 설치하세요:

1. n8n에서 **Settings (설정) → Community Nodes (커뮤니티 노드)**로 이동합니다.
2. **Install (설치)**를 클릭하고 @torrix-ai/n8n-nodes-torrix를 입력합니다.
3. 안내에 따라 n8n을 재시작합니다.
4. 노드 팔레트에 Torrix Proxy 노드가 나타납니다.

또는 바로 사용할 수 있는 워크플로우 템플릿을 가져올 수 있습니다:

1. torrix-workflow-template.json을 다운로드합니다.
2. n8n에서 **Workflows (워크플로우) → Import from file (파일에서 가져오기)**로 이동합니다.
3. 워크플로우 내부의 설정 노트를 따릅니다.

옵션 8: 브라우저 확장 프로그램 (Browser Extension)

Torrix Chrome 확장 프로그램은 코드 변경이나 API 키 재라우팅 없이 AI 채팅 플랫폼의 대화를 캡처합니다.

지원 플랫폼: ChatGPT, Claude, Gemini, Perplexity, Grok, Microsoft Copilot, Mistral

옵션 9: OpenTelemetry (zero-SDK)

모든 OpenTelemetry GenAI 계측 (instrumentation) 라이브러리를 Torrix로 연결하세요. Torrix SDK는 필요하지 않습니다.

OTLP 익스포터 (exporter) 엔드포인트를 http://localhost:8088/v1/traces로 설정하고, Authorization: Bearer trxk_...를 통해 Torrix API 키를 전달하세요.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:8088
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer trxk_your_key_here"

opentelemetry-instrumentation-openai (Python), Spring AI OTel (Java), @arizeai/openinference-instrumentation-openai (Node.js) 및 gen_ai.* 스팬 (span) 속성을 방출하는 모든 라이브러리와 함께 작동합니다.

전체 설정 예시는 docs/otel.md를 참조하세요.

옵션 10: MCP 도구 프록시 (MCP Tool Proxy)

옵션 10: MCP 도구 프록시 (MCP Tool Proxy)

모든 HTTP MCP 클라이언트를 Torrix를 통해 라우팅하여 도구 이름(tool name), 인자(arguments), 결과(result), 지연 시간(latency) 및 상태(status)와 함께 모든 tools/call 호출을 기록(log)할 수 있습니다. 핸드셰이크 메시지(initialize, tools/list, ping)는 기록되지 않고 조용히 전달됩니다.

curl -X POST http://localhost:8088/mcp-proxy \
  -H "Authorization: Bearer trxk_your_key_here" \
  -H "x-target-mcp-url: https://your-mcp-server.com/mcp" \
...

x-torrix-trace를 전달하면 추적 뷰(trace view)에서 도구 호출을 상위 LLM 실행(run)과 연결할 수 있습니다.

Claude Desktop, Cursor 및 Python 에이전트 설정 예제는 docs/mcp-proxy.md를 참조하세요.

설정:

1. Chrome 웹 스토어에서 Torrix 확장 프로그램을 설치합니다 (출시 예정)
2. 확장 프로그램 팝업을 열고 설정 아이콘을 클릭합니다
3. Torrix 서버 URL(기본값: http://localhost:8088)과 API 키를 입력합니다
4. 지원되는 모든 AI 플랫폼을 평소처럼 사용합니다. 모든 대화는 자동으로 캡처됩니다.

캡처된 모든 데이터는 귀하의 Torrix 인스턴스로 직접 전송됩니다. Torrix나 제3자에게는 아무것도 전송되지 않습니다.

에이전트 추적 그룹화 (Agent trace grouping)

에이전트 실행(agent run)의 모든 호출에 x-torrix-trace를 추가하여 이를 단일 체인 타임라인(chain timeline)으로 그룹화하세요. 에이전트 호출당 하나의 UUID를 생성하고 모든 단계에서 이를 재사용합니다:

TRACE_ID=$(python3 -c "import uuid; print(uuid.uuid4())")

# Step 1
...

두 실행 모두 실행 목록(Runs list)에 trace 배지와 함께 나타납니다. 이를 클릭하면 모델, 토큰(tokens), 비용(cost) 및 지연 시간(latency)과 함께 각 단계를 보여주는 체인 타임라인이 열립니다.

대화 세션 그룹화 (Conversation session grouping)

멀티턴 대화(multi-turn conversation)의 모든 호출에 x-torrix-session을 추가하여 이를 함께 그룹화하세요. 대화당 하나의 세션 ID를 생성하고 모든 턴(turn)에서 이를 재사용합니다:

SESSION_ID=$(python3 -c "import uuid; print(uuid.uuid4())")

# Turn 1
...

실행은 턴 횟수를 보여주는 session 배지와 함께 나타납니다. 이를 클릭하면 결합된 비용 및 토큰과 함께 전체 대화를 볼 수 있습니다.

실시간 비용 추적 (Real-time cost tracking)

모든 API 호출은 토큰 수, 모델, 비용 및 지연 시간 (Latency)과 함께 기록됩니다. 비용이 발생하는 즉시 정확히 무엇에 지출하고 있는지 확인하세요.

회귀 테스트 (Regression testing (Evals))

모든 실행 (Run)을 골든 베이스라인 (Golden baseline)으로 지정할 수 있습니다. 클릭 한 번으로 LLM에 대해 이를 다시 실행 (Replay)하고 출력을 나란히 비교해 보세요. 모델을 교체하거나 프롬프트 (Prompt)를 변경할 때 발생하는 회귀 (Regression) 현상을 포착할 수 있습니다.

Evals 페이지의 각 행에 있는 체크박스를 사용하여 개별 골든 실행 (Golden runs)을 선택하거나 한꺼번에 선택한 다음, Export JSONL을 클릭하여 OpenAI 호환 미세 조정 (Fine-tuning) 파일을 다운로드하세요.

모델 비용 비교 (Model cost comparison)

모든 실행 상세 페이지에서 동일한 요청이 300개 이상의 모델에서 얼마의 비용이 들었을지 실시간 가격과 함께 가장 저렴한 것부터 가장 비싼 순으로 확인할 수 있습니다.

예산 제어 (Budget controls)

설정 (Settings)에서 소프트 경고 임계값 (Soft alert threshold)과 하드 캡 (Hard cap)을 설정할 수 있습니다.

경고 임계값 (Alert threshold): 일일 지출이 임계값을 초과하면 Torrix가 웹훅 (Webhook)을 발송합니다. 하루에 한 번 발송됩니다. Slack 웹훅 URL (https://hooks.slack.com/)은 자동으로 네이티브 Slack Block Kit 메시지 형식으로 구성됩니다.