2026-04-10 23:20:41 -04:00
---
layout: default
title: "TrustGraph Kayı
parent: "Turkish (Beta)"
---
2026-04-11 01:08:44 +00:00
# TrustGraph Kayı
2026-04-10 23:20:41 -04:00
> **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.
2026-04-11 01:08:44 +00:00
## Genel Bakı
TrustGraph, tüm kayı `logging` modülünü kullanı ı ı ı ı ı ı ı ı ı ı
## Varsayı ı ı
### Kayı
**Varsayı `INFO`
**Yapı ı ı `--log-level` komut satı ı ı ı ı ı
**Seçenekler**: `DEBUG` , `INFO` , `WARNING` , `ERROR` , `CRITICAL`
### Çı ı
1. **Konsol (stdout)** : Her zaman etkindir - konteynerleştirilmiş ortamlarla uyumluluğu sağlar.
2. **Loki** : İsteğe bağlı ı ı ı ı ı ı
## Merkezi Kayı
Tüm kayı ı ı ı ı `trustgraph.base.logging` modülü tarafı
`add_logging_args(parser)` - Standart kayı ı ı ı ı
`setup_logging(args)` - Ayrı ı ı ı ı ı ı ı
Bu modül, tüm sunucu tarafı ı ı ı
AsyncProcessor tabanlı
API Ağ Geçidi
MCP Sunucusu
## Uygulama Yönergeleri
### 1. Kayı
Her modül, modülün `__name__` 'ı ı ı ı ı
```python
import logging
logger = logging.getLogger(__name__)
```
Kayı ı ı ı
### 2. Hizmet Başlatma
Tüm sunucu tarafı ı ı ı ı ı ı ı
```python
from trustgraph.base import add_logging_args, setup_logging
import argparse
def main():
parser = argparse.ArgumentParser()
# Add standard logging arguments (includes Loki configuration)
add_logging_args(parser)
# Add your service-specific arguments
parser.add_argument('--port', type=int, default=8080)
args = parser.parse_args()
args = vars(args)
# Setup logging early in startup
setup_logging(args)
# Rest of your service initialization
logger = logging.getLogger(__name__)
logger.info("Service starting...")
```
### 3. Komut Satı ı ı
Tüm hizmetler bu günlük kaydı ı ı
**Günlük Seviyesi:**
```bash
--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
```
**Loki Yapı ı ı
```bash
--loki-enabled # Enable Loki (default)
--no-loki-enabled # Disable Loki
--loki-url URL # Loki push URL (default: http://loki:3100/loki/api/v1/push)
--loki-username USERNAME # Optional authentication
--loki-password PASSWORD # Optional authentication
```
**Örnekler:**
```bash
# Default - INFO level, Loki enabled
./my-service
# Debug mode, console only
./my-service --log-level DEBUG --no-loki-enabled
# Custom Loki server with auth
./my-service --loki-url http://loki.prod:3100/loki/api/v1/push \
--loki-username admin --loki-password secret
```
### 4. Ortam Değişkenleri
Loki yapı ı ı
```bash
export LOKI_URL=http://loki.prod:3100/loki/api/v1/push
export LOKI_USERNAME=admin
export LOKI_PASSWORD=secret
```
Komut satı ı ı
### 5. Kayı
#### Kayı ı ı
**DEBUG**: Sorunları ı ı ı
**INFO**: Genel bilgilendirici mesajlar (hizmet başlatı ı ı ı ı
**WARNING**: Potansiyel olarak tehlikeli durumlara yönelik uyarı ı ı ı ı ı
**ERROR**: Ciddi sorunlara yönelik hata mesajları ı ı
**CRITICAL**: Acil müdahale gerektiren sistem arı ı
#### Mesaj Formatı
```python
# Good - includes context
logger.info(f"Processing document: {doc_id}, size: {doc_size} bytes")
logger.error(f"Failed to connect to database: {error}", exc_info=True)
# Avoid - lacks context
logger.info("Processing document")
logger.error("Connection failed")
```
#### Performans Hususları
```python
# Use lazy formatting for expensive operations
logger.debug("Expensive operation result: %s", expensive_function())
# Check log level for very expensive debug operations
if logger.isEnabledFor(logging.DEBUG):
debug_data = compute_expensive_debug_info()
logger.debug(f"Debug data: {debug_data}")
```
### 6. Loki ile Yapı ı ı ı ı
Karmaşı ı ı ı ı ı ı
```python
logger.info("Request processed", extra={
'tags': {
'request_id': request_id,
'user_id': user_id,
'status': 'success'
}
})
```
Bu etiketler, otomatik etiketlerin yanı ı
`severity` - Log seviyesi (DEBUG, INFO, WARNING, ERROR, CRITICAL)
`logger` - Modül adı `__name__` 'den)
### 7. İstisna Kaydı
İstisnalar için her zaman yı ı
```python
try:
process_data()
except Exception as e:
logger.error(f"Failed to process data: {e}", exc_info=True)
raise
```
### 8. Asenkron Kayı ı
Kayı ı
Konsol çı ı ı ı ı ı
Loki çı ı ı ı ı ı
Arka plan iş parçacı ı
Ana uygulama kodunun engellenmesi olmaz
```python
import asyncio
import logging
async def async_operation():
logger = logging.getLogger(__name__)
# Logging is thread-safe and won't block async operations
logger.info(f"Starting async operation in task: {asyncio.current_task().get_name()}")
```
## Loki Entegrasyonu
### Mimari
Günlük sistemi, engellemeyen Loki entegrasyonu için Python'un yerleşik `QueueHandler` ve `QueueListener` özelliklerini kullanı
1. **QueueHandler** : Günlükler, 500 mesajlı
2. **Arka Plan İş Parçacı ı : QueueListener, günlükleri Loki'ye asenkron olarak gönderir.
3. **Usulüne Uygun Bozulma** : Loki kullanı ı
### Otomatik Etiketler
Loki'ye gönderilen her günlük şunları
`processor` : İşlemci kimliği (örneğin, `config-svc` , `text-completion` , `embeddings` )
`severity` : Günlük seviyesi (DEBUG, INFO, vb.)
`logger` : Modül adı `trustgraph.gateway.service` , `trustgraph.agent.react.service` )
### Özel Etiketler
Özel etiketleri `extra` parametresi aracı ı ı
```python
logger.info("User action", extra={
'tags': {
'user_id': user_id,
'action': 'document_upload',
'collection': collection_name
}
})
```
### Loki'de Logları
```logql
# All logs from a specific processor (recommended - matches Prometheus metrics)
{processor="config-svc"}
{processor="text-completion"}
{processor="embeddings"}
# Error logs from a specific processor
{processor="config-svc", severity="ERROR"}
# Error logs from all processors
{severity="ERROR"}
# Logs from a specific processor with text filter
{processor="text-completion"} |= "Processing"
# All logs from API gateway
{processor="api-gateway"}
# Logs from processors matching pattern
{processor=~".*-completion"}
# Logs with custom tags
{processor="api-gateway"} | json | user_id="12345"
```
### Zarif Bozulma
Eğer Loki kullanı ı `python-logging-loki` yüklü değilse:
Uyarı ı ı ı ı
Konsol kaydı
Uygulama çalı
Loki bağlantı ı ı ı ı ı ı ı
## Test
Testler sı ı ı ı ı ı ı ı
```python
# In test setup
import logging
# Reduce noise during tests
logging.getLogger().setLevel(logging.WARNING)
# Or disable Loki for tests
setup_logging({'log_level': 'WARNING', 'loki_enabled': False})
```
## İzleme Entegrasyonu
### Standart Format
Tüm günlükler tutarlı
```
2025-01-09 10:30:45,123 - trustgraph.gateway.service - INFO - Request processed
```
Biçim öğeleri:
Zaman damgası ı
Kayı ı
Kayı
Mesaj
### İzleme için Loki Sorguları
Yaygı ı
```logql
# Error rate by processor
rate({severity="ERROR"}[5m]) by (processor)
# Top error-producing processors
topk(5, count_over_time({severity="ERROR"}[1h]) by (processor))
# Recent errors with processor name
{severity="ERROR"} | line_format "{{.processor}}: {{.message}}"
# All agent processors
{processor=~".*agent.*"} |= "exception"
# Specific processor error count
count_over_time({processor="config-svc", severity="ERROR"}[1h])
```
## Güvenlik Hususları
**Hassas bilgileri asla kaydetmeyin** (şifreler, API anahtarları
**Kayı ı ı
**Hassas alanlar için yer tutucular kullanı `user_id=****1234`
**Loki kimlik doğrulaması ı ı `--loki-username` ve `--loki-password` 'i kullanı
**Güvenli taşı ı `https://loki.prod:3100/loki/api/v1/push`
## Bağı ı ı
Merkezi günlük kaydı ı
`python-logging-loki` - Loki entegrasyonu için (isteğe bağlı ı ı
Zaten `trustgraph-base/pyproject.toml` ve `requirements.txt` içinde bulunmaktadı
## Geçiş Yolu
Mevcut kod için:
1. **AsyncProcessor kullanan hizmetler** : Herhangi bir değişiklik gerekmez, Loki desteği otomatik olarak sağlanı
2. **AsyncProcessor kullanmayan hizmetler** (api-gateway, mcp-server): Zaten güncellenmiştir
3. **CLI araçları : Kapsam dı ı ı ı ı
### print()'ten günlük kaydı
```python
# Before
print(f"Processing document {doc_id}")
# After
logger = logging.getLogger(__name__)
logger.info(f"Processing document {doc_id}")
```
## Yapı ı
| Argüman | Varsayı ı
|----------|---------|---------------------|-------------|
| `--log-level` | `INFO` | - | Konsol ve Loki log seviyesi |
| `--loki-enabled` | `True` | - | Loki log kaydı ı
| `--loki-url` | `http://loki:3100/loki/api/v1/push` | `LOKI_URL` | Loki push endpoint'i |
| `--loki-username` | `None` | `LOKI_USERNAME` | Loki kimlik doğrulama kullanı ı ı
| `--loki-password` | `None` | `LOKI_PASSWORD` | Loki kimlik doğrulama parolası
