Loggles

Loggles

Un sumidero de registros local-first que convierte tu agente de codificación en un compañero de ejecución.

En lugar de copiar y pegar la salida de registros en Claude o Cursor, apunta tu aplicación a Loggles. Tu agente consulta exactamente lo que necesita — filtrado por servicio, nivel, ID de traza o ventana de tiempo — y recibe datos estructurados sobre los que puede razonar. Sin desperdicio de tokens, sin copiar y pegar manual.

Your App  ──OTLP──▶  Loggles  ──MCP──▶  Claude Code / Cursor

Dos casos de uso, misma configuración:

• Investigando un error — Claude lee tu código fuente, rastrea el fallo a través de los registros y señala la línea. Tú describes el problema; él hace la investigación.
• Observando el comportamiento en ejecución — Pregunta "¿qué hizo mi aplicación cuando golpeé ese endpoint?" y Claude sigue los registros, rastrea la solicitud y narra lo que sucedió. Como un depurador en vivo, sin adjuntar uno.

---

Inicio rápido

Docker

docker run -d \
  -p 5000:5000 \
  -v loggles-data:/data \
  ghcr.io/bytesquashcom/loggles:latest

Agrega -e Auth__ApiKey=your-secret-key para habilitar la protección con clave de API (ver Autenticación).

dotnet run

git clone https://github.com/bytesquashcom/Loggles.git
cd Loggles/src/Loggles.Api
dotnet run
# Listening on http://localhost:5000

---

Enviando registros a Loggles

Apunta tu exportador OTLP a http://localhost:5000/v1/logs usando 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-logs

const { 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-sdk

from 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/otlploghttp

exporter, _ := 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

<!-- pom.xml -->
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

OtlpHttpLogRecordExporter 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-sdk

require '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'
      )
    )
  )
end

PHP

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);

Cualquier otro lenguaje / colector

Configura el endpoint de tu exportador OTLP a http://localhost:5000/v1/logs usando transporte HTTP/protobuf. HTTP/JSON también es compatible con Content-Type: application/json.

---

Conectando tu agente de codificación

Claude Code

claude mcp add loggles --transport http http://localhost:5000/mcp

Si una clave de API está configurada, Claude Code negocia la autenticación automáticamente mediante el flujo OAuth PKCE — sin necesidad de configuración manual de tokens.

Habilidad de depuración

Este repositorio incluye una habilidad de Claude Code (.claude/skills/loggles-debug/) que se activa automáticamente cuando describes un error, pides a Claude que investigue un fallo o quieres observar el comportamiento en ejecución de tu aplicación. Coloca a Claude en uno de dos modos:

Investigativo (algo está roto):

• Lee primero tu código fuente para entender el servicio relevante, mapear su salida de registros e identificar ramas de error — luego consulta los registros con ese contexto
• Contrasta la evidencia de los registros con el código fuente para confirmar una causa raíz y señalar un archivo y línea específicos
• Señala la instrumentación faltante (correlation_id no propagado, IDs incrustados en cadenas de mensajes) y explica la solución

Exploratorio (observando el comportamiento en ejecución):

• Comienza directamente desde los registros — sin lectura previa del código fuente
• Sigue flujos en vivo, rastrea solicitudes por ID y narra lo que el servicio está haciendo realmente
• Útil durante el desarrollo y las pruebas: "¿qué hizo mi aplicación cuando golpeé ese endpoint?"

La habilidad se carga automáticamente cuando abres este proyecto en Claude Code. Para usarla en el repositorio de tu propia aplicación, cópiala:

mkdir -p /your-project/.claude/skills
cp -r /path/to/loggles/.claude/skills/loggles-debug /your-project/.claude/skills/

Cursor

Agrega a .cursor/mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "loggles": {
      "url": "http://localhost:5000/mcp"
    }
  }
}

Si una clave de API está configurada, agrega un encabezado Authorization: Bearer <key> en la configuración de tu cliente MCP.

---

Herramientas MCP

