Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,10 @@ from zcs.core.exception import ZcsException
from zcs.core.logger import ZcsLogging
```

## Documentation

Technical documentation of the library (OKF bundle): see [okf/index.md](./okf/index.md).

## Local development

See [Local Development](./docs/LOCAL_DEVELOPMENT.md).
Expand Down
1 change: 1 addition & 0 deletions okf/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
viz.html
39 changes: 39 additions & 0 deletions okf/api/eccezioni.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
---
type: API Reference
title: "Eccezioni: ZcsException"
description: "ZcsException: parametri, codice di errore casuale, serializzazione con get_as_dict e legame con il logger."
resource: https://github.com/zcsadmin/zcs-python-core/blob/main/app/src/zcs/core/exception/exception.py
tags: [eccezioni, zcs-exception, error-code]
status: draft
generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z }
sources:
- { id: exc, resource: ../../app/src/zcs/core/exception/exception.py, title: "ZcsException", last_modified: 2025-10-15T08:50:58Z }
- { id: logger, resource: ../../app/src/zcs/core/logger/logger.py, title: "Uso del codice di errore nel logger", last_modified: 2026-04-03T07:58:22Z }
---

# Eccezioni (`zcs.core.exception`)

Esporta `ZcsException`, l'eccezione usata dai servizi Follia per errori da mostrare all'utente.

## Costruttore

`ZcsException(user_message="Unknown error.", error_source="Unspecified", status_code=500, internal_message=None)`.[^exc]

| Campo | Getter | Note |
|---|---|---|
| `user_message` | `get_user_message()` | Testo passato anche a `Exception.__init__` |
| `error_source` | `get_error_source()` | Chi ha generato l'errore |
| `status_code` | `get_status_code()` | Predefinito 500 |
| `internal_message` | `get_internal_message()` | Dettaglio non pensato per l'utente |
| codice errore | `get_error_code()` | 5 caratteri casuali tra maiuscole e cifre, generati a ogni istanza (r.18) |

- `get_as_dict()` restituisce `error_code`, `user_message`, `internal_message`, `error_source`, `status_code` e **`traceback`** (testo completo). Chi lo inoltra a un client deve scegliere cosa mostrare: `internal_message` e `traceback` non sono pensati per l'esterno.
- `str(exc)` ha la forma `<codice> - <sorgente> - <messaggio interno> - <messaggio utente>`.
- Il codice è casuale, non derivato dall'errore: due errori uguali hanno codici diversi.

## Legame con il logger

Il logger legge il codice dell'eccezione e lo scrive nell'etichetta `error_code` del log JSON.[^logger] Dettagli in [logger](logger.md).

[^exc]: `exception.py` r.7-46.
[^logger]: `logger.py` r.12-32, funzione `record_factory`.
6 changes: 6 additions & 0 deletions okf/api/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# API

* [Sessione: RequestState e contesto della richiesta](sessione.md) - RequestState, request_context, AuthInfo, QaInfo, FolliaModule
* [Logger: ZcsLogging e filtro degli endpoint](logger.md) - formato JSON e console, EndpointFilter
* [Eccezioni: ZcsException](eccezioni.md) - codice di errore, get_as_dict
* [Telemetria](telemetria.md) - ZcsTelemetry, setup_logging, set_trace_attributes
38 changes: 38 additions & 0 deletions okf/api/logger.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
type: API Reference
title: "Logger: ZcsLogging e filtro degli endpoint"
description: "ZcsLogging, i due formatter (JSON per Cloud Logging e console) e EndpointFilter: parametri, formato dei log e campi del contesto aggiunti."
resource: https://github.com/zcsadmin/zcs-python-core/blob/main/app/src/zcs/core/logger/logger.py
tags: [logger, cloud-logging, formatter, endpoint-filter]
status: draft
generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z }
sources:
- { id: logger, resource: ../../app/src/zcs/core/logger/logger.py, title: "ZcsLogging e formatter", last_modified: 2026-04-03T07:58:22Z }
- { id: filter, resource: ../../app/src/zcs/core/logger/endpoint_filter.py, title: "EndpointFilter", last_modified: 2025-06-27T08:46:03Z }
---

# Logger (`zcs.core.logger`)

Esporta `ZcsLogging` e `EndpointFilter`.

## ZcsLogging

`ZcsLogging(enable_cloud_logging: bool = True, log_level = logging.INFO)`; `get_logger()` restituisce il logger chiamato `zcsapp`.[^logger] L'annotazione di `log_level` è `str`, ma il valore predefinito è un intero (`logging.INFO`).

| Modo | Formato | Quando |
|---|---|---|
| `enable_cloud_logging=True` (predefinito) | una riga JSON per record, con `severity`, `message`, `time`, `logging.googleapis.com/sourceLocation` e `logging.googleapis.com/labels` | servizi nel cluster |
| `enable_cloud_logging=False` | testo `LIVELLO data - messaggio`, con colori per livello; il logger `root` aggiunge `(file:riga)` | sviluppo locale |

Etichette del formato JSON: `logger_name` e `error_code` sempre; `op_code`, `request_id`, `delta_ns`, `total_ns` solo se nel `request_context` c'è un `RequestState` (r.60-69). Nel formato console il contesto diventa un prefisso `[OP_CODE:..][REQ_ID:..]` e un suffisso con i tempi (r.108-110).

`error_code` viene dal codice della `ZcsException` quando il record contiene un'eccezione di quel tipo, nel messaggio o allegata (r.15-27).

Gli effetti globali del costruttore, il significato dei tempi e il messaggio sostituito sono in [comportamenti](../comportamenti.md).

## EndpointFilter

`logging.Filter` che scarta i record il cui messaggio contiene `GET <endpoint>`.[^filter] Gli endpoint predefiniti sono `/health`, `/metrics` e `/info` (r.11). Il confronto è una ricerca di sottostringa nel messaggio già formattato. Il filtro non si applica da solo: il consumatore lo aggiunge al logger che stampa gli accessi.

[^logger]: `logger.py`, `ZcsLogging.__init__` r.117-150.
[^filter]: `endpoint_filter.py` r.8-26.
60 changes: 60 additions & 0 deletions okf/api/sessione.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
type: API Reference
title: "Sessione: RequestState e contesto della richiesta"
description: "Classi e funzioni di zcs.core.session: RequestState, request_context, AuthInfo, QaInfo, FolliaModule, con campi, valori predefiniti e chi li imposta."
resource: https://github.com/zcsadmin/zcs-python-core/blob/main/app/src/zcs/core/session/request_state.py
tags: [sessione, request-state, contextvar, auth-info]
status: draft
generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z }
sources:
- { id: state, resource: ../../app/src/zcs/core/session/request_state.py, title: "RequestState", last_modified: 2026-05-13T15:29:36Z }
- { id: ctx, resource: ../../app/src/zcs/core/session/request_context.py, title: "request_context", last_modified: 2025-10-15T08:50:58Z }
- { id: auth, resource: ../../app/src/zcs/core/session/auth_info.py, title: "AuthInfo", last_modified: 2025-12-02T13:54:27Z }
- { id: qa, resource: ../../app/src/zcs/core/session/qa_info.py, title: "QaInfo", last_modified: 2025-12-11T13:51:36Z }
- { id: module, resource: ../../app/src/zcs/core/session/follia_module.py, title: "FolliaModule", last_modified: 2025-12-04T13:26:01Z }
---

# Sessione (`zcs.core.session`)

Il modulo esporta `request_context`, `RequestState`, `AuthInfo`, `FolliaModule` e `QaInfo`.

## request_context

Un `contextvars.ContextVar` chiamato `"request_state"` con **`default=None`**.[^ctx] Non ha funzioni di supporto: chi usa la libreria chiama `request_context.set(...)` e `request_context.get()`. Cosa succede se il contesto non è stato impostato: vedi [comportamenti](../comportamenti.md), voce "Contesto assente".

## RequestState

Costruttore (tutti i parametri sono opzionali):[^state]

| Parametro | Predefinito | Note |
|---|---|---|
| `request_id` | generato | Se assente: `uuid4`, con prefisso `<prefix>_` se dato `prefix` (`generate_op_code`, r.236) |
| `prefix` | `None` | Usato solo per generare l'id |
| `op_code` | uguale a `request_id` | r.31 |
| `auth_info`, `follia_module`, `qa_info` | `None` | Oggetti descritti sotto |
| `doc_type`, `size`, `total_pages`, `job_id`, `file_id`, `channel` | `None` | |
| `attempts` | `0` | |
| `custom_data` | `{}` | Anche se si passa `None` o un dizionario vuoto (r.43) |

- Alla creazione registra due istanti con `time.perf_counter_ns()`: inizio richiesta e checkpoint (r.32-33).
- Gli attributi sono privati (`self.__x`): si leggono e scrivono con `getX`/`setX`. Le sottoclassi dei servizi devono passare dai getter, non dagli attributi.
- `getRequestId`, `getOpCode`, `getRequestStartNs`, `getCheckpointNs` hanno getter; solo il checkpoint ha il setter (`setCheckpointNs`), usato dal logger a ogni riga. `request_id` e `op_code` non hanno setter.
- Non ci sono controlli sui valori né sincronizzazione tra thread.

## AuthInfo

`@dataclass` con cinque campi, tutti `None` di default: `client_id`, `tenant_id`, `company_id`, `user_id`, `user_email`.[^auth] **Non verifica niente**: chi la compila (di solito il middleware del servizio) decide da dove prendere i valori, vedi [flusso](../flussi/ciclo-di-vita-contesto-richiesta.md).

## QaInfo

`@dataclass` con `agent_id`, `session_id`, `datasource_ids` (lista) e `interaction_id`, tutti `None` di default.[^qa] Dal tag 0.8.0 il campo si chiama `datasource_ids`; prima era `datasource_id` (vedi [versioni](../versioni.md)).

## FolliaModule

`StrEnum` con due valori: `VIRTUAL_ASSISTANT = "virtual_assistant"` e `DATA_EXTRACTION = "data_extraction"`.[^module] La docstring dice "Data class", ma è una enumerazione.

[^ctx]: `request_context.py` r.3.
[^state]: `request_state.py`, costruttore r.12-44.
[^auth]: `auth_info.py` r.5-13.
[^qa]: `qa_info.py` r.5-12.
[^module]: `follia_module.py` r.4-8.
62 changes: 62 additions & 0 deletions okf/api/telemetria.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
---
type: API Reference
title: "Telemetria: ZcsTelemetry, setup_logging, set_trace_attributes"
description: "Cosa offre zcs.core.telemetry: inizializzazione con OTLP o Alloy, contatori, strumentazione FastAPI, log verso Loki e attributi delle tracce."
resource: https://github.com/zcsadmin/zcs-python-core/blob/main/app/src/zcs/core/telemetry/zcs_telemetry.py
tags: [telemetria, opentelemetry, prometheus, loki, alloy, grafana]
status: draft
generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z }
sources:
- { id: tel, resource: ../../app/src/zcs/core/telemetry/zcs_telemetry.py, title: "ZcsTelemetry", last_modified: 2026-07-23T09:06:44Z }
- { id: log, resource: ../../app/src/zcs/core/telemetry/logging.py, title: "setup_logging e LokiContextFilter", last_modified: 2026-05-12T08:23:34Z }
- { id: attrs, resource: ../../app/src/zcs/core/telemetry/set_trace_attributes.py, title: "set_trace_attributes", last_modified: 2026-05-12T08:23:34Z }
- { id: sett, resource: ../../app/src/zcs/core/settings/telemetry_settings.py, title: "TelemetrySettings", last_modified: 2026-05-12T08:23:34Z }
- { id: test, resource: ../../app/tests/zcs/core/telemetry/telemetry_test.py, title: "Test della telemetria", last_modified: 2026-07-23T09:06:44Z }
---

# Telemetria (`zcs.core.telemetry`)

Esporta `ZcsTelemetry`, `setup_logging` e `set_trace_attributes`. Le impostazioni stanno in `zcs.core.settings.telemetry_settings` (vedi [configurazione](../operativita/configurazione.md)). Il modulo esiste dal tag 0.11.0.

## ZcsTelemetry

`ZcsTelemetry(telemetry_settings, logger, service_name="zcs-app", service_version="0.0.0", service_environment="undefined")`. Il costruttore chiama subito `_initialize_telemetry`.[^tel]

**Quando si attiva** (r.125-232):

| Condizione | Effetto |
|---|---|
| né OTLP né Alloy configurati | avviso nel log e telemetria **non** inizializzata (r.132) |
| pacchetti `opentelemetry-*` mancanti | avviso e telemetria non inizializzata (r.258-271) |
| OTLP configurato (`has_otlp_config`) | metriche (`/v1/metrics`, esportate a intervallo) e tracce (`/v1/traces`) verso `grafana_otlp_url` con intestazione Basic (r.149-184) |
| Alloy configurato (`has_alloy_config`) | metriche tramite endpoint Prometheus `/metrics` (nessun esportatore OTLP delle metriche), tracce e log verso Alloy in gRPC, con un handler di log aggiunto al logger `root` (r.186-226) |
| entrambi | si attivano tutti e due i rami |

La telemetria risulta attiva (`is_telemetry_enabled()`) se almeno un ramo è partito (r.229-230). `get_meter()` e `get_tracer()` restituiscono `None` e avvisano se non è attiva.

**Metodi**

| Metodo | Cosa fa |
|---|---|
| `instrument_fastapi_app(app)` | strumenta l'app FastAPI con OpenTelemetry e `prometheus_fastapi_instrumentator` ed espone `/metrics` (r.37-57). Non fa nulla se la telemetria non è attiva o se i pacchetti mancano; una stessa app si strumenta una volta sola. |
| `counter_create(name, unit, description, label_names=None)` | crea il contatore su ogni meter OTLP e, con Alloy, un `Counter` Prometheus con nome sicuro (`.` e `-` diventano `_`) e le etichette date (r.74-94) |
| `counter_add(name, data=None)` | incrementa. `data` può essere un dizionario di etichette, con `value` numerico opzionale come quantità (r.96-123) |

Comportamenti d'errore di `counter_add` e `counter_create`: [comportamenti](../comportamenti.md).

## setup_logging

`setup_logging(logging_context: ZcsLogging, app_name, app_version, app_environment)` aggiunge al logger `zcsapp` un handler Loki in coda (`LokiQueueHandler`) **solo se** `has_loki_config`; altrimenti scrive un avviso (r.56-76).[^log] Tag fissi dello stream: `service`, `env`, `version`. Il filtro `LokiContextFilter` aggiunge tag dinamici dal contesto: i campi e le condizioni sono in [comportamenti](../comportamenti.md).

## set_trace_attributes

`set_trace_attributes(request_state=None, *, app_name, app_environment, app_version, extra_attributes)` scrive sullo span corrente gli attributi dell'app e quelli del contesto (`request_op_code`, `request_request_id`, `request_follia_module`, `auth_*`).[^attrs] Non fa nulla se OpenTelemetry non è installato, se lo span non è valido o se il valore è `None`; usa `request_context.get()` se non riceve lo stato. Con contesto assente scrive solo gli attributi dell'app e quelli extra.

## Test

I test esistenti coprono le impostazioni e la creazione di contatori con etichette in modalità Alloy.[^test]

[^tel]: `zcs_telemetry.py`.
[^log]: `telemetry/logging.py`.
[^attrs]: `set_trace_attributes.py` r.17-66.
[^test]: `telemetry_test.py`.
Loading
Loading