Metadata-Version: 2.4
Name: ikc-log-center
Version: 1.1.0
Summary: Lightweight SDK + Server for log_center — decorator-based instrumentation with HTTP/gRPC/Celery delivery, multi-backend storage, and search UI.
Author-email: shark8848 <admin@sharky-ai.com>
License: MIT
License-File: LICENSE
Keywords: instrumentation,log-center,logging,telemetry,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Logging
Requires-Python: >=3.10
Requires-Dist: requests>=2.28
Provides-Extra: agent
Requires-Dist: deepagents>=0.2; extra == 'agent'
Requires-Dist: langchain-mcp-adapters>=0.1; extra == 'agent'
Requires-Dist: langchain-openai>=0.3; extra == 'agent'
Requires-Dist: mcp-server-git>=0.6; extra == 'agent'
Provides-Extra: all
Requires-Dist: celery>=5.0; extra == 'all'
Requires-Dist: deepagents>=0.2; extra == 'all'
Requires-Dist: fastapi>=0.100; extra == 'all'
Requires-Dist: flask>=2.0; extra == 'all'
Requires-Dist: grpcio>=1.50; extra == 'all'
Requires-Dist: langchain-mcp-adapters>=0.1; extra == 'all'
Requires-Dist: langchain-openai>=0.3; extra == 'all'
Requires-Dist: mcp-server-git>=0.6; extra == 'all'
Requires-Dist: mcp>=1.28; extra == 'all'
Requires-Dist: mysql-connector-python>=8.0; extra == 'all'
Requires-Dist: oracledb>=2.0; extra == 'all'
Requires-Dist: psycopg[binary]>=3.0; extra == 'all'
Requires-Dist: sqlalchemy>=2.0; extra == 'all'
Requires-Dist: starlette; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.20; extra == 'all'
Provides-Extra: celery
Requires-Dist: celery>=5.0; extra == 'celery'
Provides-Extra: dev
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == 'fastapi'
Requires-Dist: starlette; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.0; extra == 'flask'
Provides-Extra: grpc
Requires-Dist: grpcio>=1.50; extra == 'grpc'
Provides-Extra: mcp
Requires-Dist: mcp>=1.28; extra == 'mcp'
Provides-Extra: mysql
Requires-Dist: mysql-connector-python>=8.0; extra == 'mysql'
Provides-Extra: oracle
Requires-Dist: oracledb>=2.0; extra == 'oracle'
Provides-Extra: pg
Requires-Dist: psycopg[binary]>=3.0; extra == 'pg'
Provides-Extra: server
Requires-Dist: fastapi>=0.100; extra == 'server'
Requires-Dist: sqlalchemy>=2.0; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.20; extra == 'server'
Provides-Extra: ui
Description-Content-Type: text/markdown

<p align="center">
  <img src="ikc-log-center-banner.png" alt="IKC Log Center" width="100%" />
</p>

<p align="center">
  <strong>Lightweight SDK + Centralized Log Service</strong><br/>
  Auto-capture · Multi-transport · Multi-backend · MCP for AI
</p>

<p align="center">
  <a href="https://pypi.org/project/ikc-log-center/"><img src="https://img.shields.io/pypi/v/ikc-log-center" alt="PyPI" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="MIT" /></a>
  <img src="https://img.shields.io/badge/Python-3.10%2B-blue" alt="Python 3.10+" />
</p>

<p align="center">
  <b>English</b> |
  <a href="README_zh.md">中文</a> |
  <a href="README_ja.md">日本語</a> |
  <a href="README_fr.md">Français</a> |
  <a href="README_de.md">Deutsch</a> |
  <a href="README_es.md">Español</a>
</p>

---

## Overview

**IKC Log Center** is a lightweight, Python-first logging platform consisting of a **Client SDK** and a **Central Server**:

- **SDK** — decorator-based auto-instrumentation with structured JSON logs, delivered via HTTP / gRPC / Celery.
- **Server** — receives, stores, and searches logs with pluggable backends (SQLite / MySQL / PostgreSQL / Elasticsearch), plus a built-in React Web UI, MCP server for AI agents, Bearer Token authentication, and an embedded **AI Agent** for intelligent log analysis.

```
App (SDK) ──HTTP/gRPC/Celery──▶ Log Center Server ──▶ SQLite / MySQL / PG / ES
                                       │
                                 Web UI · MCP · Token Auth
```

## Features

