% Helgen Drogheda — Manual de Consulta de Logs (Grafana / Loki · backend htracker)
% Compilar:  latexmk -xelatex 2026-06-22_Drogheda_Manual-Logs-Grafana_v1.0.tex   (XeLaTeX)
\documentclass[10pt]{article}
\newcommand{\sistema}{Helgen Drogheda}
\newcommand{\sistemapdf}{Manual de Consulta de Logs — Grafana / Loki}
\newcommand{\doctipo}{Manual de Operación}
\input{estilo-helgen.tex}
\usepackage{amssymb}

\begin{document}

\helgenportada{Consulta de Logs en Grafana}{Observabilidad del backend \texttt{htracker} — Grafana Loki (capa gratuita)}{%
\begin{tabular}{@{}ll@{}}
Documento & Manual de Operación\\
Versión & 1.0\\
Fecha & 22 de junio de 2026\\
Autor & Dr.\ Leopoldo Rodríguez Salazar — Helgen Technologies\\
Sistema & \texttt{htracker} (retranslator + monitor), servidor \texttt{HelgenServer}\\
Fuente & \texttt{04-Source-Code/htracker/log-shipping/}\\
Clasificación & Confidencial — Uso interno\\
\end{tabular}}

\tableofcontents
\vspace{4pt}

\section{Propósito}
El servidor del backend tiene \textbf{muy poco disco}, por lo que el gateway \textbf{no}
guarda logs localmente. En su lugar, los registros se \textbf{envían fuera del servidor}
a \textbf{Grafana Loki} (capa gratuita) y se consultan desde \textbf{Grafana}. Este manual
explica cómo \emph{entrar} a Grafana y \emph{consultar} los logs de la flota — no requiere
acceso al servidor para leer.

\begin{helgennotice}[En una frase]
Los logs del backend viven en \textbf{Grafana Loki}. Para verlos: abre Grafana
$\rightarrow$ \textbf{Explore} $\rightarrow$ fuente de datos \textbf{Loki} $\rightarrow$
escribe \texttt{\{job="htracker"\}}.
\end{helgennotice}

\section{Arquitectura del envío de logs}
El gateway escribe a la salida estándar; \texttt{systemd} la captura en \texttt{journald}
(un búfer en anillo \textbf{limitado a 200 MB}, que nunca llena el disco); un agente ligero
(\textbf{Vector}, o \textbf{Grafana Alloy}) lee el journal y lo empuja por HTTPS a Loki.

\begin{center}
\begin{tikzpicture}[node distance=6mm and 8mm]
  \node[caja] (rt) {retranslator\\\scriptsize(stdout)};
  \node[caja, right=of rt] (jd) {journald\\\scriptsize(tope 200 MB)};
  \node[caja, right=of jd] (vec) {Vector\\\scriptsize(o Alloy)};
  \node[cajaoscura, right=of vec] (loki) {Grafana\\Loki};
  \node[caja, right=of loki] (graf) {Grafana\\\scriptsize(UI)};
  \draw[flecha] (rt)--(jd); \draw[flecha] (jd)--(vec);
  \draw[flechaacento] (vec)-- node[etiqueta, above]{HTTPS} (loki); \draw[flecha] (loki)--(graf);
\end{tikzpicture}
\end{center}

\noindent\textbf{Por qué así:} el gateway nunca escribe un archivo que crece; \texttt{journald}
es un búfer pequeño y limitado (sobrevive cortes breves de Loki); el agente empuja con un
búfer acotado que \emph{descarta lo más nuevo} si Loki no responde — de modo que la ruta de
logs \textbf{jamás} bloquea ni tumba al gateway.

\begin{helgennotice}[¿Vector o Alloy? — verifícalo una vez]
El \texttt{setup-logging.sh} instala \textbf{Vector} por defecto (etiqueta
\texttt{job="htracker"}). Si en su lugar se usó el \emph{onboarding de Linux} de Grafana
Cloud, el agente es \textbf{Alloy} y los logs aparecen por unidad de systemd
(\texttt{\{unit="htracker.service"\}}). Si una consulta no devuelve nada, usa el
\textbf{Label browser} de Grafana para ver qué etiquetas existen.
\end{helgennotice}

