ikc-log-center 1.0.1

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
Auto-capture · Multi-transport · Multi-backend · MCP for AI

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, and Bearer Token authentication.

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
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[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 for AI agents:

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

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)

---

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.