mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 17:06:22 +02:00
Feat: TrustGraph i18n & Documentation Translation Updates (#781)
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
This commit is contained in:
Alex Jenkins
GitHub
parent
19f73e4cdc
commit
f95fd4f052
560 changed files with 236300 additions and 99 deletions
215
docs/tech-specs/logging-strategy.es.md
Normal file
215
docs/tech-specs/logging-strategy.es.md
Normal file
|
|
@ -0,0 +1,215 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Estrategia de Registro de TrustGraph"
|
||||
parent: "Spanish (Beta)"
|
||||
---
|
||||
|
||||
# Estrategia de Registro de TrustGraph
|
||||
|
||||
> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
|
||||
|
||||
## Visión general
|
||||
|
||||
TrustGraph utiliza el módulo integrado de Python `logging` para todas las operaciones de registro, con una configuración centralizada y la integración opcional de Loki para la agregación de registros. Esto proporciona un enfoque estandarizado y flexible para el registro en todos los componentes del sistema.
|
||||
|
||||
## Configuración predeterminada
|
||||
|
||||
### Nivel de registro
|
||||
- **Nivel predeterminado**: `INFO`
|
||||
- **Configurable a través de**: Argumento de línea de comandos `--log-level`
|
||||
- **Opciones**: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
|
||||
|
||||
### Destinos de salida
|
||||
1. **Consola (stdout)**: Siempre habilitado - asegura la compatibilidad con entornos contenedorizados
|
||||
2. **Loki**: Agregación centralizada de registros opcional (habilitado por defecto, se puede deshabilitar)
|
||||
|
||||
## Módulo de registro centralizado
|
||||
|
||||
Todas las configuraciones de registro se gestionan mediante el módulo `trustgraph.base.logging`, que proporciona:
|
||||
- `add_logging_args(parser)` - Agrega argumentos de línea de comandos estándar para registro
|
||||
- `setup_logging(args)` - Configura el registro a partir de los argumentos analizados
|
||||
|
||||
Este módulo se utiliza en todos los componentes del lado del servidor:
|
||||
- Servicios basados en AsyncProcessor
|
||||
- API Gateway
|
||||
- Servidor MCP
|
||||
|
||||
## Guía de implementación
|
||||
|
||||
### 1. Inicialización del registrador
|
||||
|
||||
Cada módulo debe crear su propio registrador utilizando el nombre del módulo:
|
||||
|
||||
```python
|
||||
import logging
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
```
|
||||
|
||||
El nombre del registrador se utiliza automáticamente como etiqueta en Loki para filtrar y buscar.
|
||||
|
||||
### 2. Inicialización del servicio
|
||||
|
||||
Todos los servicios del lado del servidor obtienen automáticamente la configuración de registro a través del módulo centralizado:
|
||||
|
||||
```python
|
||||
from trustgraph.base import add_logging_args, setup_logging
|
||||
import argparse
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser()
|
||||
|
||||
# Agrega argumentos estándar de registro (incluida la configuración de Loki)
|
||||
add_logging_args(parser)
|
||||
|
||||
# Agrega tus argumentos específicos del servicio
|
||||
parser.add_argument('--port', type=int, default=8080)
|
||||
|
||||
args = parser.parse_args()
|
||||
args = vars(args)
|
||||
|
||||
# Configura el registro temprano en el inicio
|
||||
setup_logging(args)
|
||||
|
||||
# Resto de la inicialización del servicio
|
||||
logger = logging.getLogger(__name__)
|
||||
logger.info("Servicio iniciado...")
|
||||
```
|
||||
|
||||
### 3. Argumentos de línea de comandos
|
||||
|
||||
Todos los servicios admiten estos argumentos de registro:
|
||||
|
||||
**Nivel de registro:**
|
||||
```bash
|
||||
--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
|
||||
```
|
||||
|
||||
**Configuración de Loki:**
|
||||
```bash
|
||||
--loki-enabled # Habilita Loki (predeterminado)
|
||||
--no-loki-enabled # Deshabilita Loki
|
||||
--loki-url URL # URL de envío a Loki (predeterminado: http://loki:3100/loki/api/v1/push)
|
||||
--loki-username USERNAME # Nombre de usuario opcional de autenticación
|
||||
--loki-password PASSWORD # Contraseña opcional de autenticación
|
||||
```
|
||||
|
||||
**Ejemplos:**
|
||||
```bash
|
||||
# Predeterminado - nivel INFO, Loki habilitado
|
||||
./my-service
|
||||
|
||||
# Modo DEBUG, solo consola
|
||||
./my-service --log-level DEBUG --no-loki-enabled
|
||||
|
||||
# URL de Loki personalizada con autenticación
|
||||
./my-service --loki-url http://loki.prod:3100/loki/api/v1/push \
|
||||
--loki-username admin --loki-password secret
|
||||
```
|
||||
|
||||
### 4. Variables de entorno
|
||||
|
||||
La configuración de Loki admite los valores predeterminados de las variables de entorno:
|
||||
|
||||
```bash
|
||||
export LOKI_URL=http://loki.prod:3100/loki/api/v1/push
|
||||
export LOKI_USERNAME=admin
|
||||
export LOKI_PASSWORD=secret
|
||||
```
|
||||
|
||||
Los argumentos de la línea de comandos tienen prioridad sobre las variables de entorno.
|
||||
|
||||
### 5. Mejores prácticas de registro
|
||||
|
||||
#### Uso de los niveles de registro
|
||||
- **DEBUG**: Información detallada para diagnosticar problemas (valores de variables, entrada/salida de funciones)
|
||||
- **INFO**: Mensajes informativos generales (servicio iniciado, configuración cargada, hitos de procesamiento)
|
||||
- **WARNING**: Mensajes de advertencia para situaciones potencialmente dañinas (características obsoletas, errores recuperables)
|
||||
- **ERROR**: Mensajes de error para problemas serios (operaciones fallidas, excepciones)
|
||||
- **CRITICAL**: Mensajes críticos para fallas del sistema que requieren atención inmediata
|
||||
|
||||
#### Formato de mensaje
|
||||
```python
|
||||
# Bueno - incluye contexto
|
||||
logger.info(f"Procesando documento: {doc_id}, tamaño: {doc_size} bytes")
|
||||
logger.error(f"No se pudo conectar a la base de datos: {error}", exc_info=True)
|
||||
|
||||
# No bueno - carece de contexto
|
||||
logger.info("Procesando documento")
|
||||
logger.error("Conexión fallida")
|
||||
```
|
||||
|
||||
#### Consideraciones de rendimiento
|
||||
```python
|
||||
# Usa la incrustación para operaciones costosas
|
||||
logger.debug("Resultado de la operación costosa: %s", expensive_function())
|
||||
|
||||
# Comprueba el nivel de registro para operaciones de depuración muy costosas
|
||||
if logger.isEnabledFor(logging.DEBUG):
|
||||
debug_data = compute_expensive_debug_info()
|
||||
logger.debug(f"Datos de depuración: {debug_data}")
|
||||
```
|
||||
|
||||
#### 6. Registro estructurado con Loki
|
||||
|
||||
Para datos complejos, usa el registro estructurado con etiquetas adicionales para Loki:
|
||||
|
||||
```python
|
||||
logger.info("Solicitud procesada", extra={
|
||||
'tags': {
|
||||
'request_id': request_id,
|
||||
'user_id': user_id,
|
||||
'status': 'éxito'
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Estas etiquetas se convierten en etiquetas de búsqueda en Loki, además de las etiquetas automáticas:
|
||||
- `severity` - Nivel de registro (DEBUG, INFO, etc.)
|
||||
- `logger` - Nombre del módulo (del `__name__`)
|
||||
|
||||
### 7. Registro de excepciones
|
||||
|
||||
Siempre incluye trazas de pila para las excepciones:
|
||||
|
||||
```python
|
||||
try:
|
||||
process_data()
|
||||
except Exception as e:
|
||||
logger.error(f"No se pudo procesar los datos: {e}", exc_info=True)
|
||||
```
|
||||
|
||||
### 8. Dependencias
|
||||
|
||||
El módulo centralizado de registro requiere:
|
||||
- `python-logging-loki` - Para la integración de Loki (opcional, funciona si falta)
|
||||
|
||||
Ya incluido en `trustgraph-base/pyproject.toml` y `requirements.txt`.
|
||||
|
||||
## Migración
|
||||
|
||||
Para código existente:
|
||||
|
||||
1. **Servicios que ya utilizan AsyncProcessor**: No se necesita cambios, la integración de Loki es automática
|
||||
2. **Servicios que no utilizan AsyncProcessor** (api-gateway, mcp-server): Ya actualizado
|
||||
3. **Herramientas de línea de comandos**: Fuera del alcance - continúe usando `print()` o registro simple
|
||||
|
||||
### De `print()` a registro:
|
||||
```python
|
||||
# Antes
|
||||
print(f"Procesando documento {doc_id}")
|
||||
|
||||
# Después
|
||||
logger = logging.getLogger(__name__)
|
||||
logger.info(f"Procesando documento {doc_id}")
|
||||
```
|
||||
|
||||
## Resumen de configuración
|
||||
|
||||
| Argumento | Predeterminado | Variable de entorno | Descripción |
|
||||
|---|---|---|---|
|
||||
| `--log-level` | `INFO` | - | Nivel de registro en la consola y Loki |
|
||||
| `--loki-enabled` | `True` | - | Habilita el registro de Loki |
|
||||
| `--loki-url` | `http://loki:3100/loki/api/v1/push` | `LOKI_URL` | Puntero al API de Loki |
|
||||
| `--loki-username` | `None` | `LOKI_USERNAME` | Nombre de usuario de autenticación para Loki |
|
||||
| `--loki-password` | `None` | `LOKI_PASSWORD` | Contraseña de autenticación para Loki |
|
||||
Loading…
Add table
Add a link
Reference in a new issue