---
type: Entity
layer: wiki
tags: [stack, dashdescomplicar, backend, observabilidade, sessoes, sqlite, systemd]
title: "Observabilidade-Sessions"
---

# Observabilidade-Sessions

Sistema de observabilidade de sessões Claude Code (Espelho). Indexa, armazena e expõe dados de sessões de múltiplos motores IA (Claude Code, Hermes, OpenCode) via SQLite local.

## Responsabilidades

- **Indexação**: Watcher incremental de ficheiros JSONL (Claude Code) + import de BD (Hermes SQLite, OpenCode SQLite)
- **Armazenamento**: SQLite local (`~/.claude-work/sessions.db`) com schema optimizado
- **Worklog Import**: Import de worklogs Desk CRM (discussions #31/#32/#33)
- **Pattern Detection**: Detecção semanal de padrões de uso (tools, skills, erros)
- **API**: Rota `/api/sessions` (lista + detalhe com eventos)
- **Sincronização**: Volume bind EasyPanel (`/root/data/dashboard-descomplicar/sessions.db` → `/data/sessions.db`)

## Stack

- **DB**: `better-sqlite3` 12.9 (síncrono, zero-deps)
- **Watcher**: `chokidar` 5.0 (file system events)
- **Parser**: `node-html-parser` 7.1 (extração HTML de worklogs)
- **Runtime**: Node.js 22 via `tsx` (systemd services)

## Componentes do Sistema

| Componente | Ficheiro | Função |
|---|---|---|
| Indexer | `api/scripts/sessions-indexer.ts` | Watcher incremental de JSONL |
| Patterns | `api/scripts/sessions-patterns.ts` | Detector semanal de padrões |
| Worklog Import | `api/scripts/sessions-worklog-import.ts` | Import de worklogs Desk |
| DB Layer | `api/services/sessions/db.ts` | Schema, queries, CRUD |
| Parser | `api/services/sessions/parser.ts` | Parse de ficheiros JSONL |
| Claude Indexer | `api/services/sessions/indexer.ts` | Indexação específica Claude |
| Hermes Indexer | `api/services/sessions/hermes-indexer.ts` | Indexação Hermes (`~/.hermes/state.db`) |
| OpenCode Indexer | `api/services/sessions/opencode-indexer.ts` | Indexação OpenCode (`~/.local/share/opencode/opencode.db`) |
| MCP Client | `api/services/sessions/mcp-client.ts` | Cliente MCP para Desk CRM |
| Watcher | `api/services/sessions/watcher.ts` | File watcher eventos |
| Patterns Engine | `api/services/sessions/patterns.ts` | Análise de padrões (19KB) |

## Fontes de Dados

- **Claude Code**: `~/.claude/projects/*/sessions/*.jsonl` (JSONL)
- **Hermes**: `~/.hermes/state.db` (SQLite)
- **OpenCode**: `~/.local/share/opencode/opencode.db` (SQLite)
- **Gemini**: `~/.claude-work/tool-invocations.jsonl` (via Gemini-Telemetry)
- **Desk CRM**: Discussions #31, #32, #33 (worklogs)

## Systemd Timers

| Timer | Schedule | Função |
|---|---|---|
| `observabilidade-indexer.service` | Sempre ligado (simple) | Watcher incremental |
| `observabilidade-worklog-import.timer` | Diário 03:00 | Import worklogs Desk |
| `observabilidade-patterns.timer` | Dom 23:00 | Detecção de padrões |

## Localizações

- **SQLite DB**: `~/.claude-work/sessions.db` (local) / `/data/sessions.db` (container)
- **Código**: `api/services/sessions/` (10 ficheiros, ~56KB)
- **Scripts**: `api/scripts/sessions-*.ts` (3 scripts)
- **Systemd**: `systemd/observabilidade-*.{service,timer}` (5 ficheiros)
- **Volume**: `/root/data/dashboard-descomplicar/sessions.db` → container

## Dependências

- **Systemd-Timers**: Execução agendada dos scripts
- **Gemini-Telemetry**: Dados de telemetria Gemini
- **MySQL-Pool**: Worklogs Desk CRM (discussions)
- **Express-API**: Rota `/api/sessions` expõe dados
- **Sistema de Ficheiros**: `~/.claude/`, `~/.hermes/`, `~/.local/share/opencode/`

## Fornece a

- **Painel-Sessoes**: Dados para listagem e detalhe
- **Express-API**: Rota `/api/sessions`
- **Sistema IA**: Métricas de uso, padrões, anomalias