ikc-log-center 2.0.6

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]

Install from repository wheel archive (release/)

每个已发布版本都把 wheel/sdist 归档在仓库 release/（见「Release（发布契约）」）， 可直接用归档 wheel 安装，适合固定版本、离线或内网环境：

# 方式一：克隆仓库后本地安装（推荐，最可靠，extras 完整）
git clone git@github.com:shark8848/ikc-log-center.git
cd ikc-log-center
pip install "./release/ikc_log_center-1.4.19-py3-none-any.whl[all]"

# 方式二：GitHub raw 直装（仅当仓库对该网络公开可访问时可用）
pip install "ikc-log-center[all] @ https://raw.githubusercontent.com/shark8848/ikc-log-center/main/release/ikc_log_center-1.4.19-py3-none-any.whl"

# 方式三：tiancloud（GitLab 风格 raw URL，私有仓库需带鉴权）
pip install "ikc-log-center[all] @ https://code.tiancloud.com/sunhy/ikc-log-center/-/raw/main/release/ikc_log_center-1.4.19-py3-none-any.whl"

release/ 目录与发布脚本 scripts/publish-pypi.sh 同步维护：每次发布自动归档并推送所有远程仓库； 具体版本号以 release/README.md 清单为准。raw 直装依赖远程仓库对该网络公开可访问；内网/私有仓库请用方式一。

Docker Deployment (optional bundled HAProxy)

# Standard build & start (host network, external ports stay 9315/9316/9318)
./deploy_scripts/deploy_log_center.sh --start

# Bundle HAProxy reverse proxy into the image and enable it automatically
# (frontend ports remain 9315/9316/9318)
./deploy_scripts/deploy_log_center.sh --haproxy --start

# Manual build
docker build -f docker/Dockerfile -t ikc/log-center:latest .
docker build -f docker/Dockerfile --build-arg INCLUDE_HAPROXY=true -t ikc/log-center:haproxy .

# Direct `docker run` — enable the bundled HAProxy
# (front 9315/9316/9318 → backend 19315/19316/19318, Web UI prefix stripped)
docker run -d --name ikc-log-center \
  --restart unless-stopped \
  --network host \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  -e HA_PROXY_ENABLED=true \
  -e HA_PROXY_WEB_PREFIX=/ikc-log-center \
  ikc/log-center:latest \
  "log-center-mcp --transport http --host 0.0.0.0 --port 19318 & exec log-center-server --port 19315 --ui --agent --grpc"

See docs/deployment.md §8 Docker Deployment for details.

Web UI path prefix: production portals often require the Web UI to be served under a path prefix such as https://xxxxxx:9135/ikc-log-center/. The frontend build is prefix-adaptive by default (relative assets + runtime prefix detection in web/src/basePath.ts), so the same web/dist works for every combination of HAProxy / non-HAProxy × prefixed / non-prefixed — no rebuild is needed. HAProxy strips the prefix before forwarding, or set LOG_CENTER_WEB_PREFIX=/ikc-log-center for the backend to serve it natively. VITE_BASE_PATH is still honored for explicitly baking a prefix (legacy). See docs/deployment.md §8.10 for details.

Troubleshooting (legacy baked-prefix builds only): builds made with VITE_BASE_PATH=/ikc-log-center/ must be reached through a prefix-stripping proxy or a backend that understands the prefix. Hitting the backend directly (uvicorn, no HAProxy, no LOG_CENTER_WEB_PREFIX) at /ikc-log-center only serves index.html — assets/API under the prefix are SPA-fallbacked to index.html (HTTP 200, text/html), which makes the page fail to load. Fixes: set LOG_CENTER_WEB_PREFIX=/ikc-log-center on the backend, put a stripping proxy in front, or rebuild with VITE_BASE_PATH=/ for root-path access.

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, external Elasticsearch log analysis, 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, es, 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), all database write operations (INSERT, UPDATE, DELETE, DDL), and write/delete/reindex on external ES clusters are strictly blocked.

Skills (Skill 管理 + 运行时加载)

Skills are reusable capability packages loaded at runtime from data/skills/ (configurable via LOG_CENTER_AGENT_SKILLS_DIR). Each skill is a directory with a required SKILL.md (YAML frontmatter + Markdown body) and an optional skill.py executor:

data/skills/
└── <skill_name>/
    ├── SKILL.md          # required — YAML frontmatter + instructions
    ├── skill.py          # optional — run(ctx) -> str executor
    └── assets/           # optional static resources

