nexarch-sdk 0.1.0

Nexarch SDK for runtime architecture intelligence and observability

Nexarch SDK - Python

Runtime architecture intelligence SDK for FastAPI applications.

Installation

From PyPI (once published)

pip install nexarch-sdk

From Source (Development)

cd SDK
pip install -e .

Quick Start

Basic Usage

from fastapi import FastAPI
from nexarch import NexarchSDK

# Create your FastAPI app
app = FastAPI(title="My API")

# Initialize Nexarch SDK
sdk = NexarchSDK(
    api_key="your_api_key_here",
    environment="production",
    log_file="nexarch_telemetry.json"
)

# Attach SDK to your app (auto-injects middleware and router)
sdk.init(app)

# Your existing routes
@app.get("/")
def read_root():
    return {"message": "Hello World"}

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id, "name": "John Doe"}

One-Line Initialization

from fastapi import FastAPI
from nexarch import NexarchSDK

app = FastAPI()

# Initialize in one line
NexarchSDK.start(app, api_key="your_api_key")

What Gets Captured

The SDK automatically captures:

• All HTTP Requests: Method, path, query parameters, latency, status codes
• All Errors: Exception types, messages, full tracebacks
• Performance Metrics: Request latency, throughput, error rates
• Dependency Calls: Database queries, external API calls (future)

Auto-Injected Endpoints

The SDK automatically adds internal management endpoints:

# Check SDK health
GET /__nexarch/health

# Get all telemetry data
GET /__nexarch/telemetry

# Get telemetry statistics
GET /__nexarch/telemetry/stats

# Get only errors
GET /__nexarch/telemetry/errors

# Get only request spans
GET /__nexarch/telemetry/spans

# Clear all telemetry
DELETE /__nexarch/telemetry

Local Telemetry Storage

All telemetry is stored locally in JSON format:

[
  {
    "type": "span",
    "timestamp": "2026-04-02T13:00:00.000Z",
    "data": {
      "trace_id": "abc-123",
      "operation": "GET /users/1",
      "latency_ms": 45.2,
      "status_code": 200,
      "status": "ok"
    }
  },
  {
    "type": "error",
    "timestamp": "2026-04-16T10:31:00.000Z",
    "data": {
      "error_type": "ValueError",
      "error_message": "Invalid user ID",
      "traceback": "..."
    }
  }
]

Configuration Options

sdk = NexarchSDK(
    api_key="your_api_key",              # Required: Your Nexarch API key
    environment="production",             # Optional: Environment name
    log_file="nexarch_telemetry.json",   # Optional: Local log file path
    observation_duration="3h",            # Optional: How long to observe
    sampling_rate=1.0,                    # Optional: Sample rate (0.0-1.0)
    enable_local_logs=True                # Optional: Enable local logging
)

Example: Complete FastAPI App

from fastapi import FastAPI, HTTPException
from nexarch import NexarchSDK

app = FastAPI(title="User Service")

# Initialize Nexarch
sdk = NexarchSDK(
    api_key="demo_api_key",
    environment="production",
    log_file="telemetry.json"
)
sdk.init(app)

# Simulated database
users_db = {
    1: {"id": 1, "name": "Alice"},
    2: {"id": 2, "name": "Bob"}
}

@app.get("/")
def root():
    return {"message": "User Service API"}

@app.get("/users/{user_id}")
def get_user(user_id: int):
    if user_id not in users_db:
        raise HTTPException(status_code=404, detail="User not found")
    return users_db[user_id]

@app.post("/users")
def create_user(user: dict):
    user_id = max(users_db.keys()) + 1
    users_db[user_id] = {"id": user_id, **user}
    return users_db[user_id]

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Building the Package

# Install build tools
pip install build twine

# Build the package
python -m build

# This creates:
# - dist/nexarch_sdk-0.1.0-py3-none-any.whl
# - dist/nexarch_sdk-0.1.0.tar.gz

Publishing to PyPI

# Test PyPI (for testing)
twine upload --repository testpypi dist/*

# Production PyPI
twine upload dist/*

Testing Locally

# Install in editable mode
pip install -e .

# Run your FastAPI app
python your_app.py

# Check telemetry
curl http://localhost:8000/__nexarch/telemetry/stats

What Happens After Installation

1. Middleware Injection: SDK adds middleware to capture every request
2. Router Auto-Injection: Internal /__nexarch/* endpoints are added
3. Local Logging: Telemetry is written to JSON file in real-time
4. No Code Changes: Your existing routes work exactly as before

Security & Privacy

• No Source Code Access: SDK only observes runtime behavior
• No Payload Capture: Request/response bodies are never logged
• Header Sanitization: Sensitive headers (auth, cookies) are redacted
• Local First: All data stored locally before optional remote sync

Support

• Documentation: https://docs.nexarch.io
• GitHub: https://github.com/nexarch/nexarch-sdk
• Email: [e-mail]