Logcenter Agent + Skills Toolkit

This repo provides a small, offline generator that turns a service context into:

- KQL query templates for Kibana Discover/Lens
- Alert policy templates for error rate, burst, latency, and signatures
- A consistent JSON output contract for downstream automation

It does not call Elasticsearch or Kibana APIs. It only generates queries and
templates you can paste into Kibana or wire into your own automation.

Quick start

``bash
python3 logcenter_agent.py \
--service wms-bam \
--index b7cb5f9d-c4df-436a-8de0-f5f84eda2370 \
--from now-15m \
--to now \
--field-mode structured \
--pretty
`

For message JSON fallback:

`bash
python3 logcenter_agent.py \
--service wms-bam \
--field-mode message_json \
--pretty
`

If your message includes a text prefix plus a JSON array (e.g. access logs),
use the IngestPipelineGrokJsonArray template from the output to extract the
JSON block before decoding. The generator also matches common keys like
status, durationMs, route, url, ip, traceId, and requestId for KQL
fallbacks. Use the MessageJsonCompleteOnly query to filter only completion
lines when both Start/Complete messages exist.

Input format

You can provide a JSON context file via --input. Example (also in
examples/input.json):

`json
{
"env": "prod",
"index": "item-platform_gateway_logs",
"serviceQuery": "wms-bam",
"timeRange": { "from": "now-15m", "to": "now" },
"filters": [
{ "field": "log.level", "op": "in", "value": ["INFO", "WARN", "ERROR"] }
],
"fieldMap": {
"service": "service.name",
"status": "responseStatusCode",
"duration": "duration",
"path": "requestPath",
"trace_id": "traceId"
},
"fieldMode": "structured"
}
`

Notes:

- fieldMode can be structured or message_json.
- Use --service-query if you already have a raw KQL expression.
- Use --field-map to override field mappings.

Outputs

The generator prints a JSON blob with:

- queries: KQL snippets for total, error, latency, topN, signatures
- alerts: alert policy templates (copy into Kibana Alerting)
- skills: per-skill outputs for debugging and extensions

Templates:

- templates/notification.md: alert message layout
- templates/report.md: post-incident report layout

MCP (Node)

This repo includes a Node-based MCP server that exposes one tool:
generate plus a live analysis tool analyze. The MCP
server shells out to logcenter_agent.py for generation, and queries Kibana
for analysis, so Python 3 is required on the host.

Install dependencies (for local dev):

`bash
npm install
`

Run the MCP server (stdio):

`bash
npm run mcp
`

Required env vars for live analysis:

- LOGCENTER_URL (default: https://logcenter.item.com)
- LOGCENTER_USERNAME
- LOGCENTER_PASSWORD
- LOGCENTER_DATA_VIEW (optional default data view name/id)

Node 18+ is required.

Run via npx (recommended for models/tools, from outside this repo):

`bash
npx -y logcenter-mcp
`

If you're running inside this repo, use:

`bash
npm run mcp
`

Example generate input:

`json
{
"service": "wms-bam",
"fieldMode": "message_json",
"index": "prod-item-wms-bam"
}
`

Example analyze input:

`json
{
"question": "最近2小时接口延迟情况？",
"dataView": "prod-item-wms-bam",
"topN": 5
}
`

If results are empty, the response will include time_bounds and the server
will automatically retry using a window ending at the latest timestamp. The
effective range is shown in effective_time_range. When access fields are not
detected, the server falls back to app-log mode and returns analysis_mode:
"app" with top_error_loggers and top_error_signatures. Natural language
questions should be mapped by the model into timeRange and accessOnly
arguments; the server does not parse questions directly.

Prompt: analyze_tool_guide

The MCP server provides a prompt that helps models map a natural-language
question into structured analyze arguments.

Example MCP config snippet:

`json
{
"mcpServers": {
"logcenter": {
"command": "npx",
"args": ["-y", "logcenter-mcp"],
"env": {
"LOGCENTER_URL": "https://logcenter.item.com",
"LOGCENTER_USERNAME": "your-username",
"LOGCENTER_PASSWORD": "your-password",
"LOGCENTER_DATA_VIEW": "prod-item-wms-bam"
}
}
}
}
`

See mcp/mcp.config.example.json for a ready-to-copy config file.

Publish to npm

`bash
npm login
npm publish --access public
``