Herramienta	Descripción
search_logs	Buscar con filtros: rango de tiempo, nivel, servicio, texto del mensaje, propiedades estructuradas. Soporta paginación.
get_log_by_id	Recuperar un único evento de registro por ID
get_services	Listar todos los nombres de fuente/servicio que han emitido registros
get_log_levels	Listar los niveles de registro distintos presentes
get_properties	Listar las claves de propiedades estructuradas distintas
get_property_values	Listar valores distintos para una clave de propiedad dentro de una ventana de tiempo
get_log_stats	Conteos de registros agrupados por nivel y servicio
get_logs_by_trace_id	Recuperar todos los registros que comparten un ID de traza/correlación
get_related_logs	Ventana de contexto de registros alrededor de un evento específico
get_recent_errors	Últimos N eventos de registro de error/crítico, opcionalmente filtrados por servicio
tail_logs	Los N eventos de registro más recientes
get_log_rate	Conteos de registros agrupados en intervalos a lo largo del tiempo — observa el volumen y ritmo del tráfico
get_message_templates	Listar plantillas de mensajes distintas, opcionalmente filtradas por servicio
find_log_patterns	Agrupar mensajes por patrón recurrente
get_error_spikes	Detectar intervalos de tiempo donde el conteo de errores superó un umbral
audit_log_quality	Informar cobertura de instrumentación: plantillas faltantes, mensajes no estructurados, desglosados por servicio
clear_logs	Eliminar todos los eventos de registro del almacén

---

Autenticación

Por defecto, sin clave configurada, todos los endpoints están abiertos — cero fricción para uso en localhost.

Sin autenticación (predeterminado)

Deja Auth__ApiKey sin configurar. Todos los endpoints son accesibles públicamente. Adecuado para localhost.

Clave de API

# Docker
docker run ... -e Auth__ApiKey=your-secret-key ...

# dotnet run
export Auth__ApiKey=your-secret-key
dotnet run

Una vez configurada, todos los endpoints de ingesta y consulta requieren:

Authorization: Bearer your-secret-key

Clientes MCP (Claude Code, Cursor, etc.)

Los clientes MCP que soportan OAuth (como Claude Code) negocian la autenticación automáticamente. Cuando una clave de API está configurada, Loggles expone un flujo local OAuth 2.0 + PKCE (RFC 6749 / RFC 7636) que emite tu clave de API como token de acceso. El cliente maneja este intercambio de forma transparente.

Endpoints de descubrimiento utilizados por clientes compatibles con OAuth:

Endpoint	Descripción
GET /.well-known/oauth-authorization-server	Metadatos del servidor OAuth (RFC 8414)
GET /.well-known/oauth-protected-resource	Metadatos del recurso protegido
POST /oauth/register	Registro dinámico de clientes (RFC 7591)
GET /oauth/authorize	Endpoint de autorización
POST /oauth/token	Endpoint de token — devuelve tu clave de API configurada

El flujo OAuth se puede alternar con Mcp__OAuthEnabled (predeterminado: true). Configúralo a false para suprimir los endpoints de descubrimiento si tu cliente no soporta OAuth.

---

Configuración

Todos los ajustes se pueden sobrescribir con variables de entorno usando __ como separador (por ejemplo, Retention__Hours=24).

Ajuste	Predeterminado	Descripción
Storage__Provider	sqlite	Backend de almacenamiento: sqlite o postgres
Storage__ConnectionString	Data Source=logs.db	Cadena de conexión SQLite, o cadena de conexión PostgreSQL cuando se usa el proveedor postgres
Retention__Hours	48	Cuánto tiempo conservar los registros
Retention__PurgeIntervalMinutes	15	Con qué frecuencia ejecutar la limpieza
Mcp__Enabled	true	Habilitar/deshabilitar el endpoint MCP
Mcp__OAuthEnabled	true	Exponer los endpoints de descubrimiento y token OAuth para clientes MCP
Auth__ApiKey	(vacío)	Clave de API estática para autenticación Bearer. Si no está configurada, la autenticación está deshabilitada
SelfDiagnostics__Enabled	true	Enviar los propios registros de Loggles de vuelta a sí mismo vía OTLP
SelfDiagnostics__OtlpEndpoint	http://localhost:5000	Endpoint OTLP para autodiagnóstico

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:latest

---

API REST

Más allá de MCP, una API REST está disponible para scripting o consultas manuales.

Método	Ruta	Descripción
POST	/v1/logs	Ingerir registros OTLP/HTTP (protobuf o JSON)
POST	/search	Buscar registros con filtros
GET	/logs/{id}	Obtener registro por ID
GET	/meta/properties	Listar claves de propiedades distintas
GET	/stats/levels	Conteos de registros por nivel

---

Licencia

Elastic License 2.0 — libre de usar, autoalojar y modificar. No puedes ofrecer Loggles como un servicio alojado o gestionado a terceros.