From de2cd776eeecac1868085a7bbf2d2411a1484051 Mon Sep 17 00:00:00 2001 From: Giuseppe Ferro Date: Tue, 10 Nov 2026 18:21:19 +0100 Subject: [PATCH] docs: AP-5359 OKF bundle for zcs-python-core Add the OKF bundle (okf/) describing the library as seen by its users: overview, API (session, logger, exceptions, telemetry), behaviors, consumers, version history, configuration, release and open issues. All cards are draft, without verified. Link the bundle from the README. Co-Authored-By: Claude Sonnet 5.5 --- README.md | 4 + okf/.gitignore | 1 + okf/api/eccezioni.md | 39 +++++ okf/api/index.md | 6 + okf/api/logger.md | 38 +++++ okf/api/sessione.md | 60 +++++++ okf/api/telemetria.md | 62 ++++++++ okf/comportamenti.md | 98 ++++++++++++ okf/consumatori.md | 82 ++++++++++ .../ciclo-di-vita-contesto-richiesta.md | 46 ++++++ okf/flussi/index.md | 3 + okf/index.md | 19 +++ okf/libreria.md | 72 +++++++++ okf/operativita/configurazione.md | 53 +++++++ okf/operativita/index.md | 4 + okf/operativita/rilascio.md | 78 +++++++++ okf/questioni-aperte.md | 150 ++++++++++++++++++ okf/versioni.md | 56 +++++++ 18 files changed, 871 insertions(+) create mode 100644 okf/.gitignore create mode 100644 okf/api/eccezioni.md create mode 100644 okf/api/index.md create mode 100644 okf/api/logger.md create mode 100644 okf/api/sessione.md create mode 100644 okf/api/telemetria.md create mode 100644 okf/comportamenti.md create mode 100644 okf/consumatori.md create mode 100644 okf/flussi/ciclo-di-vita-contesto-richiesta.md create mode 100644 okf/flussi/index.md create mode 100644 okf/index.md create mode 100644 okf/libreria.md create mode 100644 okf/operativita/configurazione.md create mode 100644 okf/operativita/index.md create mode 100644 okf/operativita/rilascio.md create mode 100644 okf/questioni-aperte.md create mode 100644 okf/versioni.md diff --git a/README.md b/README.md index bada655..5c1ad98 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/okf/.gitignore b/okf/.gitignore new file mode 100644 index 0000000..5c82184 --- /dev/null +++ b/okf/.gitignore @@ -0,0 +1 @@ +viz.html diff --git a/okf/api/eccezioni.md b/okf/api/eccezioni.md new file mode 100644 index 0000000..984501c --- /dev/null +++ b/okf/api/eccezioni.md @@ -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 ` - - - `. +- 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`. diff --git a/okf/api/index.md b/okf/api/index.md new file mode 100644 index 0000000..45748e4 --- /dev/null +++ b/okf/api/index.md @@ -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 diff --git a/okf/api/logger.md b/okf/api/logger.md new file mode 100644 index 0000000..69572e9 --- /dev/null +++ b/okf/api/logger.md @@ -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 `.[^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. diff --git a/okf/api/sessione.md b/okf/api/sessione.md new file mode 100644 index 0000000..fb15997 --- /dev/null +++ b/okf/api/sessione.md @@ -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 `_` 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. diff --git a/okf/api/telemetria.md b/okf/api/telemetria.md new file mode 100644 index 0000000..d1dcdca --- /dev/null +++ b/okf/api/telemetria.md @@ -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`. diff --git a/okf/comportamenti.md b/okf/comportamenti.md new file mode 100644 index 0000000..b0b1713 --- /dev/null +++ b/okf/comportamenti.md @@ -0,0 +1,98 @@ +--- +type: Behaviors +title: "Comportamenti da conoscere" +description: "Cosa succede davvero quando un servizio usa la libreria: contesto assente, effetti globali del logger, errori dei contatori, campi inviati a Loki, importazioni con effetti." +resource: https://github.com/zcsadmin/zcs-python-core/tree/main/app/src/zcs/core +tags: [comportamenti, logger, contatori, loki, contesto] +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: "Logger e formatter", last_modified: 2026-04-03T07:58:22Z } + - { id: tel, resource: ../app/src/zcs/core/telemetry/zcs_telemetry.py, title: "ZcsTelemetry", last_modified: 2026-07-23T09:06:44Z } + - { id: tlog, resource: ../app/src/zcs/core/telemetry/logging.py, title: "setup_logging e LokiContextFilter", 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: ctx, resource: ../app/src/zcs/core/session/request_context.py, title: "request_context", last_modified: 2025-10-15T08:50:58Z } + - { id: prova, resource: "prova locale in un ambiente temporaneo, 2026-11-10 (prometheus_client 0.25.0)", title: "Prova dei contatori in modalità Alloy, senza modificare la repo" } +--- + +# Comportamenti da conoscere + +Per ogni voce: dove sta nel codice, da quale versione e chi ne è toccato. Le voci con "prova" sono state provate in locale; quelle con "dedotto" no. + +## Contesto della richiesta + +### Contesto assente + +`request_context` ha `default=None`: fuori dal middleware, o nelle rotte che il middleware salta, `request_context.get()` restituisce `None`.[^ctx] + +| Chi legge | Cosa succede con `None` | +|---|---| +| Logger (JSON e console), `LokiContextFilter`, `set_trace_attributes` | gestiscono `None`: omettono i campi del contesto | +| Codice dei servizi che scrive `request_context.get().getAuthInfo()` | `AttributeError`. Caso letto: aip-generative-ai-webservice, `controller/openai_gateway/auth.py:59`. In quella rotta il contesto è sempre impostato: il middleware lo imposta a r.61 per ogni richiesta tranne quelle il cui URL finisce con `/health` o il cui percorso è `/metrics` (`config/api/register_middleware.py:51`), e le rotte `/api/openai/` non sono tra queste. Prima, a r.47, il token è validato con `keycloak_client.get_user_info`. Da verificare: che la rotta non sia mai chiamata fuori dalla richiesta HTTP. | + +Da quale versione: `request_context` dal tag 0.4.0. Servizi toccati: tutti quelli di [consumatori](consumatori.md) che leggono il contesto. + +### Thread e contesto + +Un thread creato da un consumer parte con un contesto vuoto, salvo copia esplicita del contesto: è il comportamento standard di `contextvars` (dedotto). Nei consumer che usano thread non è stato verificato (da verificare). + +### Il logger aggiorna il checkpoint + +A ogni riga di log con contesto presente, il logger chiama `setCheckpointNs` (`logger.py:65`, `logger.py:108`): il tempo "delta" è sempre relativo all'ultimo log, di qualunque componente.[^logger] Il contesto è modificato da chi scrive il log, non solo letto. + +## Logger (`ZcsLogging`) + +| Comportamento | Dove | Da quale tag | Note | +|---|---|---|---| +| **La `LogRecordFactory` si sostituisce all'import** del modulo `zcs.core.logger`: `logging.setLogRecordFactory(record_factory)` a livello di modulo | `logger.py:9`, `logger.py:32` | 0.2.0 | Vale per tutti i logger del processo, anche senza creare `ZcsLogging`. La factory aggiunge `error_code` e `original_exception` a ogni record. | +| **Il costruttore sostituisce i gestori degli altri logger**: per ogni logger già registrato imposta il livello e, se ha già almeno un handler, lo rimpiazza con quello nuovo | `logger.py:132-137` | da verificare | I logger senza handler restano senza. Va creato dopo che gli altri hanno configurato i propri. | +| `logging.basicConfig(level, handlers=[...])` sul root | `logger.py:146-149` | da verificare | Non ha effetto se il root ha già degli handler (comportamento standard di `basicConfig`, dedotto). | +| **`delta_ns` e `total_ns` sono in secondi**, non in nanosecondi: il valore è diviso per `1e9` | `logger.py:68-69` (JSON) | 0.4.0 | Il nome è fuorviante. Nel formato console i tempi sono "s" (`logger.py:109-110`). | +| **Con un'eccezione allegata, `message` diventa il testo dell'eccezione**, non il messaggio del log | `logger.py:39-40` | 0.2.0 | Succede se `exc_info` è presente e il record contiene un'eccezione. Il messaggio originale non compare nel JSON; resta il testo dell'eccezione e il traceback. | +| **`ConsoleCustomFormatter.format` modifica `record.msg`**: ci aggiunge il prefisso `[OP_CODE:..][REQ_ID:..]` e il suffisso dei tempi | `logger.py:109-110` | 0.4.0 | Il record modificato è lo stesso passato agli altri handler: con più handler sullo stesso record il prefisso si ripete (dedotto). | +| Il tipo di `log_level` è annotato `str` ma il valore predefinito è `logging.INFO` (intero) | `logger.py:117` | da verificare | Il codice usa il valore così com'è, quindi accetta sia interi sia nomi dei livelli. | +| `EndpointFilter` ha come predefinito una lista mutabile e cerca `GET ` nel messaggio | `endpoint_filter.py:11`, `endpoint_filter.py:23` | 0.3.0 | Non filtra metodi diversi da GET. | + +## Contatori (`ZcsTelemetry`) + +Provati in locale con `prometheus_client` 0.25.0 (la versione di `requirements.txt`), modalità solo Alloy (nessun meter OTLP), senza modificare la repo.[^prova] + +`counter_add` non ha nessun `try/except` (`zcs_telemetry.py:96-123`): il ramo Prometheus chiama `labels(**attributes).inc(amount)` (r.121) o `inc(amount)` (r.123) e ogni errore sale al chiamante.[^tel] + +| Chiamata | Esito | +|---|---| +| etichette dichiarate in `counter_create`, tutte presenti | nessuna eccezione | +| etichetta **non dichiarata** (`{"b": ...}` su un contatore con `["a"]`) | `ValueError: Incorrect label names` | +| contatore con etichette, `counter_add(nome)` senza dati (o con `{}`) | `ValueError: counter metric is missing label values` | +| contatore **senza** etichette, `counter_add(nome, {"a": ...})` | `ValueError: No label names were set when constructing counter` | +| contatore senza etichette, senza dati | nessuna eccezione | +| `{"value": 3, "a": "y"}` | nessuna eccezione: `value` è la quantità, il resto sono etichette | + +- Se sono attivi **anche** i meter OTLP, il ramo OTLP incrementa prima (r.112-113): quando il ramo Prometheus fallisce, l'incremento OTLP è già avvenuto. +- Con **solo OTLP** non ci sono contatori Prometheus e le etichette non dichiarate non sollevano errori. +- **Registrazione doppia**: `counter_create` con lo stesso nome una seconda volta, sulla stessa istanza o su un'altra, solleva `ValueError: Duplicated timeseries in CollectorRegistry` (provato). Il costruttore del contatore Prometheus (r.92) è protetto solo da `except ImportError`. Anche `a.b` e `a-b` collidono, perché diventano `a_b` (r.91). Con solo OTLP non si verifica. +- `counter_create` non fa nulla, con un avviso, se la telemetria non è attiva o se non c'è nessun meter e nemmeno Alloy (r.75-82); `counter_add` su un contatore mai creato avvisa e ritorna (r.114-116). + +Da quale versione: `label_names` dal tag 0.11.3, vedi [versioni](versioni.md). Servizi toccati: aip-whatsapp-service (contatori con etichette, 0.11.3); letto il 10/11/2026: le etichette che passa coincidono con quelle dichiarate. Gli altri consumatori della telemetria non chiamano `counter_create` né `counter_add` ([questioni aperte](questioni-aperte.md)). + +## Telemetria e Loki + +- L'inizializzazione non solleva eccezioni se manca la configurazione o mancano i pacchetti: scrive un avviso e `is_telemetry_enabled()` resta `False` (`zcs_telemetry.py:132`, `:258-271`). Un servizio può quindi partire senza telemetria senza accorgersene, salvo leggere i log. +- **Campi inviati a Loki.** `LokiContextFilter` è aggiunto solo all'handler Loki, che esiste solo con `grafana_loki_url` e `grafana_cloud_api_key` valorizzati (`telemetry/logging.py:56`, `:72`).[^tlog] Se nel contesto c'è un `RequestState` con `op_code`, il filtro imposta i tag dinamici `request_op_code`, `request_request_id`, `request_follia_module`, `auth_client_id`, `auth_tenant_id`, `auth_company_id`, `auth_user_id` e **`auth_user_mail`** (r.28-38); i campi di `AuthInfo` sono `None` se `AuthInfo` non è impostata. Se c'è uno span valido, aggiunge `trace_id` e `span_id` (r.41-46). +- Il filtro non rimuove nulla: se `user_email` è valorizzato in `AuthInfo`, finisce nei tag. Se i tag diventino etichette dello stream di Loki dipende dalla libreria `logging_loki`, che non è nel repo (da verificare). Vedi [questioni aperte](questioni-aperte.md). + +## Importazioni con effetti + +- `zcs.core.settings.telemetry_settings` crea `telemetry_settings = TelemetrySettings()` all'import (r.36): chi importa `zcs.core.telemetry` o `ZcsTelemetry` legge subito le variabili d'ambiente e il file `settings/telemetry-settings.env`.[^sett] +- `zcs.core.logger` sostituisce la factory dei record (vedi sopra). + +## Rischio di rilascio: tante versioni diverse in produzione + +I servizi in produzione usano **nove** versioni diverse di core, da 0.2.0 a 0.11.4 (lettura del 10/11/2026, vedi [consumatori](consumatori.md)). Un fix della libreria non raggiunge un servizio finché quel servizio non cambia la dipendenza e viene rilasciato; ciò che vale in una sezione di questa scheda dipende dalla versione richiesta dal servizio. Per ogni tag, cosa contiene: [versioni](versioni.md). + +[^ctx]: `request_context.py` r.3. +[^logger]: `logger.py`. +[^tel]: `zcs_telemetry.py`. +[^tlog]: `telemetry/logging.py`. +[^sett]: `telemetry_settings.py` r.4-36. +[^prova]: Script temporaneo, eseguito fuori dalla repo. Esito riportato nella tabella. diff --git a/okf/consumatori.md b/okf/consumatori.md new file mode 100644 index 0000000..64e8a11 --- /dev/null +++ b/okf/consumatori.md @@ -0,0 +1,82 @@ +--- +type: Consumers +title: "Chi usa zcs-python-core" +description: "Servizi e librerie che dipendono da zcs-python-core: versione richiesta su main, versione richiesta al tag in produzione, versione del servizio in app_versions e moduli importati." +resource: https://github.com/zcsadmin/zcs-python-core/blob/main/okf/consumatori.md +tags: [consumatori, versioni, produzione, app-versions] +status: draft +generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +sources: + - { id: lettura, resource: "git grep su origin/main di tutte le repo di Follia_SW e git show dai tag, 2026-11-10", title: "Lettura delle dipendenze dei consumatori" } + - { id: tfvars, resource: "app/follia.ai/terraform/terraform.tfvars di ml-follia-tesseract (origin/main 30bdc2f, file modificato il 2026-11-05)", title: "Mappa app_versions, letta il 2026-11-10" } + - { id: maintf, resource: "app/follia.ai/terraform/40_aiplatform/main.tf di ml-follia-tesseract, righe 326-333 e 349-364", title: "Modulo aip-avconsumer commentato" } + - { id: revisione-gferro, resource: "revisione del bundle, 2026-11-10", title: "Indicazioni di G. Ferro", author: "human:gferro" } +--- + +# Chi usa zcs-python-core + +Lettura del **10/11/2026**: `git grep` su `origin/main` di ogni repo di `Follia_SW`, repo per repo; versioni al tag con `git show `; mappa `app_versions` da `terraform.tfvars` di ml-follia-tesseract (`origin/main` al commit `30bdc2f`, file modificato per l'ultima volta il 05/11/2026).[^lettura][^tfvars] Le colonne "core su main" e "core al tag" sono la riga `zcs-python-core==...` nei requisiti del consumatore. + +## Servizi in produzione + +| Repo | Chiave in `app_versions` | Tag in prod | core su main | core al tag in prod | Cosa importa | +|---|---|---|---|---|---| +| aip-generative-ai-webservice | `genai` | 6.10.2 | 0.11.0 | 0.11.0 | session (`request_context` ovunque, `RequestState`, `AuthInfo`, `FolliaModule`, `QaInfo`), logger (`ZcsLogging`, `EndpointFilter`), `ZcsException`, `ZcsTelemetry` | +| aip-document-manager-webservice | `docmanager` | 2.16.3 | 0.11.4 | 0.11.4 | session (`request_context`, `RequestState`, `AuthInfo`, `FolliaModule`), `ZcsLogging`, `ZcsException` | +| aip-whatsapp-service | `whatsapp` | 0.9.3 | 0.11.3 | 0.11.3 | session, `ZcsLogging`, `ZcsException`, telemetria (`setup_logging`, `set_trace_attributes`, `ZcsTelemetry`, contatori con `label_names`) | +| aip-statistics-webservice | `statistics` | 0.10.0 | 0.11.0 | 0.11.0 | session, `FolliaModule`, `ZcsLogging`, `EndpointFilter`, `ZcsException`, telemetria | +| aip-data-ingestor-webservice | `ingestor` | 3.2.2 | 0.11.1 | 0.11.1 | session, `ZcsLogging`, `EndpointFilter`, `ZcsException` | +| aip-data-extraction-consumer | `dextraction` | 3.0.0 | 0.11.1 | 0.11.1 | session, `ZcsLogging`, `ZcsException` | +| aip-document-assistance-consumer | `docassistance` | 2.3.0 | 0.11.1 | 0.11.1 | session, `ZcsLogging`, `EndpointFilter`, `ZcsException` | +| aip-mcp-follia-server | `mcp_follia` | 0.2.0 | 0.11.0 | 0.11.0 | session, `ZcsLogging`, `EndpointFilter`, `ZcsException`, telemetria (`setup_logging`, `ZcsTelemetry`) | +| aip-mcp-cassiopea-server | `mcp_cassiopea` | 0.1.0 | 0.11.0 | 0.11.0 | session, `ZcsLogging`, `EndpointFilter`, telemetria (`setup_logging`, `ZcsTelemetry`) | +| aip-mcp-teseo-server | `mcp_teseo` | 0.13.0 | 0.10.1 | 0.10.1 | session, `ZcsLogging`, `EndpointFilter`, `ZcsException` | +| aip-file-storage-service | `file_storage` | 2.4.0 | 0.10.1 | 0.10.1 | session (`request_context`, `RequestState`, `AuthInfo`), `ZcsLogging`, `ZcsException` | +| aip-data-scraper-consumer | `scraper` | 2.2.1 | 0.10.2 | 0.10.2 | `ZcsLogging`, `ZcsException` | +| aip-erp-ai-webservice | `erpai` | 0.7.0 | 0.4.1 | 0.4.1 | `ZcsLogging`, `EndpointFilter`, `ZcsException` | +| aip-data-storage-consumer | `dsconsumer` | 2.10.0 | 0.3.0 | 0.3.0 | `ZcsLogging`, `EndpointFilter`, `ZcsException` | +| aip-audio-service | `audio_service` | 0.2.2 | 0.2.0 | 0.2.0 | `ZcsLogging` | + +**Nove versioni diverse di core in produzione**, da 0.2.0 a 0.11.4: 0.2.0, 0.3.0, 0.4.1, 0.10.1, 0.10.2, 0.11.0, 0.11.1, 0.11.3, 0.11.4. Rischio di rilascio: vedi [comportamenti](comportamenti.md) e [questioni aperte](questioni-aperte.md). + +## Servizi non in produzione + +| Repo | Stato | core su main | core al tag | +|---|---|---|---| +| aip-audio-video-consumer | **Non in produzione**: il modulo `aip-avconsumer` è commentato in `40_aiplatform/main.tf` (r.349-364); la chiave `avconsumer = "1.4.3"` è ancora in `app_versions`.[^maintf][^revisione-gferro] | 0.11.1 | 0.2.0 (tag 1.4.3) | +| aip-xml-invoice-consumer | **Non in produzione**: il modulo `aip-xmlconsumer` è commentato in `40_aiplatform/main.tf` (r.326-333); la chiave `xmlconsumer = "1.8.0"` è ancora in `app_versions`. Letto anche nelle schede di aip-follia-knowledge (verifica con `gcloud` del 9/11/2026). | 0.2.0 | 0.2.0 (tag 1.8.0) | +| aip-follia-voip | **Non è in `app_versions`**. Il suo `main` richiede `0.11.0-rc1` (una rc, non una versione stabile). | 0.11.0-rc1 | 0.11.0 (tag 0.0.1) | + +I servizi non in produzione sono elencati perché importano la libreria, non perché i loro tag siano rilasciati. + +## Altre librerie + +Non hanno una versione in `app_versions` (sono pacchetti, non servizi). + +| Libreria | core su main | core all'ultimo tag | Cosa importa | +|---|---|---|---| +| zcs-python-genai | 0.10.2 | 0.10.2 (6.19.1) | `ZcsLogging`, `request_context`, `RequestState` | +| zcs-python-service-connectors | 0.10.2 | 0.10.2 (7.4.1) | `ZcsLogging`, `request_context`, `RequestState` | +| zcs-python-stats | 0.7.2 | 0.7.2 (1.4.1) | `FolliaModule` | +| zcs-python-auth | 0.10.1 | 0.10.1 (3.1.0) | `ZcsException` | +| zcs-python-agents | 0.2.0 | 0.2.0 (0.1.1) | solo il logger (commento nel file dei requisiti) | + +Il tag `0.7.2` richiesto da zcs-python-stats non esiste nella repo di core (tag `0.7.0`, `0.7.1`, `0.8.0`): vedi [questioni aperte](questioni-aperte.md). + +## La nominano soltanto, senza importarla + +| Repo | Dove | +|---|---| +| ml-sopdu-scripts | script del radar delle librerie e relativo storico | +| aip-follia-knowledge | schede `okf/librerie/` di zcs-python-genai, zcs-python-service-connectors e zcs-python-stats | +| aip-audio-service, aip-audio-video-consumer, aip-data-scraper-consumer, aip-follia-voip, aip-mcp-follia-server, aip-statistics-webservice, aip-generative-ai-webservice | testi dei propri bundle OKF o documenti (versione di core, esempi, diagnostica) | +| aip-mcp-teseo-server | `docs/CROSS_TENANT_RACE_FIX_VIA_REQUEST_STATE.md`: progetto di correzione che usa `RequestState` e `request_context`; è un documento di progetto | + +## Non la usano (nessuna occorrenza su `origin/main`) + +aip-config-api, aip-agents-api, aip-conversational-middleware, agent-chat-server, aip-frontend, aip-auth-server, zcs-python-ms-connectors, aip-data-models-lib. + +[^lettura]: Lettura del 10/11/2026. +[^tfvars]: `terraform.tfvars`, mappa `app_versions`. +[^maintf]: `40_aiplatform/main.tf` r.349-364. +[^revisione-gferro]: Indicazione di G. Ferro del 10/11/2026: aip-audio-video-consumer non è in produzione; aip-follia-voip non è in `app_versions`. diff --git a/okf/flussi/ciclo-di-vita-contesto-richiesta.md b/okf/flussi/ciclo-di-vita-contesto-richiesta.md new file mode 100644 index 0000000..ae3d5bb --- /dev/null +++ b/okf/flussi/ciclo-di-vita-contesto-richiesta.md @@ -0,0 +1,46 @@ +--- +type: Process +title: "Ciclo di vita del contesto della richiesta" +description: "Come il contesto (RequestState in request_context) nasce, viene compilato e letto dal logger e dalla telemetria: cosa fa la libreria e cosa fa ogni servizio." +resource: https://github.com/zcsadmin/zcs-python-core/blob/main/app/src/zcs/core/session/request_context.py +tags: [contesto, request-state, middleware, tracciamento] +status: draft +generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +sources: + - { id: ctx, resource: ../../app/src/zcs/core/session/request_context.py, title: "request_context", last_modified: 2025-10-15T08:50:58Z } + - { id: state, resource: ../../app/src/zcs/core/session/request_state.py, title: "RequestState", last_modified: 2026-05-13T15:29:36Z } + - { id: logger, resource: ../../app/src/zcs/core/logger/logger.py, title: "Lettura del contesto nel logger", last_modified: 2026-04-03T07:58:22Z } + - { id: tlog, resource: ../../app/src/zcs/core/telemetry/logging.py, title: "Lettura del contesto per Loki", last_modified: 2026-05-12T08:23:34Z } + - { id: attrs, resource: ../../app/src/zcs/core/telemetry/set_trace_attributes.py, title: "Lettura del contesto per le tracce", last_modified: 2026-05-12T08:23:34Z } +--- + +# Ciclo di vita del contesto della richiesta + +La libreria **definisce** il contenitore del contesto ma **non lo imposta mai**: nessuna funzione di `zcs.core` chiama `request_context.set`. Lo fanno i servizi, nello stesso modo.[^ctx] Lo schema qui sotto è quello letto nel middleware di aip-data-ingestor-webservice e di aip-generative-ai-webservice (origin/main del 10/11/2026); gli altri consumatori sono in [consumatori](../consumatori.md) e non sono stati letti riga per riga. + +## Passi + +| # | Chi | Cosa | +|---|---|---| +| 1 | servizio (middleware HTTP o consumer di messaggi) | crea `RequestState(op_code=..., prefix='')`. L'`op_code` può arrivare dalla query (`op_code`) oppure viene generato. | +| 2 | servizio | `request_context.set(request_state)` | +| 3 | servizio | decodifica il JWT dell'intestazione `Authorization`, compila `AuthInfo` (`tenant_id`, `user_id`, `client_id`, e dove serve `company_id`), `setAuthInfo`, `setFolliaModule`, `setCustomData` | +| 4 | servizio | chiama `set_trace_attributes(request_state)` per copiare il contesto sullo span | +| 5 | libreria (logger) | a ogni log legge `request_context.get()`, aggiunge `op_code`, `request_id`, tempo dall'ultimo log e dall'inizio, e **aggiorna il checkpoint**[^logger] | +| 6 | libreria (telemetria) | `LokiContextFilter` legge il contesto per i tag Loki, `set_trace_attributes` per gli attributi della traccia[^tlog][^attrs] | +| 7 | servizio | a fine richiesta calcola il tempo totale da `getRequestStartNs()` | + +## Cosa non c'è + +- **Nessun `reset`**: nei middleware letti il `set` non è seguito da un `request_context.reset(token)`. +- **Richieste che saltano il contesto**: i middleware letti non impostano il contesto per `/health` e `/metrics`. Chi legge `request_context.get()` in quelle rotte riceve `None`. +- **Thread**: un thread nuovo parte con un contesto vuoto, a meno che chi lo crea non copi il contesto. Nei consumer che creano thread non è stato verificato (da verificare). + +## Dove cambia da servizio a servizio + +Alcuni servizi usano `RequestState` direttamente, altri una sottoclasse (`AppCustomRequestState`, `TeseoMcpRequestState`) con campi propri. I campi aggiuntivi non sono noti alla libreria. + +[^ctx]: `request_context.py`: solo la definizione del `ContextVar`. +[^logger]: `logger.py` r.60-69 e r.103-110. +[^tlog]: `telemetry/logging.py` r.25-48. +[^attrs]: `set_trace_attributes.py` r.46-66. diff --git a/okf/flussi/index.md b/okf/flussi/index.md new file mode 100644 index 0000000..6165eab --- /dev/null +++ b/okf/flussi/index.md @@ -0,0 +1,3 @@ +# Flussi + +* [Ciclo di vita del contesto della richiesta](ciclo-di-vita-contesto-richiesta.md) - chi crea, compila e legge il contesto diff --git a/okf/index.md b/okf/index.md new file mode 100644 index 0000000..a1d59fe --- /dev/null +++ b/okf/index.md @@ -0,0 +1,19 @@ +--- +okf_version: "0.2" +--- + +# Bundle OKF di zcs-python-core + +Schede che descrivono la libreria Python `zcs-python-core` vista da chi la usa: cosa offre, come si comporta, chi la usa e come si rilascia. Ogni scheda ha `status: draft` finché una persona non la verifica (`status: stable` con `verified`). + +* [Panoramica della libreria](libreria.md) - cosa offre, installazione, dipendenze e dove guardare +* [Comportamenti da conoscere](comportamenti.md) - contesto assente, effetti globali del logger, errori dei contatori, campi inviati a Loki +* [Chi usa la libreria](consumatori.md) - servizi e librerie, versioni richieste e in produzione +* [Storia delle versioni](versioni.md) - tag dal 2025 e modifiche non retrocompatibili +* [Questioni aperte](questioni-aperte.md) - problemi noti con priorità + +## Sezioni + +* [API](api/index.md) - sessione, logger, eccezioni, telemetria +* [Flussi](flussi/index.md) - ciclo di vita del contesto della richiesta +* [Operatività](operativita/index.md) - configurazione e rilascio diff --git a/okf/libreria.md b/okf/libreria.md new file mode 100644 index 0000000..3a123ec --- /dev/null +++ b/okf/libreria.md @@ -0,0 +1,72 @@ +--- +type: Library +title: "zcs-python-core: panoramica" +description: "Libreria Python di base per i servizi Follia: contesto della richiesta, logger, eccezioni e telemetria; come si installa, dove si pubblica e cosa non dichiara." +resource: https://github.com/zcsadmin/zcs-python-core/blob/main/README.md +tags: [libreria, python, core, contesto-richiesta, logger, telemetria] +esposizione: libreria +status: draft +generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +sources: + - { id: readme, resource: ../README.md, title: "README della repo", last_modified: 2025-06-27T08:46:03Z } + - { id: pyproject, resource: ../app/pyproject.toml, title: "Metadati del pacchetto", last_modified: 2025-10-15T08:50:58Z } + - { id: req, resource: ../app/requirements.txt, title: "Requisiti di sviluppo e dipendenze usate", last_modified: 2026-07-23T09:06:44Z } + - { id: publish, resource: ../.github/workflows/publish-tag.yaml, title: "Pubblicazione del pacchetto sul tag", last_modified: 2026-07-23T09:21:16Z } + - { id: telemetria, resource: ../app/src/zcs/core/telemetry/zcs_telemetry.py, title: "ZcsTelemetry", last_modified: 2026-07-23T09:06:44Z } +--- + +# zcs-python-core + +`zcs-python-core` è la libreria Python di base dei servizi Follia. Non gira da sola: i servizi la importano (`zcs.core.*`) per quattro cose. + +| Cosa offre | Modulo | Scheda | +|---|---|---| +| Contesto della richiesta (`RequestState`, `request_context`, `AuthInfo`, `QaInfo`, `FolliaModule`) | `zcs.core.session` | [sessione](api/sessione.md) | +| Logger con formato JSON per Cloud Logging o formato console, filtro per gli endpoint di servizio | `zcs.core.logger` | [logger](api/logger.md) | +| Eccezione applicativa `ZcsException` | `zcs.core.exception` | [eccezioni](api/eccezioni.md) | +| Telemetria (tracce, metriche, log verso Grafana o Alloy) | `zcs.core.telemetry`, `zcs.core.settings` | [telemetria](api/telemetria.md) | + +Il bundle descrive la libreria **vista da chi la usa**. I servizi che la importano sono elencati in [consumatori](consumatori.md), ma come sono fatti dentro sta nei loro bundle. + +## Esposizione + +`esposizione: libreria`. Non ha API per i clienti né guida in `docs/integrazione.md`. L'ha scelta chi verifica insieme alla struttura del bundle (conferma in chat del 10/11/2026). + +## Installazione + +- Il pacchetto si chiama `zcs-python-core` e si pubblica su Artifact Registry (`python`, europe-west1, progetto `ai-accounting-405809`) quando si spinge un tag.[^publish] +- Nel `requirements.txt` del consumatore serve la riga `--extra-index-url https://europe-west1-python.pkg.dev/ai-accounting-405809/python/simple/` e poi `zcs-python-core==`.[^readme] +- Il formato dei tag è `X.Y.Z` senza `v`, con rc `X.Y.Z-rcN`. Il workflow scrive il nome del tag nel campo `version` di `pyproject.toml` (che nel repo resta `0.dev0`) prima di costruire la wheel.[^publish][^pyproject] + +## Dipendenze + +- `pyproject.toml` non ha la sezione `dependencies`: installare il pacchetto **non porta nessuna libreria di terze parti**.[^pyproject] +- `app/requirements.txt` elenca `build`, `pytest`, `pydantic_settings` e `prometheus_client`, ma è il file dell'immagine di sviluppo e di prova, non è letto da chi installa il pacchetto.[^req] +- Cosa serve a chi usa ogni modulo: + +| Modulo | Serve al consumatore | Come si vede nel codice | +|---|---|---| +| `session`, `exception`, `logger` | niente di terzo | usano solo la libreria standard | +| `settings`, `telemetry` | `pydantic_settings` | `TelemetrySettings` è importata e istanziata all'import | +| `telemetry` (metriche, tracce, log OTLP) | pacchetti `opentelemetry-*` | importati solo dentro `ZcsTelemetry`, con `except ImportError` che disattiva la telemetria e scrive un avviso[^telemetria] | +| `telemetry` (contatori in modalità Alloy) | `prometheus_client` | import protetto da `except ImportError` | +| `telemetry.setup_logging` con Loki | `logging_loki` | **import non protetto**, vedi [questioni aperte](questioni-aperte.md) | + +Il README dice che la libreria "non richiede direttamente dipendenze di terze parti": è vero per `session`, `exception` e `logger`, non per la telemetria (vedi [questioni aperte](questioni-aperte.md)). + +## Dove guardare + +| Cerchi | Vai a | +|---|---| +| Come si imposta e si legge il contesto della richiesta | [flusso del contesto](flussi/ciclo-di-vita-contesto-richiesta.md), [sessione](api/sessione.md) | +| Cosa succede in errore, con contesto assente, valori predefiniti | [comportamenti](comportamenti.md) | +| Chi la usa e con quale versione | [consumatori](consumatori.md) | +| Cosa è cambiato in ogni tag | [versioni](versioni.md) | +| Variabili d'ambiente | [configurazione](operativita/configurazione.md) | +| Come si pubblica e si prova | [rilascio](operativita/rilascio.md) | +| Problemi noti | [questioni aperte](questioni-aperte.md) | + +[^publish]: Workflow `publish-tag.yaml`: carica la wheel con `twine` su Artifact Registry. +[^readme]: README, sezione "Usage". +[^pyproject]: `pyproject.toml`: nome, `version = "0.dev0"` e nessuna sezione `dependencies`. +[^telemetria]: `ZcsTelemetry._import_telemetry_modules` (r.258-271): in caso di `ImportError` torna `None` e la telemetria non si inizializza. diff --git a/okf/operativita/configurazione.md b/okf/operativita/configurazione.md new file mode 100644 index 0000000..2577327 --- /dev/null +++ b/okf/operativita/configurazione.md @@ -0,0 +1,53 @@ +--- +type: Configuration +title: "Configurazione della telemetria" +description: "Variabili d'ambiente di TelemetrySettings (solo nomi e predefiniti), file letto, campi non usati; il resto della libreria non legge variabili." +resource: https://github.com/zcsadmin/zcs-python-core/blob/main/app/src/zcs/core/settings/telemetry_settings.py +tags: [configurazione, telemetria, variabili-ambiente] +status: draft +generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +sources: + - { id: sett, resource: ../../app/src/zcs/core/settings/telemetry_settings.py, title: "TelemetrySettings", last_modified: 2026-05-12T08:23:34Z } + - { id: tel, resource: ../../app/src/zcs/core/telemetry/zcs_telemetry.py, title: "Uso delle impostazioni", last_modified: 2026-07-23T09:06:44Z } +--- + +# Configurazione + +L'unico punto in cui la libreria legge configurazione è `TelemetrySettings` (`pydantic_settings.BaseSettings`).[^sett] Nel codice non ci sono letture di `os.environ` o `getenv`. `ZcsLogging` e `ZcsTelemetry` ricevono i loro parametri dal chiamante, non dall'ambiente. Qui solo **nomi e predefiniti**, mai valori. + +## Come si legge + +- Le variabili si chiamano come i campi, senza distinzione tra maiuscole e minuscole (comportamento standard di `pydantic_settings`, dedotto): per esempio `GRAFANA_LOKI_URL`. +- In più legge il file **`settings/telemetry-settings.env`**, con percorso **relativo alla cartella da cui parte il processo** (`env_file`, r.6); i campi sconosciuti sono ignorati (`extra='ignore'`). +- `telemetry_settings = TelemetrySettings()` è creata all'**import** del modulo (r.36): il file e le variabili si leggono una volta sola, all'avvio. + +## Campi + +| Campo | Predefinito | A cosa serve | Dove è usato | +|---|---|---|---| +| `grafana_loki_url` | vuoto | indirizzo di Loki; se manca niente handler Loki | `has_loki_config`, `setup_logging` | +| `grafana_loki_instance_id` | vuoto | utente dell'autenticazione verso Loki | `setup_logging` | +| `grafana_otlp_url` | vuoto | base degli indirizzi OTLP (`/v1/metrics`, `/v1/traces`) | `has_otlp_config`, `ZcsTelemetry` | +| `grafana_otlp_instance_id` | vuoto | utente dell'intestazione Basic verso OTLP | `ZcsTelemetry._build_basic_auth_header` | +| `grafana_cloud_api_key` | vuoto | credenziale di Grafana Cloud, usata per OTLP e Loki (segreto) | `has_otlp_config`, `has_loki_config`, autenticazione | +| `metrics_export_interval_millis` | `60000` | intervallo di esportazione delle metriche OTLP | `ZcsTelemetry` r.159 | +| `alloy_host` | vuoto | host di Alloy | `has_alloy_config`, indirizzo gRPC di tracce e log | +| `alloy_insecure` | `False` | connessione gRPC senza TLS | esportatori verso Alloy | +| `alloy_port` | `4317` | porta gRPC di Alloy | `has_alloy_config`, indirizzo gRPC | +| `alloy_metrics_port` | `4318` | **non usato**: letto solo da `_build_alloy_metrics_endpoint`, che nessuno chiama | — | + +## Condizioni derivate + +| Proprietà | Vera quando | +|---|---| +| `has_otlp_config` | `grafana_otlp_url` e `grafana_cloud_api_key` valorizzati | +| `has_loki_config` | `grafana_loki_url` e `grafana_cloud_api_key` valorizzati | +| `has_alloy_config` | `alloy_host` e `alloy_port` valorizzati (con `alloy_port` predefinito 4317, basta `alloy_host`) | + +La telemetria si attiva se è vera `has_otlp_config` o `has_alloy_config` (vedi [telemetria](../api/telemetria.md)). + +## Non configurabile da ambiente + +Livello dei log, modo cloud o console e filtri degli endpoint sono parametri dei costruttori ([logger](../api/logger.md)); nome, versione e ambiente del servizio per la telemetria sono parametri di `ZcsTelemetry` e di `setup_logging`. + +[^sett]: `telemetry_settings.py` r.4-36. diff --git a/okf/operativita/index.md b/okf/operativita/index.md new file mode 100644 index 0000000..ac4caa3 --- /dev/null +++ b/okf/operativita/index.md @@ -0,0 +1,4 @@ +# Operatività + +* [Configurazione della telemetria](configurazione.md) - variabili d'ambiente di TelemetrySettings +* [Rilascio e prove in locale](rilascio.md) - workflow, tag, pre-release, run.sh diff --git a/okf/operativita/rilascio.md b/okf/operativita/rilascio.md new file mode 100644 index 0000000..52bc6ab --- /dev/null +++ b/okf/operativita/rilascio.md @@ -0,0 +1,78 @@ +--- +type: Deployment +title: "Rilascio e prove in locale" +description: "Come si pubblica zcs-python-core: workflow della PR e del tag, cosa non parte con un push su main, stato pre-release delle release lette, bug dell'identificativo, prove in locale." +resource: https://github.com/zcsadmin/zcs-python-core/blob/main/.github/workflows/publish-tag.yaml +tags: [rilascio, workflow, artifact-registry, tag, test] +status: draft +generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +sources: + - { id: publish, resource: ../../.github/workflows/publish-tag.yaml, title: "Pubblicazione sul tag", last_modified: 2026-07-23T09:21:16Z } + - { id: pr, resource: ../../.github/workflows/pr_build-and-test.yaml, title: "Build e test sulle PR", last_modified: 2026-07-23T09:06:44Z } + - { id: docker, resource: ../../.build/dockerfiles/Dockerfile, title: "Immagini dev e dist", last_modified: 2026-07-23T09:06:44Z } + - { id: run, resource: ../../run.sh, title: "Script di sviluppo", last_modified: 2024-11-21T15:07:01Z } + - { id: local, resource: ../../docs/LOCAL_DEVELOPMENT.md, title: "Sviluppo locale", last_modified: 2025-06-27T08:46:03Z } + - { id: rel, resource: "gh release list e gh api .../releases/tags/, 2026-11-10", title: "Stato pre-release delle release" } +--- + +# Rilascio + +## Workflow + +| Workflow | Quando parte | Cosa fa | +|---|---|---| +| `pr_build-and-test.yaml` | PR verso `main` | costruisce l'immagine `dist` e lancia `pytest` al suo interno.[^pr] Nessun filtro sui percorsi: parte anche per PR di sola documentazione. | +| `publish-tag.yaml` | push di qualunque tag (`'*'`) | autentica su Google Cloud, scrive il nome del tag in `pyproject.toml`, costruisce la wheel, la carica su Artifact Registry (repository `python`, europe-west1) con `twine`, poi crea la release GitHub con note generate.[^publish] | + +- **Un push su `main` non lancia nessun workflow**: non costruisce, non pubblica, non fa deploy. Non esiste `paths-ignore` e non serve, perché non c'è un trigger `push` su branch. Un push di sola documentazione non ripubblica nulla. +- **Un tag pubblica sempre**: anche una rc (`X.Y.Z-rcN`) viene caricata nel registro, perché il filtro è `'*'`. +- Non esistono ambienti sandbox, develop o produzione per la libreria: i servizi la scelgono con la riga `zcs-python-core==` nei propri requisiti. + +## Formato dei tag + +`X.Y.Z` senza `v`; le rc sono `X.Y.Z-rcN`. Vedi [versioni](../versioni.md). + +## Stato pre-release delle release GitHub + +Lettura del 10/11/2026 con `gh release list` e `gh api`:[^rel] + +| Release | `prerelease` | +|---|---| +| 0.11.4 | **no** (è la "Latest") | +| 0.11.3 | sì | +| 0.11.2 | sì | +| 0.11.2-rc2, 0.11.2-rc1 | sì | +| 0.11.1 | sì | +| 0.11.0, 0.11.0-rc1 | sì | +| 0.10.2, 0.10.2-rc2 | sì | +| 0.10.1 e precedenti (fino a 0.7.1) | no | + +### Identificativo dello step: r.64 contro r.77 + +Nel workflow `publish-tag.yaml` lo step ha `id: check-prerelease` (r.64, con il trattino), ma la release legge `steps.check_prerelease.outputs.prerelease` (r.77, con il trattino basso).[^publish] I due nomi sono diversi. + +- **Letto**: `0.11.4` è il primo tag costruito con questo workflow (commit `8d0cda4`) e la sua release **non** è marcata pre-release. +- **Dedotto**: l'uscita `prerelease` è vuota perché lo step non si chiama come scritto a r.77; la release risulta quindi "non pre-release" qualunque sia il nome del tag. +- **Letto (file ai tag)**: ai tag `0.11.2-rc1`, `0.11.2-rc2`, `0.11.2` e `0.11.3` il workflow aveva `id: check_prerelease` (corretto) ma il filtro `^X.Y.Z-N$`, che non riconosce né `-rcN` né `X.Y.Z`: l'uscita è sempre `prerelease=true`. Per questo `0.11.2` e `0.11.3`, versioni finali, risultano pre-release. +- **Dedotto**: una nuova rc, creata con il workflow attuale, risulterebbe **non** pre-release. Non c'è ancora una rc creata con questo workflow. + +Le release servono a leggere le note generate; i servizi scelgono la versione dai requisiti, non dallo stato della release. + +## Prove in locale + +Dal [README del repo](../../README.md) e da `docs/LOCAL_DEVELOPMENT.md`:[^local] + +| Comando | Cosa fa | +|---|---| +| `./run.sh -t` | lancia `pytest` nel container di sviluppo (installa i requisiti, costruisce e installa la libreria in modalità editabile) | +| `./run.sh -i` | costruisce l'immagine `dist` e lancia `pytest` al suo interno, come la PR | +| `./run.sh -s` | apre una shell nel container | +| `./run.sh -v`, `-h` | più dettagli, aiuto | + +Le immagini partono da `zcscompany/python:3.13-dev` e `zcscompany/python:3.13-dist`.[^docker] + +[^pr]: `pr_build-and-test.yaml` r.1-26. +[^publish]: `publish-tag.yaml`, r.64 (`id: check-prerelease`) e r.77 (`steps.check_prerelease`). +[^rel]: Lettura del 10/11/2026. +[^local]: `docs/LOCAL_DEVELOPMENT.md`; opzioni in `run.sh` (`getopts stvih`). +[^docker]: `Dockerfile`, stage `dev` e `dist`. diff --git a/okf/questioni-aperte.md b/okf/questioni-aperte.md new file mode 100644 index 0000000..2a040f8 --- /dev/null +++ b/okf/questioni-aperte.md @@ -0,0 +1,150 @@ +--- +type: Known Issues +title: "Questioni aperte e limiti noti" +description: "Problemi di sicurezza, dipendenze, contatori, rilascio e documenti superati di zcs-python-core, con priorità; incongruenze trovate durante la stesura." +resource: https://github.com/zcsadmin/zcs-python-core/blob/main/okf/questioni-aperte.md +tags: [questioni-aperte, sicurezza, dipendenze, rilascio] +status: draft +generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +sources: + - { id: tlog, resource: ../app/src/zcs/core/telemetry/logging.py, title: "setup_logging e LokiContextFilter", last_modified: 2026-05-12T08:23:34Z } + - { id: tel, resource: ../app/src/zcs/core/telemetry/zcs_telemetry.py, title: "ZcsTelemetry", last_modified: 2026-07-23T09:06:44Z } + - { id: pyproject, resource: ../app/pyproject.toml, title: "Metadati del pacchetto", last_modified: 2025-10-15T08:50:58Z } + - { id: req, resource: ../app/requirements.txt, title: "Requisiti", last_modified: 2026-07-23T09:06:44Z } + - { id: readme, resource: ../README.md, title: "README", last_modified: 2025-06-27T08:46:03Z } + - { id: local, resource: ../docs/LOCAL_DEVELOPMENT.md, title: "Sviluppo locale", last_modified: 2025-06-27T08:46:03Z } + - { id: publish, resource: ../.github/workflows/publish-tag.yaml, title: "Workflow dei tag", last_modified: 2026-07-23T09:21:16Z } + - { id: logger, resource: ../app/src/zcs/core/logger/logger.py, title: "Logger", last_modified: 2026-04-03T07:58:22Z } + - { id: module, resource: ../app/src/zcs/core/session/follia_module.py, title: "FolliaModule", last_modified: 2025-12-04T13:26:01Z } + - { id: loki, resource: "git grep su origin/main di ml-follia-tesseract, ml-universe e dei consumatori (solo nomi), 2026-11-10", title: "Configurazione di Loki e uso dei contatori" } + - { id: ingestor, resource: "git grep su origin/main di aip-data-ingestor-webservice e aip-generative-ai-webservice, 2026-11-10", title: "Decodifica del JWT nei middleware dei consumatori" } + - { id: revisione-gferro, resource: "revisione del bundle, 2026-11-10", title: "Indicazioni di G. Ferro", author: "human:gferro" } +--- + +# Questioni aperte + +Ordine: priorità **alta**, **media**, **bassa**. Per ogni voce: cosa, dove, effetto. Le informazioni "lette" vengono dal codice o dai comandi eseguiti il 10/11/2026; "dedotto" e "da verificare" sono segnati. + +## Priorità alta + +### 1. Dati personali nei tag Loki + +`LokiContextFilter` imposta `auth_tenant_id`, `auth_company_id`, `auth_user_id` e **`auth_user_mail`** come tag dei record inviati a Loki, quando c'è un contesto con `op_code` e un handler Loki attivo (`telemetry/logging.py:28-38`, `:56`, `:72`).[^tlog] L'handler esiste solo se `grafana_loki_url` e `grafana_cloud_api_key` sono valorizzati: **la questione vale solo dove Loki è configurato**. + +Lettura del 10/11/2026 (solo nomi, mai valori):[^loki] + +| Dove | Cosa risulta | +|---|---| +| ml-follia-tesseract (produzione) | `GRAFANA_LOKI_URL`, `GRAFANA_LOKI_INSTANCE_ID`, `GRAFANA_OTLP_URL`, `GRAFANA_OTLP_INSTANCE_ID` e il segreto `GRAFANA_CLOUD_API_KEY` sono impostati **solo per aip-statistics-webservice** (`apps/05-aip-statistics`). L'indirizzo di Loki ha un valore predefinito non vuoto in `variables.tf`. Nessun'altra app di produzione che usa core imposta queste variabili. | +| ml-universe (develop e staging) | le stesse variabili compaiono solo per aip-mcp-follia (`aipmcpfollia-values.yml`) | +| consumatori (sandbox, locale, CI) | nei file di impostazioni locali e di CI le variabili sono presenti ma vuote; `ALLOY_HOST` è nei valori di sandbox di whatsapp, mcp-follia, mcp-cassiopea e statistics | + +- **In produzione, quindi, Loki è configurato per aip-statistics-webservice.** Che il segreto `GRAFANA_CLOUD_API_KEY` sia valorizzato non è verificabile da questi file: da verificare. +- aip-statistics-webservice compila `AuthInfo.user_email` con il claim `user_email` del token, oppure `"NOT-SET"` se manca (`app/src/config/fastapi.py:101`, `:116`). Dedotto: con Loki attivo, l'indirizzo (o `NOT-SET`) va nel tag `auth_user_mail`. Se i token di quel servizio abbiano il claim è da verificare. Gli altri consumatori letti non valorizzano `user_email` (righe commentate nei middleware di ingestor, genai e document manager). +- Dedotto: se la libreria `logging_loki` trasforma i tag in etichette dello stream (non letto, la libreria non è nel repo), ogni utente produce un flusso distinto. Da verificare con chi gestisce Loki; da decidere se `user_email` debba restare. + +## Priorità media + +### 2. Nota per i consumatori: il JWT è decodificato senza verificare la firma + +**Core non decodifica nulla**: `AuthInfo` è un dataclass senza controlli ([sessione](api/sessione.md)). Ciò che contiene lo decide il servizio. Occorrenze lette il 10/11/2026 su `origin/main`:[^ingestor] + +| Servizio | Dove | Cosa ne ricava | +|---|---|---| +| aip-data-ingestor-webservice | `app/src/config/api/register_middleware.py:41` | `tenant`, `sub`, `azp`, `custom-data` per il contesto | +| aip-generative-ai-webservice | `app/src/config/api/register_middleware.py:83` | anche `company`, `channel`, `swd_app`, `origin` | +| aip-generative-ai-webservice | `app/src/config/auth/service_token.py:47` | token di servizio appena ottenuto da Keycloak: lo decodifica solo per confrontare tenant, company e dati e scrivere avvisi nel log; non lo usa per decidere | +| aip-statistics-webservice | `app/src/config/fastapi.py:101` | `tenant`, `company`, `sub`, `user_email`, `azp` per il contesto (non richiesto: trovato durante il controllo) | + +- Le rotte del gateway `/api/openai/` di genai validano comunque il token con `keycloak_client.get_user_info` (`controller/openai_gateway/auth.py:47`) prima di leggere `AuthInfo`. +- **Da verificare nei bundle dei servizi**: se la firma è verificata a monte (ingress, gateway, Keycloak) e se il servizio è raggiungibile senza passarne. Questa scheda non lo afferma né lo esclude, e non corregge i bundle di quei servizi. + +### 3. `counter_add` e `counter_create` sollevano `ValueError` non gestiti + +Provato in locale in modalità Alloy: etichette non dichiarate, mancanti o su un contatore senza etichette sollevano `ValueError` da `counter_add` (`zcs_telemetry.py:121`, `:123`); la registrazione doppia dello stesso nome solleva `ValueError` da `counter_create` (`:92`, protetto solo da `ImportError`). Dettaglio in [comportamenti](comportamenti.md). Effetto: una chiamata sbagliata può interrompere la richiesta, se il chiamante non la protegge (dedotto). + +**Controllo sui consumatori** (`git grep` su `origin/main`, 10/11/2026):[^loki] + +| Consumatore | Chiamate a `counter_create` / `counter_add` | Esito | +|---|---|---| +| aip-whatsapp-service | `config/telemetry/custom_telemetry.py`: tre contatori con etichette (`display_phone_number`, `sender`, `webhook_type`) e due senza | Le etichette passate a `counter_add` sono esattamente quelle dichiarate; i contatori senza etichette sono chiamati senza dati. **Nessun errore trovato.** `setup_custom_telemetry` è chiamata da `api.py:123` e ogni nome è creato una volta nel file letto; il numero di invocazioni a runtime non è verificato | +| aip-generative-ai-webservice, aip-mcp-follia-server, aip-mcp-cassiopea-server, aip-statistics-webservice | nessuna chiamata a `counter_create` o `counter_add` | Non toccati | + +Nessun consumatore sbaglia le etichette: priorità media. + +### 4. Nove versioni di core in produzione + +0.2.0, 0.3.0, 0.4.1, 0.10.1, 0.10.2, 0.11.0, 0.11.1, 0.11.3, 0.11.4 (lettura del 10/11/2026, [consumatori](consumatori.md)). Rischio di rilascio: un fix o un cambio di comportamento (es. `message` sostituito dall'eccezione, contatori, `datasource_ids`) vale solo per i servizi che hanno aggiornato la dipendenza. Servizi con core molto vecchio: aip-audio-service (0.2.0), aip-data-storage-consumer (0.3.0), aip-erp-ai-webservice (0.4.1). + +### 5. Il tag `0.11.2` ha meno codice del suo `-rc2` + +`0.11.2` punta a `3438808` (stesso commit di `0.11.1`) e non contiene `label_names`, presente in `0.11.2-rc1`, `-rc2` e `0.11.3`. Per i numeri di versione `0.11.2 > 0.11.2-rc2`. Chi fissa `==0.11.2` riceve il comportamento senza il fix. Letto il 10/11/2026: **nessun consumatore lo richiede** e nessun consumatore usa intervalli di versione su core (tutti i requisiti sono `==`). Vedi [versioni](versioni.md). + +### 6. Workflow dei tag: identificativo dello step diverso (r.64 contro r.77) + +`id: check-prerelease` a r.64 e `steps.check_prerelease` a r.77: i nomi non coincidono.[^publish] Letto: la release `0.11.4` non è marcata pre-release; `0.11.2` e `0.11.3` (versioni finali) lo sono. Dedotto: una rc creata con il workflow attuale non sarebbe marcata pre-release. Dettaglio in [rilascio](operativita/rilascio.md). + +### 7. Effetti globali del logger + +La factory dei record si sostituisce all'import (`logger.py:9`, `:32`); il costruttore di `ZcsLogging` rimpiazza gli handler dei logger che ne hanno già (`:132-137`); con eccezione allegata il campo `message` del JSON diventa il testo dell'eccezione (`:39-40`).[^logger] Effetti e versioni in [comportamenti](comportamenti.md). + +### 8. Rinomina non retrocompatibile senza `!` (0.8.0) + +`QaInfo.datasource_id` è diventato `datasource_ids` (lista) nel tag 0.8.0, commit `60b5fae` senza `!`. Un consumatore che costruisce `QaInfo(datasource_id=...)` si rompe all'aggiornamento (letto nel diff). Vedi [versioni](versioni.md). + +### 9. zcs-python-stats richiede `zcs-python-core==0.7.2`, che non è un tag + +I tag della repo sono `0.7.0`, `0.7.1` e `0.8.0`: `0.7.2` non esiste come tag (letto). Da verificare se è nel registro dei pacchetti (non ho accesso) o se il requisito è errato. Vedi [consumatori](consumatori.md). Da portare nel bundle di zcs-python-stats (AP-5321). + +### 10. Consumatori non in produzione e su rc + +aip-audio-video-consumer e aip-xml-invoice-consumer hanno il modulo commentato in `main.tf` (r.349-364 e r.326-333) ma le chiavi `avconsumer` e `xmlconsumer` restano in `app_versions`; il tag 1.4.3 di audio-video richiede core 0.2.0 e il suo `main` 0.11.1, il tag 1.8.0 di xml-invoice richiede 0.2.0. aip-follia-voip richiede `0.11.0-rc1` (una rc) e non è in `app_versions`.[^revisione-gferro] + +## Priorità bassa + +### 11. Dipendenze non dichiarate + +- `pyproject.toml` non ha `dependencies`;[^pyproject] `requirements.txt` elenca `pydantic_settings` e `prometheus_client` ma non è letto da chi installa il pacchetto.[^req] Stessa situazione descritta per zcs-python-genai. +- `logging_loki` è importato dentro `setup_logging` solo se `has_loki_config`, a `telemetry/logging.py:57`, **senza `try`**: se la libreria manca e Loki è configurato, `setup_logging` solleva `ImportError`. Gli altri import opzionali (OpenTelemetry, `prometheus_client`) sono protetti. +- `zcs.core.telemetry` richiede `pydantic_settings` anche se la telemetria non si usa, perché `TelemetrySettings` è importata e istanziata all'import. +- Effetto: ogni servizio deve aggiungere da sé `pydantic_settings`, `opentelemetry-*`, `logging_loki`, `prometheus_client`; una versione di core non indica cosa serve. + +### 12. README superato (ultimo commit 27/06/2025) + +Letto il 10/11/2026, confrontato con il codice del 23/07/2026:[^readme] + +| Frase del README | Cosa dice il codice | +|---|---| +| "The library doesn't require directly third party dependencies. This will let you install only the requirements needed by the utils you will effectively use." | Vero per `session`, `exception`, `logger`; non più per la telemetria (dal tag 0.11.0): `pydantic_settings` all'import, OpenTelemetry e `prometheus_client` per le funzioni | +| Esempi d'uso: solo `ZcsException` e `ZcsLogging` | Mancano `RequestState`, `request_context`, `AuthInfo`, `FolliaModule`, `QaInfo` (dal tag 0.4.0) e `ZcsTelemetry`, `setup_logging`, `set_trace_attributes` (0.11.0) | +| Nessun cenno ai campi di `RequestState` | `channel` (0.11.1), `attempts` (0.10.0), `custom_data` (0.10.1), `job_id`/`file_id` (0.9.0), `size`/`total_pages` (0.8.0), `doc_type` (0.7.1), `qa_info` (0.7.0) non compaiono | + +`docs/LOCAL_DEVELOPMENT.md` (stessa data) descrive `./run.sh -t` e `-i`, che esistono ancora in `run.sh`: nessuna frase superata.[^local] + +### 13. Altre incongruenze di nome e tipo (da verificare) + +- `delta_ns` e `total_ns` sono in secondi (`logger.py:68-69`). +- `log_level` annotato `str`, valore predefinito intero (`logger.py:117`). +- `FolliaModule` ha la docstring "Data class" ma è una `StrEnum` (`follia_module.py:4-8`).[^module] +- `EndpointFilter` usa una lista mutabile come valore predefinito (`endpoint_filter.py:11`). +- `alloy_metrics_port` e `_build_alloy_metrics_endpoint` non sono usati ([configurazione](operativita/configurazione.md)). + +### 14. Copertura dei test + +Tre file di test (76 righe totali, `app/tests/zcs/core/`): impostazioni e contatori della telemetria (3 test), una `ZcsException`, e un test del logger che si limita a creare `ZcsLogging`. Nessun test per `RequestState`, `request_context`, i formatter, `EndpointFilter` o `setup_logging` (letto). + +## Incongruenze trovate durante la stesura (da verificare) + +Nessuna correzione al codice o ai documenti è stata fatta da questo bundle. Le voci 2, 9, 11, 12 e 13 riguardano la repo di core o i bundle dei consumatori e vanno decise da una persona (correzioni in rami separati). + +[^loki]: Lettura su `origin/main` del 10/11/2026; nei file sono stati guardati solo i nomi delle variabili. +[^ingestor]: Lettura su `origin/main` del 10/11/2026. +[^tlog]: `telemetry/logging.py`. +[^pyproject]: `pyproject.toml`. +[^req]: `requirements.txt`. +[^publish]: `publish-tag.yaml` r.64 e r.77. +[^logger]: `logger.py`. +[^readme]: `README.md`. +[^local]: `docs/LOCAL_DEVELOPMENT.md`. +[^module]: `follia_module.py`. +[^revisione-gferro]: Indicazione di G. Ferro del 10/11/2026. diff --git a/okf/versioni.md b/okf/versioni.md new file mode 100644 index 0000000..01bffe1 --- /dev/null +++ b/okf/versioni.md @@ -0,0 +1,56 @@ +--- +type: Version History +title: "Storia delle versioni" +description: "Tag di zcs-python-core dal 2025: data, cosa cambia nel codice, modifiche non retrocompatibili e vincoli noti dal codice." +resource: https://github.com/zcsadmin/zcs-python-core/tags +tags: [versioni, tag, release] +status: draft +generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +sources: + - { id: git, resource: "git log e git diff tra i tag della repo, letti il 2026-11-10", title: "Storia dei tag" } + - { id: rel, resource: "gh release list e gh api repos/zcsadmin/zcs-python-core/releases, 2026-11-10", title: "Release GitHub e stato pre-release" } + - { id: publish, resource: ../.github/workflows/publish-tag.yaml, title: "Workflow dei tag", last_modified: 2026-07-23T09:21:16Z } + - { id: qa, resource: ../app/src/zcs/core/session/qa_info.py, title: "QaInfo", last_modified: 2025-12-11T13:51:36Z } +--- + +# Storia delle versioni + +La data è quella del commit del tag (`git log -1 --format=%cs `). "Cosa cambia" è letto dalle differenze nel codice (`app/src`) tra un tag e il precedente. La colonna "vincoli noti dal codice" riporta **solo ciò che il codice dice**: nessuna deduzione dai numeri AP nei messaggi di commit.[^git] + +| Tag | Data | Commit | Cosa cambia | Vincoli noti dal codice | +|---|---|---|---|---| +| 0.3.0 | 27/06/2025 | `ec0be53` | `EndpointFilter` | nessuno | +| 0.4.0-rc1, rc2 | 13/10/2025 | `1769345`, `4d5f91d` | rc di 0.4.0 (contenuto non confrontato: da verificare) | — | +| 0.4.0 | 15/10/2025 | `38eed47` | prima versione di `RequestState` e `request_context`; formato JSON con `op_code`, `request_id`, tempi | nessuno | +| 0.4.1 | 23/10/2025 | `3be72f5` | dati aggiuntivi nel formato JSON del logger | nessuno | +| 0.5.0 | 02/12/2025 | `f3145a2` | `AuthInfo` | nessuno | +| 0.5.1 | 02/12/2025 | `48e0b4e` | `setAuthInfo` | nessuno | +| 0.6.0 | 04/12/2025 | `5be26dd` | `FolliaModule` | nessuno | +| 0.7.0 | 10/12/2025 | `10ce223` | `QaInfo` (con `datasource_id`) | nessuno | +| 0.7.1 | 10/12/2025 | `b72e3e4` | `doc_type` | nessuno | +| 0.8.0 | 19/12/2025 | `1adfd72` | `size`, `total_pages`; **`QaInfo.datasource_id` rinominato `datasource_ids` (lista)** | **Non retrocompatibile nel codice**: chi costruisce `QaInfo(datasource_id=...)` o legge `.datasource_id` si rompe. Il commit (`60b5fae`, "change datasource ids") non ha `!`.[^qa] | +| 0.9.0 | 23/12/2025 | `83e97e3` | `job_id`, `file_id` | nessuno | +| 0.10.0 | 21/01/2026 | `b522578` | `attempts` | nessuno | +| 0.10.1 | 10/02/2026 | `05b0df8` | `custom_data` | nessuno | +| 0.10.2-rc1, rc2 | 03/04/2026 | `f3a3690`, `fcb1247` | rc1: contenuto non confrontato (da verificare); rc2: il commit è «ci: create release on tag» (il workflow crea la release sul tag) | — | +| 0.10.2 | 07/04/2026 | `1d359f2` | `logger.py`: protezione per i log OpenTelemetry | nessuno | +| 0.11.0-rc1 | 12/05/2026 | `c6c2a6f` | rc della telemetria | — | +| 0.11.0 | 13/05/2026 | `865d042` | **telemetria**: `ZcsTelemetry`, `setup_logging`, `set_trace_attributes`, `TelemetrySettings` | `requirements.txt` aggiunge `pydantic_settings`; i moduli `telemetry` e `settings` lo importano | +| 0.11.1 | 13/05/2026 | `3438808` | `RequestState.channel` (`getChannel`, `setChannel`) | nessuno | +| **0.11.2** | 13/05/2026 (commit); release GitHub del 23/07/2026 | `3438808` | **stesso commit di 0.11.1**: stesso codice | non contiene `label_names` (vedi sotto) | +| 0.11.2-rc1, rc2 | 23/07/2026 | `c7bbaa3` | `counter_create(..., label_names=None)` e contatore Prometheus con etichette | — | +| 0.11.3 | 23/07/2026 | `3f3eb95` | merge del fix delle etichette, `build` 1.5.0, `pytest` 9.1.1, `pydantic_settings` 2.14.2, `prometheus_client` 0.25.0 | `prometheus_client` entra nei requisiti di sviluppo | +| 0.11.4 | 23/07/2026 | `8d0cda4` | solo `publish-tag.yaml` (controllo pre-release); nessun cambio in `app/src` | nessuno | + +## Note + +- **Esiste un tag `0.11.2` finale.** Punta allo stesso commit di `0.11.1` (`3438808`) e **non contiene** il fix delle etichette (`494d4d8`), che è invece in `0.11.2-rc1`, `0.11.2-rc2` e `0.11.3`. Il workflow del tag `0.11.2` è terminato con successo il 23/07/2026 e la release GitHub risulta pre-release.[^rel] Per l'ordine delle versioni `0.11.2` è maggiore di `0.11.2-rc2`, ma ha meno codice. +- **Nessun commit** con `!` dopo il tipo, `BREAKING` o `BREAKING CHANGE` nel messaggio (ricerca su tutta la storia con `git log --grep`). L'unica modifica non retrocompatibile letta nel codice è la rinomina di `datasource_id` in 0.8.0. +- Le rc 0.10.2 e 0.11.0 hanno data diversa dal tag finale; le rc 0.11.2 sono state create dopo il tag `0.11.2` (stesso giorno). +- Non c'è `CHANGELOG`: la storia sta nei commit e nelle release generate automaticamente dal workflow.[^publish] +- Per i tag, lo stato pre-release delle release GitHub è in [rilascio](operativita/rilascio.md). + +[^git]: Date e commit da `git log -1 --format=%cs ^{commit}`; differenze da `git diff --stat` e `git show`. +[^qa]: `qa_info.py` r.11 al tag corrente; differenza in `git show 60b5fae`. +[^rel]: `gh api repos/zcsadmin/zcs-python-core/releases/tags/0.11.2` e `gh run list --workflow=publish-tag.yaml`. +[^publish]: `publish-tag.yaml`, step "Create GitHub Release" con `generate_release_notes: true`.