| Category | Highlights |
|----------|-----------|
| Auto-capture | `@instrumented` decorator — duration, status, args logging with slow-call detection |
| Multi-transport | HTTP POST, gRPC unary, Celery task — combinable via env var |
| Multi-backend | SQLite (zero-config), MySQL, PostgreSQL, Elasticsearch |
| Trace analysis | Distributed trace_id / span_id propagation across FastAPI, Flask, Celery |
| Web UI | React-based search, dashboard, trace chain visualization, token management |
| MCP for AI | Expose log search as MCP tools — AI Agent ready |
| AI Agent | Built-in LangGraph agent — log analysis, Git repo reading, DB queries, artifact generation |
| Auth | OpenAI-style `sk-lc-*` Bearer tokens with SHA-256 hash storage |
| Ops-friendly | Rotating file logs, 7-day retention, shell scripts, CLI tools |

## Installation

```bash
# Client SDK only
pip install ikc-log-center                        # HTTP delivery (default)
pip install ikc-log-center[grpc]                  # + gRPC delivery
pip install ikc-log-center[celery]                # + Celery delivery
pip install ikc-log-center[fastapi]               # + FastAPI middleware
pip install ikc-log-center[flask]                 # + Flask hooks

# Server
pip install ikc-log-center[server]                # HTTP server + SQLite
pip install ikc-log-center[mcp]                   # + MCP server
pip install ikc-log-center[agent]                 # + AI Agent (LangGraph)
pip install ikc-log-center[server,mysql]          # + MySQL backend
pip install ikc-log-center[server,pg]             # + PostgreSQL backend

# Everything
pip install ikc-log-center[all]
```

## Quick Start

### 1. Start the Server

```bash
# HTTP API on :9315 (SQLite storage, zero config)
log-center-server

# With gRPC (:9316) and Web UI
log-center-server --grpc --ui

# Or use shell scripts
./start-log-center.sh
./show-log-center.sh
./stop-log-center.sh
```

### 2. Instrument Your App

```python
from log_center_sdk import configure, instrumented

configure(module_name="my_app")

@instrumented("process_order", slow_threshold_ms=500)
def process_order(order_id: str, amount: float):
    ...

@instrumented("llm_call", log_args={"model"}, redact_args={"api_key"})
async def call_llm(prompt: str, model: str, api_key: str):
    ...
```

Enable remote delivery:

```bash
LOG_CENTER_ENABLE=true \
LOG_CENTER_URL=http://localhost:9315 \
python my_app.py
```

### 3. Framework Integrations

**FastAPI:**
```python
from log_center_sdk.integrations.fastapi import TraceMiddleware
app.add_middleware(TraceMiddleware)
```

**Flask:**
```python
from log_center_sdk.integrations.flask import init_trace_hooks
init_trace_hooks(app)
```

**Celery Workers:**
```python
from log_center_sdk import patch_celery_app
patch_celery_app(app)  # auto-reinit handlers after fork
```

## Delivery Modes

| Mode | Protocol | Port | Best For |
|------|----------|------|----------|
| `api` | HTTP POST JSON | 9315 | Cross-network, external apps |
| `grpc` | gRPC unary JSON bytes | 9316 | Low-latency internal network |
| `celery` | Redis queue + send_task | 6379 | Apps with existing Celery |

Combine modes: `LOG_CENTER_DELIVERY=grpc,api`

## MCP Server (AI Agent Ready)

Expose log search capabilities as MCP tools for AI agents:

```bash
pip install ikc-log-center[mcp]
log-center-mcp
```

## AI Agent

Built-in intelligent assistant powered by LangGraph, capable of log analysis, Git repository reading, database queries, and file artifact generation.

```bash
pip install ikc-log-center[agent]
log-center-server --agent
```

| Capability | Description |
|------------|-------------|
| Log analysis | Search and analyze logs via MCP tools |
| Git repos | Clone & read repositories (read-only, write ops blocked) |
| Database queries | MySQL / PostgreSQL / Oracle — forced read-only |
| Artifacts | Generate downloadable files (reports, code, etc.) |
| Work modes | `auto` (tools run automatically) or `approval` (human-in-the-loop confirmation) |
| Memory | Conversation memory with auto-extraction of key facts |

> **Safety**: Git write operations (commit, push, add, reset) and all database write operations (INSERT, UPDATE, DELETE, DDL) are strictly blocked.

## Authentication

OpenAI-style Bearer Token auth. Tokens (`sk-lc-<48 hex>`) are stored as SHA-256 hashes; plaintext is shown only once at creation.

```bash
# Generate a token
log-center-server --gen-token "production server"

# List / revoke tokens
log-center-server --list-tokens
log-center-server --revoke-token "sk-lc-a1b2"

# Start server with auth enabled
LOG_CENTER_AUTH_ENABLED=true log-center-server --ui
```

