196 lines
9.2 KiB
TeX
196 lines
9.2 KiB
TeX
% 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}
|