Documentation

Getting Started with LogPilot

LogPilot is an AI-powered platform that transforms how you debug and monitor distributed systems. Instead of writing complex queries, you ask questions in plain English. Instead of manually tracing errors, LogPilot automatically identifies root causes and suggests fixes.

Prerequisites

Node.js 18+ or Python 3.9+. A running application or log files to analyze. An OpenAI API key (for the CLI tool's AI features).

1 Installation

Install the LogPilot CLI globally using npm or pip:

npm (recommended)

$ npm install -g @logpilot/cli

pip

$ pip install logpilot

Docker

$ docker pull logpilot/agent:latest

2 Quick Start

Initialize LogPilot in your project and authenticate:

                Terminal
              
# Initialize LogPilot in your project
$ logpilot init
✓ Created .logpilot/config.yaml
✓ Detected Kubernetes cluster: prod-us-east-1
 
# Set your API key
$ logpilot auth --key sk-your-api-key
✓ Authenticated as user@example.com
 
# Start monitoring (streams logs in real-time)
$ logpilot monitor --cluster production
▶ Connected to 12 pods across 6 services
▶ AI agent active — monitoring for anomalies...

Or analyze a local log file:

                Analyze a log file
              
$ logpilot analyze ./app.log
 
Parsing 247,832 log entries...
Generating embeddings...
Running pattern analysis...
 
✓ Analysis complete
  Found 12 unique patterns, 3 anomalies
  Top issue: Memory leak in TxnCache (47 occurrences)
  Run `logpilot report` to view full report

3 Configuration

LogPilot uses a YAML configuration file. Here's the default .logpilot/config.yaml:

                .logpilot/config.yaml
              
version: "1.0"
 
sources:
  - type: kubernetes
    cluster: prod-us-east-1
    namespaces: [default, payments, auth]
 
ai:
  provider: openai
  model: gpt-4o
  auto_remediate: false  # set to true for auto-fix
 
storage:
  backend: cloud  # or "local" for CLI-only mode
  retention: 30d
 
alerts:
  slack: https://hooks.slack.com/...
  pagerduty: your-integration-key

Semantic Search

LogPilot's semantic search lets you query logs using natural language. Under the hood, it converts your query into vector embeddings and performs similarity search across your log data, combined with structured SQL queries for time ranges and filters.

Examples
$ logpilot search "all payment timeouts after 3pm yesterday"
$ logpilot search "auth failures from IP range 10.0.x.x"
$ logpilot search "which service had the most errors this week?"
$ logpilot search "show me logs similar to this OOM crash"

Root Cause Analysis

When LogPilot detects an anomaly, it can perform automatic root cause analysis by tracing the failure path across services. You can also trigger RCA manually:

Terminal
$ logpilot rca --trace-id abc123def456
 
Analyzing trace abc123def456...
├─ api-gateway (2ms) ✓
├─ order-svc (15ms) ✓
├─ payment-svc (timeout) ✗
│  └─ stripe-api (DNS failure) ✗
 
Root Cause: DNS configuration change in v2.4.0
Suggested fix: Revert resolv.conf or add fallback resolver

Pattern Discovery

The pattern engine clusters similar log events and ranks them by novelty. Known patterns are suppressed, while new or escalating patterns are surfaced as alerts.

Terminal
$ logpilot patterns --last 24h
 
  PATTERN                          COUNT      STATUS
  Connection Timeout (known)       1,247,839  suppressed
  Health check passed (known)        892,104  suppressed
  GC pause > 200ms (new)                 47  ⚠ alert
  Cert expiry 48h (new, critical)          3  🔴 critical

Auto-Remediation

Enable auto-remediation to let LogPilot fix common issues automatically. When auto_remediate: true, the agent can restart pods, scale deployments, and create GitHub PRs.

Safety First

Auto-remediation only executes pre-approved actions. All changes are logged and can be rolled back. For destructive operations, LogPilot always asks for confirmation via Slack or CLI.

API Reference

The LogPilot REST API allows you to programmatically ingest logs, run queries, and manage your configuration.

GET /api/v1/search Semantic log search

POST /api/v1/ingest Ingest log events

POST /api/v1/rca Trigger root cause analysis

GET /api/v1/patterns List discovered patterns

GET /api/v1/health Service health metrics

CLI Commands

logpilot init

Initialize LogPilot in the current directory, creating a config file.

logpilot auth --key <api-key>

Authenticate with your LogPilot API key.

logpilot monitor [--cluster <name>]

Start real-time log monitoring with AI anomaly detection.

logpilot analyze <file>

Analyze a local log file for patterns and anomalies.

logpilot search "<query>"

Search logs using natural language.

logpilot rca --trace-id <id>

Run root cause analysis for a specific trace.

logpilot patterns [--last <duration>]

List discovered log patterns within a time range.

logpilot report

Generate and display the latest analysis report.

SDK & Libraries

Use our SDKs to integrate LogPilot directly into your application for structured log ingestion:

Node.js / TypeScript

import { LogPilot } from '@logpilot/sdk'
 
const pilot = new LogPilot({
  apiKey: 'sk-...'
})
 
pilot.log('Payment processed', {
  level: 'info',
  service: 'payment-svc'
})

Python

from logpilot import LogPilot
 
pilot = LogPilot(
  api_key="sk-..."
)
 
pilot.log(
  "Payment processed",
  level="info",
  service="payment-svc"
)