Loggles

Loggles

Um coletor de logs local-first que transforma seu agente de codificação em um companheiro de runtime.

Em vez de copiar e colar a saída de logs no Claude ou no Cursor, aponte seu aplicativo para o Loggles. Seu agente consulta exatamente o que precisa — filtrado por serviço, nível, ID de rastreamento ou janela de tempo — e recebe dados estruturados sobre os quais pode raciocinar. Sem desperdício de tokens, sem copiar e colar manualmente.

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

Dois casos de uso, mesma configuração:

• Investigando um bug — O Claude lê seu código-fonte, rastreia a falha pelos logs e aponta para a linha. Você descreve o problema; ele faz a investigação.
• Observando o comportamento em runtime — Pergunte "o que meu aplicativo fez quando acessei esse endpoint?" e o Claude acompanha os logs, rastreia a requisição e narra o que aconteceu. Como um depurador ao vivo, sem precisar anexar um.

---

Início rápido

Docker

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

Adicione -e Auth__ApiKey=your-secret-key para habilitar a proteção por chave de API (veja Autenticação).

dotnet run

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

---

Enviando logs para o Loggles

Aponte seu exportador OTLP para 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);

Qualquer outra linguagem / coletor

Defina o endpoint do seu exportador OTLP para http://localhost:5000/v1/logs usando transporte HTTP/protobuf. HTTP/JSON também é suportado com Content-Type: application/json.

---

Conectando seu agente de codificação

Claude Code

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

Se uma chave de API estiver configurada, o Claude Code negocia a autenticação automaticamente via fluxo OAuth PKCE — sem necessidade de configuração manual de token.

Habilidade de depuração

Este repositório inclui uma habilidade do Claude Code (.claude/skills/loggles-debug/) que é ativada automaticamente quando você descreve um bug, pede ao Claude para investigar um erro ou deseja observar o comportamento em runtime do seu aplicativo. Ela coloca o Claude em um de dois modos:

Investigativo (algo está quebrado):

• Lê seu código-fonte primeiro para entender o serviço relevante, mapear sua saída de logs e identificar ramos de erro — depois consulta os logs com esse contexto
• Cruza evidências de logs com o código-fonte para confirmar a causa raiz e apontar para um arquivo e linha específicos
• Aponta instrumentação ausente (correlation_id não propagado, IDs embutidos em strings de mensagem) e explica a correção

Exploratório (observando o comportamento em runtime):

• Começa diretamente pelos logs — sem leitura prévia do código-fonte
• Acompanha streams ao vivo, rastreia requisições por ID e narra o que o serviço está realmente fazendo
• Útil durante desenvolvimento e testes: "o que meu aplicativo fez quando acessei esse endpoint?"

A habilidade é carregada automaticamente quando você abre este projeto no Claude Code. Para usá-la no repositório do seu próprio aplicativo, copie-a:

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

Cursor

Adicione a .cursor/mcp.json na raiz do seu projeto:

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

Se uma chave de API estiver configurada, adicione um cabeçalho Authorization: Bearer <key> na configuração do seu cliente MCP.

---

Ferramentas MCP

Ferramenta	Descrição
search_logs	Pesquisar com filtros: intervalo de tempo, nível, serviço, texto da mensagem, propriedades estruturadas. Suporta paginação.
get_log_by_id	Recuperar um único evento de log por ID
get_services	Listar todos os nomes de fonte/serviço que emitiram logs
get_log_levels	Listar níveis de log distintos presentes
get_properties	Listar chaves de propriedades estruturadas distintas
get_property_values	Listar valores distintos para uma chave de propriedade dentro de uma janela de tempo
get_log_stats	Contagens de logs agrupadas por nível e serviço
get_logs_by_trace_id	Recuperar todos os logs que compartilham um ID de rastreamento/correlação
get_related_logs	Janela de contexto de logs ao redor de um evento específico
get_recent_errors	Últimos N eventos de log de erro/crítico, opcionalmente filtrados por serviço
tail_logs	Últimos N eventos de log mais recentes
get_log_rate	Contagens de logs em intervalos ao longo do tempo — observe volume e ritmo de tráfego
get_message_templates	Listar modelos de mensagem distintos, opcionalmente filtrados por serviço
find_log_patterns	Agrupar mensagens por padrão recorrente
get_error_spikes	Detectar intervalos de tempo onde a contagem de erros excedeu um limite
audit_log_quality	Relatar cobertura de instrumentação: modelos ausentes, mensagens não estruturadas, divididas por serviço
clear_logs	Excluir todos os eventos de log do armazenamento

---

Autenticação

Por padrão, sem chave configurada, todos os endpoints estão abertos — zero atrito para uso em localhost.

Sem autenticação (padrão)

Deixe Auth__ApiKey não definido. Todos os endpoints são publicamente acessíveis. Adequado para localhost.

Chave de API

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

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

Uma vez definida, todos os endpoints de ingestão e consulta exigem:

Authorization: Bearer your-secret-key

Clientes MCP (Claude Code, Cursor, etc.)

Clientes MCP que suportam OAuth (como Claude Code) negociam autenticação automaticamente. Quando uma chave de API está configurada, o Loggles expõe um fluxo local OAuth 2.0 + PKCE (RFC 6749 / RFC 7636) que emite sua chave de API como token de acesso. O cliente lida com esse handshake de forma transparente.

Endpoints de descoberta usados por clientes com suporte a OAuth:

Endpoint	Descrição
GET /.well-known/oauth-authorization-server	Metadados do servidor OAuth (RFC 8414)
GET /.well-known/oauth-protected-resource	Metadados do recurso protegido
POST /oauth/register	Registro dinâmico de clientes (RFC 7591)
GET /oauth/authorize	Endpoint de autorização
POST /oauth/token	Endpoint de token — retorna sua chave de API configurada

O fluxo OAuth pode ser alternado com Mcp__OAuthEnabled (padrão: true). Defina como false para suprimir endpoints de descoberta se seu cliente não suportar OAuth.

---

Configuração

Todas as configurações podem ser substituídas com variáveis de ambiente usando __ como separador (por exemplo, Retention__Hours=24).

Configuração	Padrão	Descrição
Storage__Provider	sqlite	Backend de armazenamento: sqlite ou postgres
Storage__ConnectionString	Data Source=logs.db	String de conexão SQLite, ou string de conexão PostgreSQL ao usar o provedor postgres
Retention__Hours	48	Por quanto tempo manter os logs
Retention__PurgeIntervalMinutes	15	Com que frequência executar a limpeza
Mcp__Enabled	true	Habilitar/desabilitar o endpoint MCP
Mcp__OAuthEnabled	true	Expor endpoints de descoberta e token OAuth para clientes MCP
Auth__ApiKey	(vazio)	Chave de API estática para autenticação Bearer token. Se não definida, a autenticação é desabilitada
SelfDiagnostics__Enabled	true	Enviar os próprios logs do Loggles de volta para ele mesmo via 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

Além do MCP, uma API REST está disponível para scripts ou consultas manuais.

Método	Caminho	Descrição
POST	/v1/logs	Ingerir logs OTLP/HTTP (protobuf ou JSON)
POST	/search	Pesquisar logs com filtros
GET	/logs/{id}	Obter log por ID
GET	/meta/properties	Listar chaves de propriedades distintas
GET	/stats/levels	Contagens de logs por nível

---

Licença

Elastic License 2.0 — gratuito para usar, hospedar e modificar. Você não pode oferecer o Loggles como um serviço hospedado ou gerenciado para terceiros.