\section{Acceso a Grafana}
\subsection{Grafana en la nube (nada que instalar)}
\begin{enumerate}[leftmargin=1.5em]
  \item Entra a tu \textbf{stack de Grafana Cloud} (URL del tipo \texttt{https://<stack>.grafana.net}).
  \item Menú lateral $\rightarrow$ \textbf{Explore}.
  \item Arriba, selecciona la fuente de datos \textbf{Loki}.
  \item Escribe la consulta (sección 4) y presiona \textbf{Run query}. Ajusta el rango de
        tiempo arriba a la derecha.
\end{enumerate}

\subsection{Grafana local (si prefieres correr la interfaz tú mismo)}
Los datos siguen en Grafana Cloud; sólo el visor es local.
\begin{verbatim}
docker run -d --name grafana -p 3000:3000 grafana/grafana-oss
# http://localhost:3000  (admin/admin)
# Connections -> Data sources -> Loki:
#   URL:  <LOKI_URL>    Auth: Basic   user: <LOKI_USER>   password: <LOKI_TOKEN>
\end{verbatim}

\begin{helgennotice}[Credenciales]
\texttt{LOKI\_URL}, \texttt{LOKI\_USER} y \texttt{LOKI\_TOKEN} están en
\texttt{/etc/vector/htracker.env} del servidor y en la consola de Grafana Cloud
(\emph{Connections} $\rightarrow$ \emph{Hosted logs}). \textbf{Son secretos} — viven en
\texttt{.env.vector} (ignorado por git); nunca se suben al repo.
\end{helgennotice}

\section{Cómo consultar los logs (LogQL)}
En \textbf{Explore} con la fuente \textbf{Loki}. Loki indexa \textbf{etiquetas}, no el texto;
todo lo demás se filtra con \texttt{|=} (contiene) en el momento de la consulta.

\begin{verbatim}
{job="htracker"}                           # todo el backend
{job="htracker", level="error"}            # sólo errores
{job="htracker", unit="htracker.service"}  # sólo el gateway (retranslator)
{job="htracker"} |= "Anti-Salto"           # rechazos del filtro anti-salto
{job="htracker"} |= "victimas_backend"     # el resumen 1/min (victimas de backend)
{job="htracker"} |= "ADDR-CHANGE"          # cambios de direccion SIM/NAT
\end{verbatim}

\noindent Si el envío es por \textbf{Alloy} (no Vector), usa la unidad de systemd:
\begin{verbatim}
{unit="htracker.service"}
{unit="htracker.service"} |= "victimas_backend"
\end{verbatim}

\section{Qué se registra}
\begin{center}\footnotesize\renewcommand{\arraystretch}{1.3}
\begin{tabularx}{\linewidth}{@{}>{\bfseries\color{HelgenIndigo}}L{3.6cm} X@{}}
\toprule
Etiquetas (labels) & \texttt{job=htracker}, \texttt{host}, \texttt{unit}
  (\texttt{htracker.service} / \texttt{-web} / \texttt{-notifier}), \texttt{level}
  (\texttt{info}/\texttt{warn}/\texttt{error}/\texttt{debug})\\
Nivel por defecto & \texttt{INFO}: sólo \textbf{eventos} + una línea de \textbf{resumen cada
  60 s} (\texttt{[SUMMARY]} / \texttt{victimas\_backend}). El detalle por paquete es
  \texttt{DEBUG} y \textbf{no} se envía.\\
Eventos clave & anti-salto (\texttt{Anti-Salto}), cambios de dirección SIM/NAT
  (\texttt{ADDR-CHANGE}), víctimas de backend (unidad en línea en htracker pero ausente en
  Wialon).\\
\bottomrule
\end{tabularx}
\end{center}

\section{Retención, límites y seguridad de disco}
\begin{itemize}
  \item \textbf{Loki (capa gratuita):} 50 GB/mes, \textbf{retención de 14 días}, Grafana
        incluido. Tras el recorte de verbosidad se usa una fracción mínima.
  \item \textbf{journald (servidor):} \texttt{SystemMaxUse=200M}, retención 3 días
        (\texttt{/etc/systemd/journald.conf.d/htracker.conf}). Aunque Loki esté caído días,
        el disco \textbf{no} se llena.
  \item \textbf{Búfer de Vector:} en memoria, descarta lo más nuevo si Loki no responde.
\end{itemize}

\section{Verbosidad (nivel de log)}
\begin{itemize}
  \item \texttt{GW\_LOG\_LEVEL} (por defecto \texttt{INFO}). Para depurar una unidad en vivo,
        ponlo en \texttt{DEBUG} \emph{temporalmente}.
  \item \texttt{GW\_LOG\_SUMMARY\_S} (por defecto 60) — cadencia del resumen.
\end{itemize}
\begin{helgennotice}[No dejes DEBUG encendido]
\texttt{DEBUG} registra cada paquete e inunda la tubería (y consume la cuota de Loki).
Úsalo unos minutos y regresa a \texttt{INFO}.
\end{helgennotice}

\section{Salud del envío y diagnóstico}
En el servidor (\texttt{ssh HelgenServer}):
\begin{verbatim}
systemctl status vector          # esta activo el agente?
journalctl -u vector -f          # esta enviando? errores de Loki?
\end{verbatim}
\noindent \textbf{No aparecen logs en Grafana:} (1) confirma \texttt{vector} activo; (2) revisa
credenciales/endpoint en \texttt{/etc/vector/htracker.env}; (3) verifica el rango de tiempo en
Grafana; (4) revisa el \textbf{Label browser} (¿\texttt{job} o \texttt{unit}?, Vector vs Alloy).

\section{Puesta en marcha / reinstalación}
Sólo si hay que reinstalar el envío (normalmente ya está activo). En el servidor, desde
\texttt{/home/itadmin/htracker/log-shipping}:
\begin{verbatim}
cp .env.vector.example .env.vector
nano .env.vector            # pega LOKI_URL / LOKI_USER / LOKI_TOKEN
./setup-logging.sh          # limita journald, --no-filelog, instala Vector, arranca
# ./setup-logging.sh --journald-only   # si Grafana Alloy ya envia el journal
\end{verbatim}
\noindent \texttt{deploy.sh} ya sincroniza la carpeta \texttt{log-shipping/} al servidor.
Detalle completo: \texttt{04-Source-Code/htracker/log-shipping/README.md}.

\section{Referencia rápida de consultas}
\begin{center}\footnotesize\renewcommand{\arraystretch}{1.3}
\begin{tabularx}{\linewidth}{@{}>{\ttfamily\color{HelgenIndigo}}L{6.3cm} X@{}}
\toprule
\normalfont\bfseries Consulta & \normalfont\bfseries Qué muestra\\
\midrule
\{job="htracker"\} & Todo el backend\\
\{job="htracker", level="error"\} & Sólo errores\\
\{job="htracker", unit="htracker.service"\} & Sólo el gateway (retranslator)\\
\{job="htracker"\} |= "victimas\_backend" & Resumen 1/min — víctimas de backend\\
\{job="htracker"\} |= "Anti-Salto" & Rechazos del filtro anti-salto\\
\{job="htracker"\} |= "ADDR-CHANGE" & Cambios de dirección SIM/NAT\\
\bottomrule
\end{tabularx}
\end{center}

\vfill
\begin{center}\scriptsize\color{gray}
Helgen Technologies · Project Drogheda · Observabilidad del backend · Documento interno · v1.0 (22 jun 2026)
\end{center}

\end{document}