trustgraph/docs/tech-specs/logging-strategy.sw.md

layout	title	parent
default	Mbinu ya Uandikaji (Logging) ya TrustGraph	Swahili (Beta)

Mbinu ya Uandikaji (Logging) ya 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.

Muhtasari

TrustGraph hutumia moduli iliyojumuishwa ya Python logging kwa operesheni zote za uandikaji, pamoja na usanidi uliokatikati na ujumuishaji wa Loki wa hiari kwa ukusanyaji wa matangazo. Hii hutoa mbinu iliyoendeshwa na kikao, inayobadilika kwa uandikaji katika vipengele vyote vya mfumo.

Mpangilio Chaguwa

Kigezo cha Uandikaji

Kigezo Chaguwa: INFO Inayoweza kusanidiwa kupitia: hoja ya mstari wa amri --log-level Chaguo: DEBUG, INFO, WARNING, ERROR, CRITICAL

Vituo vya Matokeo

1. Kikonsoli (stdout): Daima inaanzishwa - huhakikisha utangamano na mazingira yaliyofungwa.
2. Loki: Ukusanyaji wa matangazo uliokatikati wa hiari (inaanzishwa kwa chaguwa, inaweza kuzimwa).

Moduli ya Uandikaji Iliyokatikati

Mpangilio wote wa uandikaji unadhibitiwa na moduli trustgraph.base.logging, ambayo hutoa: add_logging_args(parser) - Inaongeza hoja za kawaida za CLI za uandikaji. setup_logging(args) - Inasanidi uandikaji kutoka kwa hoja zilizochanganuliwa.

Moduli hii inatumika na vipengele vyote vya upande wa seva: Huduma zinazotegemea AsyncProcessor API Gateway MCP Server

Miongozo ya Utendaji

1. Uanzishaji wa Kichunguzi

Kila moduli inapaswa kuunda kichunguzi chake mwenyewe kwa kutumia moduli ya __name__:

import logging

logger = logging.getLogger(__name__)

Jina la kichujio hutumika kiotomatiki kama lebo katika Loki kwa ajili ya kuchujua na kutafuta.

2. Uanzishaji wa Huduma

Huduma zote za upande wa seva hupokea kiotomatiki usanidi wa uandishi wa matukio kupitia moduli ya kituo:

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. Vigezo vya Kamba ya Amri

Huduma zote zinaunga mkono vigezo hivi vya uandishi wa matukio:

Kiwango cha Uandishi:

--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}

Mipangilio ya Loki:

--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

Mfano:

# 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. Vigezo vya Mazingira

Usanidi wa Loki unaounga mkono utumizi wa vigezo vya mazingira kama chaguo-mbadala:

export LOKI_URL=http://loki.prod:3100/loki/api/v1/push
export LOKI_USERNAME=admin
export LOKI_PASSWORD=secret

Vigezo vya mstari wa amana hupendelewa kuliko vigezo vya mazingira.

5. Mbinu Bora za Uandishi wa Matukio

Matumizi ya Viwango vya Matukio

DEBUG: Habari za kina kwa ajili ya utambuzi wa matatizo (maelezo ya vigezo, kuingia/kuacha kazi) INFO: Jumbe za habari za jumla (huduma ilianza, usanidi ulipakuliwa, hatua muhimu za usindikaji) WARNING: Jumbe za onyo kwa hali ambazo zinaweza kuwa hatari (vipengele vilivyomalizwa, makosa yanayoweza kutatuliwa) ERROR: Jumbe za makosa kwa matatizo makubwa (operesheni zilizoendea, ukiukaji) CRITICAL: Jumbe muhimu kwa ajili ya hitilafu za mfumo zinazohitaji uangalifu wa haraka

Muundo wa Jumbe

# 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")

Mawazo ya Utendaji

# 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. Uandikaji Maelezo Ulio Pamoja na Muundo Ukitumia Loki

Kwa data ngumu, tumia uandikaji maelezo uliopangwa na lebo za ziada kwa ajili ya Loki:

logger.info("Request processed", extra={
    'tags': {
        'request_id': request_id,
        'user_id': user_id,
        'status': 'success'
    }
})

Alama hizi zinakuwa lebo zinazoweza kutafutwa katika Loki, pamoja na lebo za kiotomatiki: severity - Kiwango cha matukio (DEBUG, INFO, WARNING, ERROR, CRITICAL) logger - Jina la moduli (kutoka __name__)

7. Uandikaji wa Matukio ya Aina ya Makosa

Daima jumuisha maandishi ya mfuatano wa mazingira kwa matukio ya aina ya makosa:

try:
    process_data()
except Exception as e:
    logger.error(f"Failed to process data: {e}", exc_info=True)
    raise

8. Mambo ya Kuzingatia Kuhusu Uandikaji wa Matukio (Logging) ya Aina ya Async

