What is Feenion?

Docker Quickstart

Spin up the complete Feenion server and React dashboard with embedded SQLite WAL storage in one command:

git clone https://github.com/DarshanAguru/feenion.git
cd feenion
docker compose up -d

Open http://localhost:8000 in your browser to view the live dashboard.

Python SDK Setup

Install the official lightweight Python SDK in your application environment:

pip install feenion

Your First 5-Minute Trace

Configure the client and annotate your functions with @trace and span():

from feenion import trace, span, configure

# Point SDK to your local or self-hosted server
configure(server_url="http://localhost:8000")

@trace(name="customer_support_agent", span_type="agent")
def handle_query(user_query: str):
    with span("vector_kb_search", span_type="retrieval", input={"q": user_query}):
        docs = ["Reset password at /settings", "API keys are under Security"]

    with span("llm_synthesis", span_type="llm"):
        return f"Answer for {user_query}: {docs[0]}"

handle_query("How do I reset my password?")

Traces, Spans & Events Data Model

Feenion models execution as a hierarchical Directed Acyclic Graph (DAG):

• Trace: The top-level root operation representing the end-to-end request (e.g. an API endpoint or agent task).
• Span: A timed unit of work within a trace (e.g., LLM generation, vector search, tool execution, function call).
• Event: An instantaneous timestamped milestone attached to a span (e.g. streaming first token received).

Context Propagation

Feenion uses Python's native contextvars.ContextVar to maintain the current active trace and parent span IDs across nested sync and async calls without requiring manual ID passing.

Pluggable Telemetry Exporters

Feenion provides 5 built-in, decoupled exporters for any production or testing setup:

• AsyncExporter(inner): Non-blocking daemon worker with an in-memory queue flushing batches every 500ms without slowing down request loops.
• HTTPExporter(endpoint, api_key, project_id): Direct HTTP ingestion transport to the Feenion server with tenant API key authentication.
• JSONLExporter(filepath): Structured append-only local file logging for air-gapped environments, CI pipelines, and offline trace replay.
• ConsoleExporter(verbose): Real-time formatted terminal output for local developer interactive debugging.
• CompositeExporter([exporters]): Broadcasts telemetry to multiple targets simultaneously (e.g. streaming to remote HTTP while saving local JSONL audit files).

from feenion import configure
from feenion.exporters import AsyncExporter, HTTPExporter, CompositeExporter, JSONLExporter

# Composite: Async HTTP upload + local JSONL audit trail
configure(
    exporter=CompositeExporter([
        AsyncExporter(HTTPExporter("http://localhost:8000", api_key="feenion_key", project_id="finance-prod")),
        JSONLExporter("traces_audit.jsonl"),
    ])
)

Multi-Tenant Workspace Routing & Authentication

Telemetry in Feenion is routed strictly using each workspace's unique Workspace ID (obtained from the Settings page):

import feenion
from feenion import trace

# Option 1: Global Workspace Configuration by Workspace ID
feenion.configure(
    server_url="http://localhost:8000",
    workspace_id="60d03b94-82a1-4328-874e-7b5fbfbc4402",
    api_key="fn_live_...",  # Optional for local instance, required for auth
)

# Option 2: Dynamic Per-Agent / Per-Trace Workspace Routing (with Auth)
@trace(
    name="compliance_scanner",
    workspace_id="60d03b94-82a1-4328-874e-7b5fbfbc4402",
    api_key="fn_live_...",
)
def run_compliance():
    # Or attach dynamically inside any function:
    feenion.set_workspace_id("60d03b94-82a1-4328-874e-7b5fbfbc4402")
    feenion.set_api_key("fn_live_...")
    return "completed"

@trace & @async_trace Decorators

Decorate any synchronous or asynchronous Python function to automatically track execution:

from feenion import async_trace

@async_trace(name="async_pipeline", span_type="agent")
async def process_stream(payload: dict):
    await asyncio.sleep(0.05)
    return {"status": "success"}

span() Context Manager

Use the span() context manager for sub-operations:

with span("db_lookup", span_type="tool", input={"user_id": 42}) as s:
    result = db.query(...)
    s.set_output(result)
    s.set_metric("rows_returned", len(result))

Token & Cost Tracking • Multi-Currency Support

