ikc-log-center 1.4.8

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

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

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

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

Docker Sandbox

When enabled, Agent file operations and command execution run inside isolated Docker containers:

# Local testing (host machine)
LOG_CENTER_AGENT_SANDBOX_ENABLED=true log-center-server --port 9315 --agent

# Docker deployment (DooD mode)
./deploy_scripts/deploy_log_center.sh --start --sandbox

Sandbox security features: --network=none (no network), --memory limits, --rm (auto-cleanup), /tmp tmpfs.

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

Local file logging is always active regardless of backend choice.

API Endpoints

Environment Variables

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.