Client SDK carries the token:

```bash
LOG_CENTER_TOKEN=sk-lc-xxxxx LOG_CENTER_ENABLE=true LOG_CENTER_URL=http://server:9315 python my_app.py
```

> `/health`, `/docs`, `/openapi.json` are always auth-free.

## Storage Backends

| Backend | `LOG_CENTER_STORE` | Extra Deps |
|---------|-------------------|------------|
| Local file + SQLite | `local` (default) | — |
| MySQL | `mysql` | `[mysql]` |
| PostgreSQL | `pg` | `[pg]` |
| Elasticsearch | `es` | — |

> Local file logging is **always active** regardless of backend choice.

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/ingest` | POST | Ingest single or batch JSON logs |
| `/search` | GET | Query by `trace_id` / `level` / `message_substr` / `limit` |
| `/health` | GET | Health check (auth-free) |
| `/docs` | GET | OpenAPI docs (auth-free) |

## Environment Variables

<details>
<summary><b>Client SDK</b></summary>

| Variable | Default | Description |
|----------|---------|-------------|
| `LOG_CENTER_ENABLE` | `false` | Enable remote log delivery |
| `LOG_CENTER_DELIVERY` | `api` | Delivery mode: `api` / `grpc` / `celery` / comma-combined |
| `LOG_CENTER_URL` | — | HTTP delivery URL (e.g. `http://log-center:9315`) |
| `LOG_CENTER_GRPC_ADDR` | — | gRPC address (e.g. `log-center:9316`) |
| `LOG_CENTER_CELERY_BROKER` | `redis://localhost:6379/0` | Celery broker URL |
| `LOG_CENTER_TIMEOUT` | `2` | Delivery timeout (seconds) |
| `LOG_CENTER_QUEUE` | `1000` | In-memory queue size |
| `LOG_CENTER_BATCH` | `50` | Batch size |
| `LOG_CENTER_TOKEN` | — | Bearer token (required when server auth is on) |
| `LOG_LEVEL` | `INFO` | Log level |
| `LOG_JSON` | `true` | JSON format output |
| `LOG_FILE_PATH` | `logs/{module}.log` | Log file path |
| `LOG_FILE_MAX_MB` | `500` | Max file size (MB) |
| `LOG_FILE_BACKUP` | `3` | Rotation backup count |
| `LOG_FILE_RETENTION_DAYS` | `14` | Retention days |

</details>

<details>
<summary><b>Server</b></summary>

| Variable | Default | Description |
|----------|---------|-------------|
| `LOG_CENTER_PORT` | `9315` | HTTP API port |
| `LOG_CENTER_HOST` | `0.0.0.0` | Bind address |
| `LOG_CENTER_GRPC_PORT` | `9316` | gRPC port |
| `LOG_CENTER_STORE` | `local` | Backend: `local` / `sqlite` / `mysql` / `pg` / `es` |
| `LOG_CENTER_DB_PATH` | `data/log_center/log_center.db` | SQLite database path |
| `LOG_CENTER_AUTH_ENABLED` | `false` | Enable Bearer Token auth |
| `LOG_CENTER_MYSQL_HOST/PORT/USER/PASSWORD/DB` | — | MySQL connection |
| `LOG_CENTER_PG_HOST/PORT/USER/PASSWORD/DB` | — | PostgreSQL connection |
| `LOG_CENTER_ES_ENDPOINT` | — | Elasticsearch endpoint URL |
| `LOG_CENTER_ES_INDEX` | `log-center` | ES index name |
| `LOG_CENTER_CORS_ORIGINS` | `*` | Allowed CORS origins |
| `LOG_CENTER_FORWARD_URLS` | — | Forward target URLs (comma-separated) |
| `LOG_CENTER_AGENT_MODEL` | `gpt-4o` | Agent LLM model name |
| `LOG_CENTER_AGENT_BASE_URL` | — | LLM API base URL |
| `LOG_CENTER_AGENT_API_KEY` | — | LLM API key |
| `LOG_CENTER_AGENT_WORK_MODE` | `auto` | Agent work mode: `auto` / `approval` |
| `LOG_CENTER_AGENT_RECURSION_LIMIT` | `1000` | Max tool-call rounds per turn |

</details>

---

## License

This project is licensed under the **[MIT License](https://opensource.org/licenses/MIT)**.

Copyright (c) IKC Team. You are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, subject to inclusion of the copyright and license notices. The software is provided "as is", without warranty of any kind.