Feenion contains built-in pricing tables for standard models (e.g. GPT-4o, Claude 3.5 Sonnet, Gemini 2.0 Flash, DeepSeek). You can also set custom token usage and model overrides in code or via the Web Dashboard:

s.set_tokens(prompt_tokens=512, completion_tokens=128)
s.set_attribute("model", "gpt-4o")

# Override pricing directly in code (per 1M tokens):
from feenion import set_model_pricing
set_model_pricing("my-fine-tuned-model", prompt_per_1m=1.20, completion_per_1m=3.80)

Client-Side Sensitive PII & Secret Redaction

Mask sensitive fields in payload dicts before they leave application memory:

from feenion.redaction import Redactor

redactor = Redactor(sensitive_keys={"api_key", "password", "auth_token", "ssn"})
safe_payload = redactor.redact(raw_payload)

Azure OpenAI & Azure AI Foundry

Wrap Azure OpenAI (openai.AzureOpenAI or LangChain langchain_openai.AzureChatOpenAI) in one call:

from langchain_openai import AzureChatOpenAI
from feenion.integrations import wrap_azure_openai

# Auto-instruments .invoke(), .ainvoke(), tokens, and pricing
llm = wrap_azure_openai(AzureChatOpenAI(
    azure_endpoint="https://my-resource.openai.azure.com/",
    api_key="AZURE_API_KEY",
    azure_deployment="gpt-4o",
    api_version="2024-02-01",
))

response = llm.invoke([("user", "Analyze compliance report #1024")])

OpenAI Auto-Instrumentation

Wrap the official OpenAI client or LangChain ChatOpenAI:

from openai import OpenAI
from feenion.integrations.openai import wrap_openai

client = wrap_openai(OpenAI())

Google Gemini Auto-Instrumentation

Wrap Google Gemini clients (google-genai or google-generativeai) in one line:

from google import genai
from feenion.integrations.gemini import instrument_gemini

client = genai.Client()
instrument_gemini(client)

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="Explain vector embeddings in machine learning."
)

Anthropic Claude Auto-Instrumentation

from anthropic import Anthropic
from feenion.integrations.anthropic import instrument_anthropic

client = Anthropic()
instrument_anthropic(client)

LangChain & LangGraph Callbacks

from feenion.integrations.langchain import FeenionCallbackHandler

handler = FeenionCallbackHandler(trace_name="rag_chain")
chain.invoke({"topic": "AI Debugging"}, config={"callbacks": [handler]})

RAG & Vector Retrieval Observability

Instrument retrieval spans to capture similarity scores, chunk IDs, and query text:

with span("chroma_kb_query", span_type="retrieval", input={"query": q, "top_k": 5}) as s:
    chunks = vector_store.similarity_search_with_score(q, k=5)
    s.set_output([{"text": doc.page_content, "score": score} for doc, score in chunks])

Autonomous Agents & Tool Calling

Track multi-turn reasoning loops, tool call arguments, execution outputs, and error recovery:

with span("sql_executor", span_type="tool", input={"sql": query_str}) as s:
    s.set_attribute("tool_name", "database_reader")
    res = db.execute(query_str)
    s.set_output(res)

Waterfall Timeline & Critical Path

The Waterfall Timeline view provides an interactive flamegraph of all child spans. Feenion automatically highlights the critical path that contributed most to the overall request duration, allowing you to instantly spot latency bottlenecks.

D3 Execution DAG Mind Map

The Mind Map view renders the full parent-child causality tree of your AI execution. Link distances scale proportionally to latency, and color-coded nodes represent LLMs (purple), retrievals (amber), tools (cyan), and exceptions (rose).

Semantic Error Intelligence

Feenion clusters similar exceptions using semantic error fingerprinting. Click any fingerprint to see the full stack trace, occurrence frequency, affected models, and deep links to sample traces.

Comparative Trace Regression Diff

Open two traces side-by-side to immediately compare durations, token inflations, cost variances, and prompt differences to determine why a regression occurred.

Production Docker Deployment

Deploy Feenion as a single all-in-one container using SQLite Write-Ahead Logging:

version: '3.8'
services:
  feenion:
    image: feenion/feenion:latest
    ports:
      - "8000:8000"
    environment:
      - FEENION_DATABASE_URL=sqlite:////app/data/feenion.db
      - FEENION_RETENTION_DAYS=30
    volumes:
      - feenion_data:/app/data
    restart: unless-stopped

Environment Variables Reference