Mfumo wa uandikaji wa matukio hutumia vichuja (handlers) visivyozuia (non-blocking) vilivyopangwa kwa Loki: Matokeo ya konseli ni ya aina moja kwa moja (haraka) Matokeo ya Loki yanapangwa na buffer ya ujumbe 500 Mfumo wa nyuma hushughulikia usambazaji wa Loki Hakuna kuzuiliwa kwa msimbo mkuu wa programu

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()}")

Uunganisho wa Loki

Muundo

Mfumo wa uandikaji matumizi hutumia QueueHandler na QueueListener zilizojumuishwa katika Python kwa uunganisho wa Loki usiozuia:

1. QueueHandler: Matukio yanawekwa kwenye folyo ya ujumbe 500 (hayazuilii)
2. Mfululizo wa Nyuma: QueueListener hutuma matukio kwa Loki kwa njia isiyo ya moja kwa moja
3. Upunguzaji wa Kawaida: Ikiwa Loki haipatikani, uandikaji matukio kwenye konsi unaendelea

Laha za Otomatiki

Kila tukio linalotumwa kwa Loki linajumuisha: processor: Kitambulisho cha kichakata (k.m., config-svc, text-completion, embeddings) severity: Kiwango cha matukio (DEBUG, INFO, n.k.) logger: Jina la moduli (k.m., trustgraph.gateway.service, trustgraph.agent.react.service)

Laha za Msingi

Ongeza laha za msingi kupitia parameter ya extra:

logger.info("User action", extra={
    'tags': {
        'user_id': user_id,
        'action': 'document_upload',
        'collection': collection_name
    }
})

Kuuliza Kumbukumbu katika Loki

# 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"

Upunguzaji wa Athari (Graceful Degradation)

Ikiwa Loki haipatikani au python-logging-loki haijafunguliwa: Ujumbe wa onyo huonyeshwa kwenye konsoli Uandikaji kwenye konsoli unaendelea kama kawaida Programu inaendelea kuendeshwa Hakuna mfumo wa kujaribu tena muunganisho wa Loki (fainda haraka, punguza athari)

Majaribio

Wakati wa majaribio, fikiria kutumia usanidi tofauti wa uandikaji:

# 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})

Ufuatiliaji wa Uunganishaji

Muundo wa Kawaida

Matumizi yote ya rekodi hutumia muundo unaofuata sheria:

2025-01-09 10:30:45,123 - trustgraph.gateway.service - INFO - Request processed

Vipengele vya muundo: Wakati (muundo wa ISO na milisekundi) Jina la kisajili (njia ya moduli) Kiwango cha kisajili Ujumbe

Maswali ya Loki kwa Ufuatiliaji

Maswali ya kawaida ya ufuatiliaji:

# 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])

Mambo ya Kuzingatia Kuhusu Usalama

Usisahirishe kamwe taarifa nyeti (manenosi, funguo za API, data ya kibinafsi, alama) Safisha pembejeo za mtumiaji kabla ya kuzisajili Tumia nafasi za kubadilika kwa sehemu nyeti: user_id=****1234 Uthibitishaji wa Loki: Tumia --loki-username na --loki-password kwa matumizi salama Usafiri salama: Tumia HTTPS kwa URL ya Loki katika mazingira ya uzalishaji: https://loki.prod:3100/loki/api/v1/push

Utegemezi

Moduli ya uandikaji matukio ya kituo inahitaji: python-logging-loki - Kwa ujumuishaji wa Loki (hiari, utendaji wa chini ikiwa haipo)

Tayari imejumuishwa katika trustgraph-base/pyproject.toml na requirements.txt.

Njia ya Uhamishaji

Kwa programu zilizopo:

1. Huduma ambazo tayari zinatumia AsyncProcessor: Hakuna mabadiliko yanayohitajika, usaidizi wa Loki ni moja kwa moja
2. Huduma ambazo hazitumii AsyncProcessor (api-gateway, mcp-server): Tayari zimefanyiwa mabadiliko
3. Zana za CLI: Hayajajumuishwa - endelea kutumia print() au uandikaji matukio rahisi

Kutoka print() hadi uandikaji matukio:

# Before
print(f"Processing document {doc_id}")

# After
logger = logging.getLogger(__name__)
logger.info(f"Processing document {doc_id}")

Muhtasari wa Usanidi

Jina la hoja	Chaguizi	Kigezo cha mazingira	Maelezo
--log-level	INFO	-	Kigezo cha uingishaji wa Loki na kituo cha uendeshaji
--loki-enabled	True	-	Wezesha uingishaji wa Loki
--loki-url	http://loki:3100/loki/api/v1/push	LOKI_URL	Kifaa cha utumaji cha Loki
--loki-username	None	LOKI_USERNAME	Jina la mtumiaji la uthibitishaji wa Loki
--loki-password	None	LOKI_PASSWORD	Nenosiri la uthibitishaji wa Loki