ikc-log-center 1.4.4

Lightweight SDK + Server for log_center — decorator-based instrumentation with HTTP/gRPC/Celery delivery, multi-backend storage, and search UI.

Lightweight SDK + Centralized Log Service + AI Agent
Auto-capture · Multi-transport · Multi-backend · MCP for AI · Built-in Agent

English | 中文 | 日本語 | Français | Deutsch | Español

---

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              AI Agent             MCP Server
           (React SPA)          (LangGraph)        (stdio / SSE)
                 │                     │                     │
           Token Auth            Work Modes         External AI Tools
                         auto / plan / approval     Claude Code · Codex
                                                   Cursor · Windsurf
                                       │
                              ┌────────┴────────┐
                              │                 │
                         Git Repos        Business DBs
                        (read-only)      MySQL · PG · Oracle

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 — compatible with Claude Code, Codex, Cursor, Windsurf & more
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

# 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

# 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

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:

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

3. Framework Integrations

FastAPI:

from log_center_sdk.integrations.fastapi import TraceMiddleware
app.add_middleware(TraceMiddleware)

Flask:

from log_center_sdk.integrations.flask import init_trace_hooks
init_trace_hooks(app)

Celery Workers:

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. Works with the built-in AI Agent and any external MCP-compatible tool:

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

External Tool Integration

Connect your favorite AI dev tools to Log Center via MCP:

Claude Code / Codex CLI (~/.claude/mcp.json or mcp_servers.json):

{
  "mcpServers": {
    "log-center": {
      "command": "log-center-mcp",
      "env": {
        "LOG_CENTER_URL": "http://localhost:9315",
        "LOG_CENTER_TOKEN": "sk-lc-xxxxx"
      }
    }
  }
}

Cursor / Windsurf (Settings → MCP Servers):

{
  "log-center": {
    "command": "log-center-mcp",
    "env": {
      "LOG_CENTER_URL": "http://localhost:9315"
    }
  }
}

Once connected, you can ask your AI assistant:

• "Search for ERROR logs in the last hour"
• "Find all logs for trace_id abc-123"
• "Show slow calls (>500ms) from module payment"

AI Agent

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

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

Capabilities

Capability	Description
Log analysis	Search and analyze logs via MCP tools (search, stats, trace chain, levels)
Git repos	Clone & read repositories (read-only, write ops blocked)
Database queries	MySQL / PostgreSQL / Oracle — forced read-only
Artifacts	Generate downloadable files (reports, analysis, code, etc.)
Work modes	auto (tools run automatically), plan (generate plan then execute), approval (human-in-the-loop)
Memory	Conversation memory with auto-extraction of key facts
Session history	Persistent per-thread conversation history with resume support
Context compression	window / token_limit / summarize strategies to manage long conversations
Sub-agent delegation	Spawn parallel sub-agents for complex multi-node tasks (e.g., analyze each node independently)
Dynamic tool routing	Classify user intent per turn and inject only relevant tools (reduces ~45% token cost)
Multi-language UI	Full Chinese / English internationalization for the Agent chat interface

Sub-Agent Delegation

When enabled, the main agent gains a task tool to spawn ephemeral sub-agents:

User: "Analyze errors on each node separately"
  Main Agent → get_services() → [nodeA, nodeB, nodeC]
  Main Agent → task("Analyze nodeA", type="log-analyst")  ─┐
             → task("Analyze nodeB", type="log-analyst")  ─┼─ parallel
             → task("Analyze nodeC", type="log-analyst")  ─┘
  Main Agent ← collect results → generate summary report

Built-in sub-agent types:

• log-analyst — specialized in per-node/per-service log & trace analysis
• report-writer — generates structured analysis reports and saves artifacts
• general-purpose — inherits all tools for any complex multi-step task

Dynamic Tool Routing

When enabled, each user message is classified by a lightweight LLM call into tool groups (log, git, repo, db, artifact), and only the matching subset is injected — reducing per-turn token cost by ~45% without losing capability.

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.

# 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:

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

Client SDK

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

Server

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 / plan / approval
LOG_CENTER_AGENT_RECURSION_LIMIT	1000	Max tool-call rounds per turn
LOG_CENTER_AGENT_TOOL_ROUTING	false	Enable dynamic tool routing (intent-based subset injection)
LOG_CENTER_AGENT_SUBAGENT	false	Enable sub-agent delegation (parallel task execution)
LOG_CENTER_AGENT_CONTEXT_STRATEGY	window	Context compression: none / window / token_limit / summarize
LOG_CENTER_AGENT_CONTEXT_MAX_MESSAGES	50	Max messages to keep (window strategy)
LOG_CENTER_AGENT_CONTEXT_MAX_TOKENS	60000	Max tokens in context (token_limit strategy)

---

License

This project is licensed under the MIT License.

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.