Loggles
Debugging your software logs with Code Asisstants made easier!
Documentation
Loggles
A local-first log sink that turns your coding agent into a runtime companion.
Instead of copy-pasting log output into Claude or Cursor, point your app at Loggles. Your agent
queries exactly what it needs — filtered by service, level, trace ID, or time window — and gets
back structured data it can reason over. No token waste, no manual copy-paste.
Your App ──OTLP──▶ Loggles ──MCP──▶ Claude Code / CursorTwo use cases, same setup:
- Investigating a bug — Claude reads your source, traces the failure through logs, and points
to the line. You describe the problem; it does the digging.
- Watching runtime behaviour — Ask "what did my app do when I hit that endpoint?" and Claude
tails the logs, traces the request, and narrates what happened. Like a live debugger, without
attaching one.
Quick start
Docker
docker run -d \
-p 5000:5000 \
-v loggles-data:/data \
ghcr.io/bytesquashcom/loggles:latestAdd `-e Auth__ApiKey=your-secret-key` to enable API key protection (see Authentication).
dotnet run
git clone https://github.com/bytesquashcom/Loggles.git
cd Loggles/src/Loggles.Api
dotnet run
# Listening on http://localhost:5000Sending logs to Loggles
Point your OTLP exporter at `http://localhost:5000/v1/logs` using HTTP/protobuf.
.NET
// dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
builder.Services.AddOpenTelemetry()
.WithLogging(logging =>
{
logging.AddOtlpExporter(otlp =>
{
otlp.Endpoint = new Uri("http://localhost:5000/v1/logs");
otlp.Protocol = OtlpExportProtocol.HttpProtobuf;
});
});Node.js
npm install @opentelemetry/sdk-node @opentelemetry/exporter-logs-otlp-http @opentelemetry/sdk-logsconst { LoggerProvider, SimpleLogRecordProcessor } = require('@opentelemetry/sdk-logs');
const { OTLPLogExporter } = require('@opentelemetry/exporter-logs-otlp-http');
const provider = new LoggerProvider();
provider.addLogRecordProcessor(
new SimpleLogRecordProcessor(
new OTLPLogExporter({ url: 'http://localhost:5000/v1/logs' })
)
);
provider.register();Python
pip install opentelemetry-exporter-otlp-proto-http opentelemetry-sdkfrom opentelemetry import _logs
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
provider = LoggerProvider()
provider.add_log_record_processor(
BatchLogRecordProcessor(OTLPLogExporter(endpoint="http://localhost:5000/v1/logs"))
)
_logs.set_logger_provider(provider)Go
go get go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttpexporter, _ := otlploghttp.New(context.Background(),
otlploghttp.WithEndpointURL("http://localhost:5000/v1/logs"),
otlploghttp.WithInsecure(),
)
provider := log.NewLoggerProvider(
log.WithProcessor(log.NewBatchProcessor(exporter)),
)
global.SetLoggerProvider(provider)Java
io.opentelemetry
opentelemetry-exporter-otlpOtlpHttpLogRecordExporter exporter = OtlpHttpLogRecordExporter.builder()
.setEndpoint("http://localhost:5000/v1/logs")
.build();
SdkLoggerProvider provider = SdkLoggerProvider.builder()
.addLogRecordProcessor(BatchLogRecordProcessor.builder(exporter).build())
.build();
OpenTelemetrySdk.builder().setLoggerProvider(provider).buildAndRegisterGlobal();Ruby
gem install opentelemetry-exporter-otlp opentelemetry-sdkrequire 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
OpenTelemetry::SDK.configure do |c|
c.add_span_processor(
OpenTelemetry::SDK::Logs::Export::BatchLogRecordProcessor.new(
OpenTelemetry::Exporter::OTLP::LogsExporter.new(
endpoint: 'http://localhost:5000/v1/logs'
)
)
)
endPHP
composer require open-telemetry/exporter-otlp open-telemetry/sdk$exporter = (new \OpenTelemetry\Contrib\Otlp\LogsExporter(
\OpenTelemetry\Contrib\Otlp\OtlpUtil::createTransport('http://localhost:5000/v1/logs')
));
$provider = new \OpenTelemetry\SDK\Logs\LoggerProvider(
new \OpenTelemetry\SDK\Logs\Processor\BatchLogRecordProcessor($exporter)
);
\OpenTelemetry\API\Logs\NoopLogger::setLoggerProvider($provider);Any other language / collector
Set your OTLP exporter endpoint to `http://localhost:5000/v1/logs` using HTTP/protobuf transport.
HTTP/JSON is also supported with `Content-Type: application/json`.
Connecting your coding agent
Claude Code
claude mcp add loggles --transport http http://localhost:5000/mcpIf an API key is configured, Claude Code negotiates authentication automatically via the OAuth
PKCE flow — no manual token setup required.
Debug skill
This repository ships a Claude Code skill (`.claude/skills/loggles-debug/`) that activates
automatically when you describe a bug, ask Claude to investigate an error, or want to observe
your app's runtime behaviour. It puts Claude in one of two modes:
Investigative (something is broken):
- Reads your source code first to understand the relevant service, map its log output, and
identify error branches — then queries logs with that context
- Cross-references log evidence against source to confirm a root cause and point to a specific
file and line
- Calls out missing instrumentation (`correlation_id` not propagated, IDs embedded in message
strings) and explains the fix
Exploratory (observing runtime behaviour):
- Starts from the logs directly — no upfront source reading
- Tails live streams, traces requests by ID, and narrates what the service is actually doing
- Useful during development and testing: "what did my app do when I hit that endpoint?"
The skill is loaded automatically when you open this project in Claude Code. To use it in
your own application's repository, copy it:
mkdir -p /your-project/.claude/skills
cp -r /path/to/loggles/.claude/skills/loggles-debug /your-project/.claude/skills/Cursor
Add to `.cursor/mcp.json` in your project root:
{
"mcpServers": {
"loggles": {
"url": "http://localhost:5000/mcp"
}
}
}If an API key is configured, add an `Authorization: Bearer ` header in your MCP client
configuration.
MCP tools
| Tool | Description |
|---|---|
| `search_logs` | Search with filters: time range, level, service, message text, structured properties. Supports pagination. |
| `get_log_by_id` | Retrieve a single log event by ID |
| `get_services` | List all source/service names that have emitted logs |
| `get_log_levels` | List distinct log levels present |
| `get_properties` | List distinct structured property keys |
| `get_property_values` | List distinct values for a property key within a time window |
| `get_log_stats` | Log counts grouped by level and service |
| `get_logs_by_trace_id` | Retrieve all logs sharing a trace/correlation ID |
| `get_related_logs` | Context window of logs around a specific event |
| `get_recent_errors` | Last N error/critical log events, optionally filtered by service |
| `tail_logs` | Most recent N log events |
| `get_log_rate` | Bucketed log counts over time — observe traffic volume and rhythm |
| `get_message_templates` | List distinct message templates, optionally filtered by service |
| `find_log_patterns` | Cluster messages by recurring pattern |
| `get_error_spikes` | Detect time buckets where error count exceeded a threshold |
| `audit_log_quality` | Report instrumentation coverage: missing templates, unstructured messages, broken down by service |
| `clear_logs` | Delete all log events from the store |
Authentication
By default, with no key configured, all endpoints are open — zero friction for localhost use.
No authentication (default)
Leave `Auth__ApiKey` unset. All endpoints are publicly accessible. Suitable for localhost.
API key
# Docker
docker run ... -e Auth__ApiKey=your-secret-key ...
# dotnet run
export Auth__ApiKey=your-secret-key
dotnet runOnce set, all ingest and query endpoints require:
Authorization: Bearer your-secret-keyMCP clients (Claude Code, Cursor, etc.)
MCP clients that support OAuth (such as Claude Code) negotiate authentication automatically.
When an API key is configured, Loggles exposes a local OAuth 2.0 + PKCE flow (RFC 6749 /
RFC 7636) that issues your API key as the access token. The client handles this handshake
transparently.
Discovery endpoints used by OAuth-aware clients:
| Endpoint | Description |
|---|---|
| `GET /.well-known/oauth-authorization-server` | OAuth server metadata (RFC 8414) |
| `GET /.well-known/oauth-protected-resource` | Protected resource metadata |
| `POST /oauth/register` | Dynamic client registration (RFC 7591) |
| `GET /oauth/authorize` | Authorization endpoint |
| `POST /oauth/token` | Token endpoint — returns your configured API key |
The OAuth flow can be toggled with `Mcp__OAuthEnabled` (default: `true`). Set to `false` to
suppress discovery endpoints if your client does not support OAuth.
Configuration
All settings can be overridden with environment variables using `__` as separator
(e.g. `Retention__Hours=24`).
| Setting | Default | Description |
|---|---|---|
| `Storage__Provider` | `sqlite` | Storage backend: `sqlite` or `postgres` |
| `Storage__ConnectionString` | `Data Source=logs.db` | SQLite connection string, or PostgreSQL connection string when using `postgres` provider |
| `Retention__Hours` | `48` | How long to keep logs |
| `Retention__PurgeIntervalMinutes` | `15` | How often to run cleanup |
| `Mcp__Enabled` | `true` | Enable/disable the MCP endpoint |
| `Mcp__OAuthEnabled` | `true` | Expose OAuth discovery and token endpoints for MCP clients |
| `Auth__ApiKey` | _(empty)_ | Static API key for Bearer token auth. If unset, auth is disabled |
| `SelfDiagnostics__Enabled` | `true` | Send Loggles' own logs back to itself via OTLP |
| `SelfDiagnostics__OtlpEndpoint` | `http://localhost:5000` | OTLP endpoint for self-diagnostics |
PostgreSQL
docker run -d \
-p 5000:5000 \
-e Storage__Provider=postgres \
-e Storage__ConnectionString="Host=your-host;Database=loggles;Username=loggles;Password=secret" \
ghcr.io/bytesquashcom/loggles:latestREST API
Beyond MCP, a REST API is available for scripting or manual queries.
| Method | Path | Description |
|---|---|---|
| `POST` | `/v1/logs` | Ingest OTLP/HTTP logs (protobuf or JSON) |
| `POST` | `/search` | Search logs with filters |
| `GET` | `/logs/{id}` | Get log by ID |
| `GET` | `/meta/properties` | List distinct property keys |
| `GET` | `/stats/levels` | Log counts by level |
License
Elastic License 2.0 — free to use, self-host, and modify. You may not offer Loggles as a hosted or managed service to third parties.
Frequently asked questions
What is Loggles?
Loggles is Debugging your software logs with Code Asisstants made easier!
How do I install Loggles?
Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.
Is Loggles open source?
Yes — it is hosted on GitHub at https://github.com/bytesquashcom/Loggles and has 9 stars.
Related MCP tools
Unity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.
AI Skills, MCP Tools, and CLI for Unity Engine. Full AI develop and test loop. Use cli for quick setup. Efficient token usage, advanced tools. Any C# method may be turned into a tool by a single line. Works with Claude Code, Gemini, Copilot, Cursor and any other absolutely for free.
Catalog of official Microsoft MCP (Model Context Protocol) server implementations for AI-powered data access and tool integration
An MCP server that allows MCP clients like Claude Desktop or Cursor to perform actions in the Unity Editor C#-based implementation.
The official C# SDK for Model Context Protocol servers and clients. Maintained in collaboration with Microsoft. Trusted by 3500+ developers.
Model Context Protocol (MCP) plugin to connect with Unity Editor — designed for OpenAI, Gemini, Claude, Deepseek and Grok interoperability
Run your own MCP server? See who uses it and what to fix.
Measure it with TrackMCP