SKILL.md frontmatter:

---
name: daily-log-review
description: 每日日志巡检：统计错误、发现新错误模式、生成报告
version: 1.0.0
enabled: true
when_to_use: 用户要求日志巡检、日报、错误趋势分析时使用
instructions: |
  执行每日日志巡检时，按以下步骤进行：…
tools: [search_logs, get_log_stats, get_trace_chain, save_artifact]
---
# Daily Log Review

Three capability mechanisms:

• A · Prompt injection — instructions + when_to_use are injected into the agent system prompt.
• B · Tool orchestration — declared tools join the skill routing group for dynamic tool routing.
• C · Executor — skill.py's run(ctx) is registered as a langchain tool skill_<name>; ctx receives {"messages": [...]}.

Management API (all runtime, no restart required):

• GET /api/agent/skills — list installed skills with enabled state
• PUT /api/agent/skills/{name} — enable/disable (persisted to data/skills/.state.json, agent rebuilt)
• POST /api/agent/skills — upload <name>.md or <name>.zip (name validated against ^[a-zA-Z0-9_-]+$, zip entries checked for path traversal)
• GET /api/agent/skills/{name}/export — download a skill package as <name>.zip (SKILL.md + skill.py + assets/, excluding __pycache__/*.pyc)
• DELETE /api/agent/skills/{name} — permanently delete a skill (directory + state, tombstoned so default templates don't auto-reseed)

MCP resources log-center://skills and log-center://skills/{name} expose installed skills to external MCP clients. Two example skills (daily-log-review, error-cluster-analysis) are bundled and auto-seeded on first run.

禁用/删除后的对话一致性：禁用（或删除）的技能会从 Agent 的系统提示词、工具注册与路由分类中移除； 历史对话记忆里残留的「技能已安装」等旧事实也会被过滤（匹配技能名与 SKILL.md frontmatter 的 aliases）， 因此对话中不会再出现/生效已禁用的技能。

对话式删除：删除技能必须在对话中由用户明确说出技能名后执行——Agent 通过 delete_skill 工具删除； 若用户未提供技能名，Agent 会先询问，禁止猜测或未经确认删除。

Safety: a skill's skill.py executor runs as arbitrary code on the server — only install skills from trusted sources; a sandboxed executor is planned (see docs/iteration-guidance.md §2).

Release（发布契约）

每次发布走 scripts/publish-pypi.sh，流程固定为：

1. 构建 wheel + sdist（python -m build）；
2. twine 上传 PyPI；
3. 归档：构建产物按版本复制到 release/（如 release/ikc_log_center-1.4.19-py3-none-any.whl）；
4. 推送：git commit 归档并 push 到所有远程仓库（origin / tiancloud 等）。

第 3/4 步是仓库硬契约（AGENTS.md / process.md），默认强制执行；仅在例外场景用 --no-repo-release 豁免并须在 process.md 会话记录写明原因。release/README.md 维护已归档版本清单。

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.

Time Zones

• Log ts values are stored as received; queries, the Web UI, MCP and Agent retrieval display them converted to the server display timezone (LOG_CENTER_TZ_OFFSET, default 8 → UTC+8 / Asia/Shanghai), e.g. 2026-08-30T14:14:13+08:00.
• Convention: naive timestamps without an offset are treated as UTC (typical for SDK clients running in UTC Docker containers) and converted to the display timezone; aware timestamps (Z / ±HH:MM) are converted exactly.
• The SDK (log_center_sdk) emits ts with a timezone offset since v1.4.21 to avoid ambiguity. Date-only or unparseable values pass through unchanged.

API Endpoints

Environment Variables

Security

Security Advisory — SPA Fallback Arbitrary File Disclosure (2026-08-10)

Affected: all versions ≤ 1.4.9 with the Web UI enabled Fixed in: v1.4.10

A crafted URL with a leading slash (e.g. GET //etc/passwd) could reach the SPA fallback route with an absolute path, causing the server to serve arbitrary files from the host (e.g. /etc/passwd, /etc/shadow, application source code).

Please upgrade immediately:

# pip deployments — upgrade to the patched version
pip install --upgrade "ikc-log-center[all]==1.4.10"

# Docker deployments — rebuild & restart from the repo root
./deploy_scripts/deploy_log_center.sh --start

Full report: docs/security/SPA-fallback-path-injection-fix-report.md (root cause, PoC, verification matrix, and upgrade guide).

To report a security issue, please open a GitHub issue with the security label or contact the maintainers directly.

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.