95 95
96Quando l'app desktop o un runner di [ambiente self-hosted](https://code.claude.com/docs/it/self-hosted-environments) avvia Claude Code e nomina un endpoint OTLP nell'ambiente che fornisce, Claude Code fissa la destinazione allo stesso modo: le variabili di telemetria del launcher rimuovono le variabili impostate dagli sviluppatori esattamente come fanno le impostazioni gestite. Claude Code non rimuove le variabili che il launcher stesso ha impostato. Richiede Claude Code v2.1.251 o successivo.96Quando l'app desktop o un runner di [ambiente self-hosted](https://code.claude.com/docs/it/self-hosted-environments) avvia Claude Code e nomina un endpoint OTLP nell'ambiente che fornisce, Claude Code fissa la destinazione allo stesso modo: le variabili di telemetria del launcher rimuovono le variabili impostate dagli sviluppatori esattamente come fanno le impostazioni gestite. Claude Code non rimuove le variabili che il launcher stesso ha impostato. Richiede Claude Code v2.1.251 o successivo.
97 97
98## Dettagli della configurazione98## Dettagli di configurazione
99 99
100### Variabili di configurazione comuni100### Variabili di configurazione comuni
101 101
102Queste variabili configurano gli esportatori, gli endpoint e il comportamento dell'esportazione per tutti i deployment.102Queste variabili configurano gli exporter, gli endpoint e il comportamento di esportazione per tutti i deploy.
103 103
104Se imposti una variabile di endpoint o protocollo per segnale specifico, come `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, Claude Code la utilizza al posto della variabile generica per quel segnale. Se imposti una variabile di intestazioni per segnale specifico, come `OTEL_EXPORTER_OTLP_METRICS_HEADERS`, Claude Code la unisce con la generica `OTEL_EXPORTER_OTLP_HEADERS` per quel segnale.104Se imposti una variabile di endpoint o di protocollo specifica per segnale, come `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, Claude Code la usa al posto della variabile generica per quel segnale. Se imposti una variabile di header specifica per segnale, come `OTEL_EXPORTER_OTLP_METRICS_HEADERS`, Claude Code ne esegue il merge con la variabile generica `OTEL_EXPORTER_OTLP_HEADERS` per quel segnale.
105 105
106Su macchine con impostazioni gestite, vedi [Come le impostazioni gestite bloccano la destinazione OTLP](#how-managed-settings-lock-the-otlp-destination) per sapere cosa Claude Code rimuove.106Sulle macchine con impostazioni gestite, consulta [Come le impostazioni gestite bloccano la destinazione OTLP](#how-managed-settings-lock-the-otlp-destination) per sapere cosa rimuove Claude Code.
107 107
108| Variabile di ambiente | Descrizione | Valori di esempio |108| Variabile d'ambiente | Descrizione | Valori di esempio |
109| - | - | - |109| - | - | - |
110| `CLAUDE_CODE_ENABLE_TELEMETRY` | Abilita la raccolta della telemetria (obbligatorio) | `1` |110| `CLAUDE_CODE_ENABLE_TELEMETRY` | Abilita la raccolta della telemetria (obbligatoria) | `1` |
111| `OTEL_METRICS_EXPORTER` | Tipi di esportatore di metriche, separati da virgola. Usa `none` per disabilitare | `console`, `otlp`, `prometheus`, `none` |111| `OTEL_METRICS_EXPORTER` | Tipi di exporter delle metriche, separati da virgole. Usa `none` per disabilitare | `console`, `otlp`, `prometheus`, `none` |
112| `OTEL_LOGS_EXPORTER` | Tipi di esportatore di log/eventi, separati da virgola. Usa `none` per disabilitare | `console`, `otlp`, `none` |112| `OTEL_LOGS_EXPORTER` | Tipi di exporter di log/eventi, separati da virgole. Usa `none` per disabilitare | `console`, `otlp`, `none` |
113| `OTEL_EXPORTER_OTLP_PROTOCOL` | Protocollo per l'esportatore OTLP, si applica a tutti i segnali. Claude Code non ha un protocollo predefinito, quindi imposta questa variabile o la variabile di protocollo specifica per segnale per ogni esportatore `otlp` che abiliti | `grpc`, `http/json`, `http/protobuf` |113| `OTEL_EXPORTER_OTLP_PROTOCOL` | Protocollo per l'exporter OTLP, si applica a tutti i segnali. Claude Code non ha un protocollo predefinito, quindi imposta questa variabile o la variabile di protocollo specifica per segnale per ogni exporter `otlp` che abiliti | `grpc`, `http/json`, `http/protobuf` |
114| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint del collettore OTLP per tutti i segnali | `http://localhost:4317` |114| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint del collector OTLP per tutti i segnali | `http://localhost:4317` |
115| `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` | Protocollo per le metriche, sostituisce l'impostazione generale | `grpc`, `http/json`, `http/protobuf` |115| `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` | Protocollo per le metriche, sovrascrive l'impostazione generale | `grpc`, `http/json`, `http/protobuf` |
116| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Endpoint delle metriche OTLP, sostituisce l'impostazione generale | `http://localhost:4318/v1/metrics` |116| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Endpoint OTLP per le metriche, sovrascrive l'impostazione generale | `http://localhost:4318/v1/metrics` |
117| `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` | Protocollo per i log, sostituisce l'impostazione generale | `grpc`, `http/json`, `http/protobuf` |117| `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` | Protocollo per i log, sovrascrive l'impostazione generale | `grpc`, `http/json`, `http/protobuf` |
118| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Endpoint dei log OTLP, sostituisce l'impostazione generale | `http://localhost:4318/v1/logs` |118| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Endpoint OTLP per i log, sovrascrive l'impostazione generale | `http://localhost:4318/v1/logs` |
119| `OTEL_EXPORTER_OTLP_HEADERS` | Intestazioni di autenticazione per OTLP | `Authorization=Bearer token` |119| `OTEL_EXPORTER_OTLP_HEADERS` | Header di autenticazione per OTLP | `Authorization=Bearer token` |
120| `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | Intestazioni di autenticazione per le metriche, unite alle intestazioni generali | `Authorization=Bearer token` |120| `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | Header di autenticazione per le metriche, uniti tramite merge con gli header generali | `Authorization=Bearer token` |
121| `OTEL_EXPORTER_OTLP_LOGS_HEADERS` | Intestazioni di autenticazione per i log, unite alle intestazioni generali | `Authorization=Bearer token` |121| `OTEL_EXPORTER_OTLP_LOGS_HEADERS` | Header di autenticazione per i log, uniti tramite merge con gli header generali | `Authorization=Bearer token` |
122| `OTEL_METRIC_EXPORT_INTERVAL` | Intervallo di esportazione in millisecondi (predefinito: 60000) | `5000`, `60000` |122| `OTEL_METRIC_EXPORT_INTERVAL` | Intervallo di esportazione in millisecondi (predefinito: 60000) | `5000`, `60000` |
123| `OTEL_LOGS_EXPORT_INTERVAL` | Intervallo di esportazione dei log in millisecondi (predefinito: 5000) | `1000`, `10000` |123| `OTEL_LOGS_EXPORT_INTERVAL` | Intervallo di esportazione dei log in millisecondi (predefinito: 5000) | `1000`, `10000` |
124| `OTEL_LOG_USER_PROMPTS` | Abilita la registrazione del contenuto del prompt dell'utente (predefinito: disabilitato) | `1` per abilitare |124| `OTEL_LOG_USER_PROMPTS` | Abilita la registrazione del contenuto dei prompt dell'utente (predefinito: disabilitato) | `1` per abilitare |
125| `OTEL_LOG_ASSISTANT_RESPONSES` | Abilita la registrazione del testo della risposta dell'assistente su eventi `assistant_response` (predefinito: disabilitato). Se non impostato, ricade al valore di `OTEL_LOG_USER_PROMPTS` | `1` per abilitare, `0` per mantenere oscurato |125| `OTEL_LOG_ASSISTANT_RESPONSES` | Abilita la registrazione del testo delle risposte dell'assistente negli eventi `assistant_response` (predefinito: disabilitato). Se non è impostata, usa il valore di `OTEL_LOG_USER_PROMPTS` | `1` per abilitare, `0` per mantenerlo oscurato |
126| `OTEL_LOG_TOOL_DETAILS` | Abilita la registrazione dei parametri dello strumento e degli argomenti di input negli eventi dello strumento e negli attributi dello span di traccia: comandi Bash, nomi del server MCP e dello strumento, nomi delle skill, nomi dei workflow creati dall'utente e input dello strumento. Abilita anche i nomi dei comandi personalizzati, plugin e MCP su eventi `user_prompt` e i nomi reali dell'agente, della skill, del plugin e del server MCP e dello strumento sui [contatori di costo e token](#cost-counter) (predefinito: disabilitato). Per i server integrati di Claude Desktop, nelle sessioni di proprietà di Claude Desktop, `mcp_server_name`/`mcp_tool_name` vengono emessi su `tool_decision`/`tool_result` anche con il flag disattivato. L'eccezione richiede Claude Code v2.1.214 o successivo | `1` per abilitare |126| `OTEL_LOG_TOOL_DETAILS` | Abilita la registrazione dei parametri degli strumenti e degli argomenti di input negli eventi degli strumenti e negli attributi degli span delle tracce: comandi Bash, nomi dei server MCP e degli strumenti, nomi delle skill, nomi dei workflow creati dall'utente e input degli strumenti. Abilita anche i nomi dei comandi personalizzati, dei plugin e MCP negli eventi `user_prompt`, e i nomi reali di agenti, skill, plugin, server MCP e strumenti nei [contatori di costi e token](#cost-counter) (predefinito: disabilitato). Per i server integrati di Claude Desktop, nelle sessioni gestite da Claude Desktop, `mcp_server_name`/`mcp_tool_name` vengono emessi su `tool_decision`/`tool_result` anche con il flag disattivato. L'eccezione richiede Claude Code v2.1.214 o successiva | `1` per abilitare |
127| `OTEL_LOG_TOOL_CONTENT` | Abilita la registrazione del contenuto dello strumento nell'[evento dello span `tool.output`](#tool-output-span-event) (predefinito: disabilitato). Gli attributi dello span portano il contenuto dello strumento sotto [i loro stessi gate](#new-context-gates). Richiede [tracing](#traces-beta). Il contenuto viene troncato al limite di contenuto (60 KB per impostazione predefinita) | `1` per abilitare |127| `OTEL_LOG_TOOL_CONTENT` | Abilita la registrazione del contenuto degli strumenti nell'[evento di span `tool.output`](#tool-output-span-event) (predefinito: disabilitato). Gli attributi degli span riportano il contenuto degli strumenti sotto [i propri controlli](#new-context-gates). Richiede il [tracing](#traces-beta). Il contenuto viene troncato al limite del contenuto (60 KB per impostazione predefinita) | `1` per abilitare |
128| `OTEL_LOG_MANAGED_SETTINGS` | Aggiungi le impostazioni gestite oscurate e un digest SHA-256 delle impostazioni prima dell'oscuramento agli eventi [managed settings resolved](#managed-settings-resolved-event) (predefinito: disabilitato). Un valore nelle impostazioni di progetto o locali non lo attiva. Richiede Claude Code v2.1.274 o successivo | `1` per abilitare |128| `OTEL_LOG_MANAGED_SETTINGS` | Aggiunge le impostazioni gestite oscurate, e un digest SHA-256 delle impostazioni prima dell'oscuramento, agli eventi [managed settings resolved](#managed-settings-resolved-event) (predefinito: disabilitato). Un valore nelle impostazioni di progetto o locali non lo attiva. Richiede Claude Code v2.1.274 o successiva | `1` per abilitare |
129| `OTEL_LOG_RAW_API_BODIES` | Emetti il JSON completo della richiesta e della risposta dell'API Anthropic Messages come eventi di log `api_request_body` / `api_response_body` (predefinito: disabilitato). I corpi includono l'intera cronologia della conversazione. L'abilitazione di questa opzione implica il consenso a tutto ciò che `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_DETAILS` e `OTEL_LOG_TOOL_CONTENT` rivelerebbero | `1` per corpi inline troncati al limite di contenuto (60 KB per impostazione predefinita), o `file:<dir>` per corpi non troncati su disco con un puntatore `body_ref` nell'evento |129| `OTEL_LOG_RAW_API_BODIES` | Emette il JSON completo di richiesta e risposta della Messages API di Anthropic come eventi di log `api_request_body` / `api_response_body` (predefinito: disabilitato). I corpi includono l'intera cronologia della conversazione. Abilitarla implica il consenso a tutto ciò che rivelerebbero `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_DETAILS` e `OTEL_LOG_TOOL_CONTENT` | `1` per corpi inline troncati al limite del contenuto (60 KB per impostazione predefinita), oppure `file:<dir>` per corpi non troncati su disco con un puntatore `body_ref` nell'evento |
130| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | Limite di contenuto: la lunghezza massima degli attributi che portano contenuto come risposte del modello, contenuto dello strumento, prompt di sistema e corpi API grezzi, marcatore di troncamento incluso, in unità di codice UTF-16 (predefinito: 61440, cioè 60 KB). Il valore predefinito è dimensionato per backend che limitano i valori degli attributi a 64 KB; aumentalo solo se il tuo backend accetta valori più grandi, o riducilo per tagliare il volume della telemetria. Quando un limite di attributo dell'SDK OpenTelemetry, `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` o una delle sue varianti logrecord e span, è impostato più basso, Claude Code tronca a quel valore più piccolo in modo che il marcatore `[TRUNCATED ...]` rimanga entro il limite dell'SDK | `262144` |130| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | Limite del contenuto: la lunghezza massima degli attributi che contengono contenuto, come risposte del modello, contenuto degli strumenti, prompt di sistema e corpi API grezzi, marcatore di troncamento incluso, in unità di codice UTF-16 (predefinito: 61440, cioè 60 KB). Il valore predefinito è dimensionato per i backend che limitano i valori degli attributi a 64 KB; aumentalo solo se il tuo backend accetta valori più grandi, oppure riducilo per diminuire il volume della telemetria. Quando un limite degli attributi dell'SDK OpenTelemetry, `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` o una delle sue varianti per logrecord e span, è impostato su un valore inferiore, Claude Code tronca a quel valore più piccolo in modo che il marcatore `[TRUNCATED ...]` rimanga entro il limite dell'SDK | `262144` |
131| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Preferenza di temporalità delle metriche (predefinito: `delta`). Imposta su `cumulative` se il tuo backend si aspetta una temporalità cumulativa | `delta`, `cumulative` |131| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Preferenza di temporalità delle metriche (predefinito: `delta`). Imposta `cumulative` se il tuo backend si aspetta una temporalità cumulativa | `delta`, `cumulative` |
132| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Intervallo per l'aggiornamento delle intestazioni dinamiche (predefinito: 1740000ms / 29 minuti) | `900000` |132| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Intervallo per l'aggiornamento degli header dinamici (predefinito: 1740000ms / 29 minuti) | `900000` |
133 133
134Per i protocolli `http/protobuf` e `http/json`, Claude Code invia ogni richiesta di esportazione con un'intestazione `Content-Length`.134Per i protocolli `http/protobuf` e `http/json`, Claude Code invia ogni richiesta di esportazione con un header `Content-Length`.
135 135
136### Autenticazione mTLS136### Autenticazione mTLS
137 137
138Il modo in cui configuri i certificati client per l'esportatore OTLP dipende dal protocollo OTLP in uso per quel segnale, impostato tramite `OTEL_EXPORTER_OTLP_PROTOCOL` o l'override specifico per segnale. La stessa configurazione si applica a metriche, log e tracce.138Il modo in cui configuri i certificati client per l'exporter OTLP dipende dal protocollo OTLP in uso per quel segnale, impostato tramite `OTEL_EXPORTER_OTLP_PROTOCOL` o l'override specifico per segnale. La stessa configurazione si applica a metriche, log e tracce.
139 139
140| Protocollo | Variabili del certificato client | Fidati della CA del collettore con |140| Protocollo | Variabili del certificato client | Considera attendibile la CA del collector con |
141| :- | :- | :- |141| :- | :- | :- |
142| `http/protobuf`, `http/json` | `CLAUDE_CODE_CLIENT_CERT`, `CLAUDE_CODE_CLIENT_KEY` e facoltativamente `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`. Vedi [Configurazione di rete](https://code.claude.com/docs/it/network-config.md#mtls-authentication) | `NODE_EXTRA_CA_CERTS` |142| `http/protobuf`, `http/json` | `CLAUDE_CODE_CLIENT_CERT`, `CLAUDE_CODE_CLIENT_KEY` e, facoltativamente, `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`. Consulta [Configurazione di rete](https://code.claude.com/docs/it/network-config.md#mtls-authentication) | `NODE_EXTRA_CA_CERTS` |
143| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` e `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`, o i varianti specifici per segnale come `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` per utilizzare un certificato diverso per segnale | `OTEL_EXPORTER_OTLP_CERTIFICATE` |143| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` e `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`, oppure le varianti specifiche per segnale come `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` per usare un certificato diverso per ogni segnale | `OTEL_EXPORTER_OTLP_CERTIFICATE` |
144 144
145Per `grpc`, l'SDK OpenTelemetry legge direttamente le variabili OTLP standard, quindi le configurazioni esistenti che impostano le variabili di metriche specifiche per segnale continuano a funzionare. Su macchine con impostazioni gestite, Claude Code [può rimuovere le credenziali e gli endpoint specifici per segnale impostati dallo sviluppatore](#how-managed-settings-lock-the-otlp-destination) all'avvio.145Per `grpc`, l'SDK OpenTelemetry legge direttamente le variabili OTLP standard, quindi le configurazioni esistenti che impostano le variabili delle metriche specifiche per segnale continuano a funzionare. Sulle macchine con impostazioni gestite, Claude Code [potrebbe rimuovere all'avvio le credenziali e gli endpoint specifici per segnale impostati dallo sviluppatore](#how-managed-settings-lock-the-otlp-destination).
146 146
147### Controllo della cardinalità delle metriche147### Controllo della cardinalità delle metriche
148 148
149Le seguenti variabili di ambiente controllano quali attributi sono inclusi nelle metriche per gestire la cardinalità:149Le seguenti variabili d'ambiente controllano quali attributi vengono inclusi nelle metriche per gestire la cardinalità:
150 150
151| Variabile di ambiente | Descrizione | Valore predefinito | Esempio per disabilitare |151| Variabile d'ambiente | Descrizione | Valore predefinito | Esempio per disabilitare |
152| - | - | - | - |152| - | - | - | - |
153| `OTEL_METRICS_INCLUDE_SESSION_ID` | Includi gli attributi session.id e, nelle sessioni cloud, ccr.session.id nelle metriche | `true` | `false` |153| `OTEL_METRICS_INCLUDE_SESSION_ID` | Include gli attributi session.id e, nelle sessioni cloud, ccr.session.id nelle metriche | `true` | `false` |
154| `OTEL_METRICS_INCLUDE_VERSION` | Includi l'attributo app.version nelle metriche | `false` | `true` |154| `OTEL_METRICS_INCLUDE_VERSION` | Include l'attributo app.version nelle metriche | `false` | `true` |
155| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Includi gli attributi user.account\_uuid e user.account\_id nelle metriche | `true` | `false` |155| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Include gli attributi user.account\_uuid e user.account\_id nelle metriche | `true` | `false` |
156| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | Includi l'attributo app.entrypoint nelle metriche | `false` | `true` |156| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | Include l'attributo app.entrypoint nelle metriche | `false` | `true` |
157| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | Includi le chiavi da `OTEL_RESOURCE_ATTRIBUTES` come attributi sui punti dati delle metriche | `true` | `false` |157| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | Include le chiavi di `OTEL_RESOURCE_ATTRIBUTES` come attributi sui datapoint delle metriche | `true` | `false` |
158| `OTEL_METRICS_INCLUDE_REPOSITORY` | Includi gli [attributi di identità del repository](#repository-attributes) `vcs.*` su metriche ed eventi. Richiede Claude Code v2.1.269 o successivo | `false` | `true` |158| `OTEL_METRICS_INCLUDE_REPOSITORY` | Include gli [attributi di identità del repository](#repository-attributes) `vcs.*` su metriche ed eventi. Richiede Claude Code v2.1.269 o successiva | `false` | `true` |
159 159
160Una cardinalità più bassa generalmente significa migliori prestazioni e costi di archiviazione inferiori, ma dati meno granulari per l'analisi.160Una cardinalità inferiore generalmente comporta prestazioni migliori e costi di archiviazione inferiori, ma dati meno granulari per l'analisi.
161 161
162### Traces (beta)162### Tracce (beta)
163 163
164Il tracing distribuito esporta span che collegano ogni prompt dell'utente alle richieste API e alle esecuzioni di strumenti che attiva, in modo da poter visualizzare una richiesta completa come una singola traccia nel tuo backend di tracing.164Il tracing distribuito esporta span che collegano ogni prompt dell'utente alle richieste API e alle esecuzioni degli strumenti che attiva, così puoi visualizzare una richiesta completa come una singola traccia nel tuo backend di tracing.
165 165
166Il tracing è disabilitato per impostazione predefinita. Per abilitarlo, imposta sia `CLAUDE_CODE_ENABLE_TELEMETRY=1` che `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`, quindi imposta `OTEL_TRACES_EXPORTER` per scegliere dove vengono inviati gli span. Le tracce riutilizzano la [configurazione OTLP comune](#common-configuration-variables) per endpoint, protocollo, intestazioni e [mTLS](#mtls-authentication). Su macchine con impostazioni gestite, Claude Code [può rimuovere le credenziali e gli endpoint specifici per segnale impostati dallo sviluppatore](#how-managed-settings-lock-the-otlp-destination) all'avvio.166Il tracing è disattivato per impostazione predefinita. Per abilitarlo, imposta sia `CLAUDE_CODE_ENABLE_TELEMETRY=1` sia `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`, quindi imposta `OTEL_TRACES_EXPORTER` per scegliere dove vengono inviati gli span. Le tracce riutilizzano la [configurazione OTLP comune](#common-configuration-variables) per endpoint, protocollo, header e [mTLS](#mtls-authentication). Sulle macchine con impostazioni gestite, Claude Code [potrebbe rimuovere all'avvio le credenziali e gli endpoint specifici per segnale impostati dallo sviluppatore](#how-managed-settings-lock-the-otlp-destination).
167 167
168| Variabile di ambiente | Descrizione | Valori di esempio |168| Variabile d'ambiente | Descrizione | Valori di esempio |
169| - | - | - |169| - | - | - |
170| `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` | Abilita il tracing degli span (obbligatorio). `ENABLE_ENHANCED_TELEMETRY_BETA` è anche accettato | `1` |170| `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` | Abilita il tracing degli span (obbligatoria). È accettata anche `ENABLE_ENHANCED_TELEMETRY_BETA` | `1` |
171| `OTEL_TRACES_EXPORTER` | Tipi di esportatore di tracce, separati da virgola. Usa `none` per disabilitare | `console`, `otlp`, `none` |171| `OTEL_TRACES_EXPORTER` | Tipi di exporter delle tracce, separati da virgole. Usa `none` per disabilitare | `console`, `otlp`, `none` |
172| `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | Protocollo per le tracce, sostituisce `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc`, `http/json`, `http/protobuf` |172| `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | Protocollo per le tracce, sovrascrive `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc`, `http/json`, `http/protobuf` |
173| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Endpoint delle tracce OTLP, sostituisce `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318/v1/traces` |173| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Endpoint OTLP per le tracce, sovrascrive `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318/v1/traces` |
174| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | Intestazioni di autenticazione per le tracce, unite a `OTEL_EXPORTER_OTLP_HEADERS` | `Authorization=Bearer token` |174| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | Header di autenticazione per le tracce, uniti tramite merge con `OTEL_EXPORTER_OTLP_HEADERS` | `Authorization=Bearer token` |
175| `OTEL_TRACES_EXPORT_INTERVAL` | Intervallo di esportazione batch degli span in millisecondi (predefinito: 5000) | `1000`, `10000` |175| `OTEL_TRACES_EXPORT_INTERVAL` | Intervallo di esportazione dei batch di span in millisecondi (predefinito: 5000) | `1000`, `10000` |
176 176
177Gli span oscurano il testo del prompt dell'utente, i dettagli dell'input dello strumento e il contenuto dello strumento per impostazione predefinita. Imposta `OTEL_LOG_USER_PROMPTS=1`, `OTEL_LOG_TOOL_DETAILS=1` e `OTEL_LOG_TOOL_CONTENT=1` per includerli.177Per impostazione predefinita, gli span oscurano il testo dei prompt dell'utente, i dettagli dell'input degli strumenti e il contenuto degli strumenti. Imposta `OTEL_LOG_USER_PROMPTS=1`, `OTEL_LOG_TOOL_DETAILS=1` e `OTEL_LOG_TOOL_CONTENT=1` per includerli.
178 178
179Quando il tracing è attivo, i sottoprocessi Bash e PowerShell ereditano automaticamente una variabile di ambiente `TRACEPARENT` contenente il contesto di traccia W3C dello span di esecuzione dello strumento attivo. Questo consente a qualsiasi sottoprocesso che legge `TRACEPARENT` di far diventare i propri span figli della stessa traccia, abilitando il tracing distribuito end-to-end attraverso script e comandi che Claude esegue.179Quando il tracing è attivo, i sottoprocessi Bash e PowerShell ereditano automaticamente una variabile d'ambiente `TRACEPARENT` contenente il contesto di traccia W3C dello span di esecuzione dello strumento attivo. Questo consente a qualsiasi sottoprocesso che legge `TRACEPARENT` di collegare i propri span come figli all'interno della stessa traccia, abilitando il tracing distribuito end-to-end attraverso gli script e i comandi eseguiti da Claude.
180 180
181Quando il tracing è attivo e Claude Code è connesso direttamente all'API Anthropic, ogni richiesta del modello porta un'intestazione W3C `traceparent` impostata al contesto dello span `claude_code.llm_request` e l'intestazione `traceresponse` dell'API viene registrata come collegamento dello span. Insieme questi collegano gli span lato client di Claude Code alla traccia lato server attraverso qualsiasi intermediario conforme. Le richieste HTTP MCP in uscita portano `traceparent` allo stesso modo. L'intestazione non viene inviata ai provider di terze parti.181Quando il tracing è attivo e Claude Code è connesso direttamente all'API di Anthropic, ogni richiesta al modello include un header W3C `traceparent` impostato sul contesto dello span `claude_code.llm_request`, e l'header `traceresponse` dell'API viene registrato come link di span. Insieme, questi collegano gli span lato client di Claude Code alla traccia lato server attraverso qualsiasi intermediario conforme. Le richieste MCP HTTP in uscita includono `traceparent` allo stesso modo. L'header non viene inviato a provider di terze parti.
182 182
183Per impostazione predefinita, l'intestazione `traceparent` sulle richieste del modello e HTTP MCP viene inviata solo quando `ANTHROPIC_BASE_URL` non è impostato o punta all'API Anthropic, poiché alcuni proxy rifiutano intestazioni non riconosciute. La variabile `TRACEPARENT` del sottoprocesso è controllata dallo stesso switch per coerenza. Se esegui Claude Code attraverso un proxy `ANTHROPIC_BASE_URL` personalizzato e desideri che il contesto di traccia sia propagato, imposta `CLAUDE_CODE_PROPAGATE_TRACEPARENT=1`.183Per impostazione predefinita, l'header `traceparent` sulle richieste al modello e sulle richieste MCP HTTP viene inviato solo quando `ANTHROPIC_BASE_URL` non è impostata o punta all'API di Anthropic, poiché alcuni proxy rifiutano header non riconosciuti. La variabile `TRACEPARENT` dei sottoprocessi è controllata dallo stesso interruttore per coerenza. Se esegui Claude Code attraverso un proxy `ANTHROPIC_BASE_URL` personalizzato e vuoi che il contesto di traccia venga propagato, imposta `CLAUDE_CODE_PROPAGATE_TRACEPARENT=1`.
184 184
185In Agent SDK e sessioni non interattive avviate con `-p`, Claude Code legge anche `TRACEPARENT` e `TRACESTATE` dal proprio ambiente quando avvia ogni span di interazione. Questo consente a un processo di incorporamento di passare il suo contesto di traccia W3C attivo nel sottoprocesso in modo che gli span di Claude Code appaiano come figli della traccia distribuita del chiamante. Le sessioni interattive ignorano `TRACEPARENT` in entrata per evitare di ereditare accidentalmente valori ambientali da ambienti CI o container.185Nell'Agent SDK e nelle sessioni non interattive avviate con `-p`, Claude Code legge anche `TRACEPARENT` e `TRACESTATE` dal proprio ambiente all'avvio di ogni span di interazione. Questo consente a un processo che incorpora Claude Code di passare il proprio contesto di traccia W3C attivo al sottoprocesso, in modo che gli span di Claude Code appaiano come figli della traccia distribuita del chiamante. Le sessioni interattive ignorano `TRACEPARENT` in ingresso per evitare di ereditare accidentalmente valori ambientali da ambienti CI o container.
186 186
187Il contesto di traccia in entrata si applica anche agli [eventi](#events). In sessioni Agent SDK e `-p` con `TRACEPARENT` impostato, ogni record di log degli eventi OTLP porta i valori `trace_id` e `span_id` che lo collegano alla traccia della tua applicazione, anche quando l'esportatore di tracce non è configurato, in modo che il tuo backend di logging possa correlare gli eventi con il resto della traccia.187Il contesto di traccia in ingresso si applica anche agli [eventi](#events). Nell'Agent SDK e nelle sessioni `-p` con `TRACEPARENT` impostata, ogni record di log degli eventi OTLP include valori `trace_id` e `span_id` che lo collegano alla traccia della tua applicazione, anche quando l'exporter delle tracce non è configurato, così il tuo backend di logging può correlare gli eventi con il resto della traccia.
188 188
189Un record emesso mentre un'interazione è attiva porta gli ID dello span di interazione, anche quando Claude Code lo emette al di fuori del contesto asincrono dello span, come in un callback di richiesta di permesso o per un record memorizzato nel buffer durante l'avvio ed esportato in seguito. Un record emesso senza uno span di interazione attivo porta direttamente gli ID `TRACEPARENT` in entrata.189Un record emesso mentre un'interazione è attiva riporta gli ID dello span di interazione, anche quando Claude Code lo emette al di fuori del contesto asincrono dello span, ad esempio in una callback di una richiesta di permesso o per un record bufferizzato durante l'avvio ed esportato in seguito. Un record emesso senza uno span di interazione attivo riporta direttamente gli ID di `TRACEPARENT` in ingresso.
190 190
191#### Gerarchia degli span191#### Gerarchia degli span
192 192
193Ogni prompt dell'utente avvia uno span radice `claude_code.interaction`. Le chiamate API, le chiamate di strumenti e le esecuzioni di hook vengono registrate come suoi figli. Gli span degli strumenti hanno due span figli propri: uno per il tempo trascorso in attesa di una decisione di autorizzazione e uno per l'esecuzione stessa. Quando lo strumento Agent, o lo strumento Task legacy, genera un subagente, gli span API e degli strumenti del subagente si annidano sotto lo span `claude_code.tool` del genitore.193Ogni prompt dell'utente avvia uno span radice `claude_code.interaction`. Le chiamate API, le chiamate agli strumenti e le esecuzioni degli hook vengono registrate come suoi figli. Gli span degli strumenti hanno a loro volta due span figli: uno per il tempo trascorso in attesa di una decisione sul permesso e uno per l'esecuzione stessa. Quando lo strumento Agent, o lo strumento Task legacy, genera un subagent, gli span API e degli strumenti del subagent vengono annidati sotto lo span `claude_code.tool` del genitore.
194 194
195```text theme={null}195```text theme={null}
196claude_code.interaction196claude_code.interaction
197├── claude_code.llm_request197├── claude_code.llm_request
198├── claude_code.hook (richiede tracing beta dettagliato)198├── claude_code.hook (requires detailed beta tracing)
199└── claude_code.tool199└── claude_code.tool
200 ├── claude_code.tool.blocked_on_user200 ├── claude_code.tool.blocked_on_user
201 ├── claude_code.tool.execution201 ├── claude_code.tool.execution
202 └── (strumento Agent) span claude_code.llm_request / claude_code.tool del subagent202 └── (Agent tool) subagent claude_code.llm_request / claude_code.tool spans
203```203```
204 204
205In sessioni Agent SDK e `claude -p`, `claude_code.interaction` stesso diventa un figlio dello span del chiamante quando `TRACEPARENT` è impostato nell'ambiente.205Nell'Agent SDK e nelle sessioni `claude -p`, `claude_code.interaction` stesso diventa figlio dello span del chiamante quando `TRACEPARENT` è impostata nell'ambiente.
206 206
207Quando un hook `PreToolUse` [rinvia una chiamata di strumento](https://code.claude.com/docs/it/hooks.md#defer-a-tool-call-for-later), Claude Code salva il contesto di traccia del turno che l'ha rinviata. Quando riprendi la sessione e lo strumento viene rieseguito, gli span dello strumento si uniscono alla traccia di quel turno precedente come figli dello span `claude_code.interaction` del turno.207Quando un hook `PreToolUse` [rinvia una chiamata a uno strumento](https://code.claude.com/docs/it/hooks.md#defer-a-tool-call-for-later), Claude Code salva il contesto di traccia del turno che l'ha rinviata. Quando riprendi la sessione e lo strumento viene rieseguito, gli span dello strumento si uniscono alla traccia di quel turno precedente come figli dello span `claude_code.interaction` del turno.
208 208
209#### Attributi degli span209#### Attributi degli span
210 210
211Ogni span porta gli [attributi standard](#standard-attributes) più un attributo `span.type` che corrisponde al suo nome. Le tabelle seguenti elencano gli attributi aggiuntivi impostati su ogni span. Gli span `llm_request`, `tool.execution` e `hook` impostano lo stato OpenTelemetry `ERROR` quando registrano un errore; gli altri span terminano sempre con lo stato `UNSET`.211Ogni span include gli [attributi standard](#standard-attributes) più un attributo `span.type` corrispondente al suo nome. Le tabelle seguenti elencano gli attributi aggiuntivi impostati su ciascuno span. Gli span `llm_request`, `tool.execution` e `hook` impostano lo stato OpenTelemetry `ERROR` quando registrano un errore; gli altri span terminano sempre con stato `UNSET`.
212 212
213**`claude_code.interaction`**213**`claude_code.interaction`**
214 214
215| Attributo | Descrizione | Controllato da |215| Attributo | Descrizione | Controllato da |
216| - | - | - |216| - | - | - |
217| `user_prompt` | Testo del prompt. Il valore è `<REDACTED>` a meno che il gate non sia impostato | `OTEL_LOG_USER_PROMPTS` |217| `user_prompt` | Testo del prompt. Il valore è `<REDACTED>` a meno che il controllo non sia impostato | `OTEL_LOG_USER_PROMPTS` |
218| `user_prompt_length` | Lunghezza del prompt in caratteri | |218| `user_prompt_length` | Lunghezza del prompt in caratteri | |
219| `interaction.sequence` | Contatore basato su 1 delle interazioni, contato per processo Claude Code piuttosto che per sessione, come descritto per [`event.sequence`](#event-correlation-attributes) | |219| `interaction.sequence` | Contatore delle interazioni a partire da 1, conteggiato per processo di Claude Code anziché per sessione, come descritto per [`event.sequence`](#event-correlation-attributes) | |
220| `parent.source` | Come lo span ha ottenuto il suo genitore di traccia: `env` quando è stato genitore sotto un `TRACEPARENT` in entrata, `none` quando ha avviato la sua traccia. Richiede Claude Code v2.1.268 o successivo | |220| `parent.source` | Come lo span ha ottenuto il suo genitore di traccia: `env` quando è stato collegato come figlio di un `TRACEPARENT` in ingresso, `none` quando ha avviato una propria traccia. Richiede Claude Code v2.1.268 o successiva | |
221| `interaction.duration_ms` | Durata wall-clock del turno | |221| `interaction.duration_ms` | Durata effettiva del turno | |
222 222
223**`claude_code.llm_request`**223**`claude_code.llm_request`**
224 224
225| Attributo | Descrizione | Controllato da |225| Attributo | Descrizione | Controllato da |
226| - | - | - |226| - | - | - |
227| `model` | Identificatore del modello | |227| `model` | Identificatore del modello | |
228| `gen_ai.system` | Sempre `anthropic`. Convenzione semantica OpenTelemetry GenAI | |228| `gen_ai.system` | Sempre `anthropic`. Convenzione semantica GenAI di OpenTelemetry | |
229| `gen_ai.request.model` | Stesso valore di `model`. Convenzione semantica OpenTelemetry GenAI | |229| `gen_ai.request.model` | Stesso valore di `model`. Convenzione semantica GenAI di OpenTelemetry | |
230| `query_source` | Sottosistema che ha emesso la richiesta, come `repl_main_thread` o un nome di subagente | `ENABLE_BETA_TRACING_DETAILED` |230| `query_source` | Sottosistema che ha emesso la richiesta, come `repl_main_thread` o il nome di un subagent | `ENABLE_BETA_TRACING_DETAILED` |
231| `query_source_safe` | Forma limitata di `query_source`, emessa indipendentemente dal fatto che il tracing beta dettagliato sia attivo, con valori come `repl_main_thread` o `agent.builtin.general-purpose`. `:` diventa `.` e gli agenti denominati dall'utente appaiono come `agent.custom`. Richiede Claude Code v2.1.268 o successivo | |231| `query_source_safe` | Forma limitata di `query_source`, emessa indipendentemente dal fatto che il tracing beta dettagliato sia attivo, con valori come `repl_main_thread` o `agent.builtin.general-purpose`. `:` diventa `.` e gli agenti con nomi scelti dall'utente appaiono come `agent.custom`. Richiede Claude Code v2.1.268 o successiva | |
232| `agent_id` | Identificatore del subagente o del compagno di squadra che ha emesso la richiesta. Assente nella sessione principale | |232| `agent_id` | Identificatore del subagent o del compagno di squadra che ha emesso la richiesta. Assente nella sessione principale | |
233| `parent_agent_id` | Identificatore dell'agente che ha generato questo. Assente per la sessione principale e per gli agenti generati direttamente da essa | |233| `parent_agent_id` | Identificatore dell'agente che ha generato questo agente. Assente per la sessione principale e per gli agenti generati direttamente da essa | |
234| `workflow.run_id` | Identificatore di esecuzione dell'esecuzione dello strumento [Workflow](https://code.claude.com/docs/it/workflows.md) che ha generato questo agente, con prefisso `wf_`. Assente per gli agenti non generati da un workflow | |234| `workflow.run_id` | Identificatore dell'esecuzione dello strumento [Workflow](https://code.claude.com/docs/it/workflows.md) che ha generato questo agente, con prefisso `wf_`. Assente per gli agenti non generati da un workflow | |
235| `workflow.name` | Nome del workflow che ha generato questo agente. I nomi creati dall'utente vengono sostituiti con `custom` a meno che il gate non sia impostato | `OTEL_LOG_TOOL_DETAILS` |235| `workflow.name` | Nome del workflow che ha generato questo agente. I nomi creati dall'utente vengono sostituiti con `custom` a meno che il controllo non sia impostato | `OTEL_LOG_TOOL_DETAILS` |
236| `speed` | `fast` o `normal` | |236| `speed` | `fast` o `normal` | |
237| `effort` | [Livello di sforzo](https://code.claude.com/docs/it/model-config.md#adjust-effort-level) applicato alla richiesta: `low`, `medium`, `high`, `xhigh` o `max`. Assente quando Claude Code non invia alcun livello di sforzo, ad esempio su un modello che non supporta lo sforzo. Richiede Claude Code v2.1.274 o successivo | |237| `effort` | [Livello di sforzo](https://code.claude.com/docs/it/model-config.md#adjust-effort-level) applicato alla richiesta: `low`, `medium`, `high`, `xhigh` o `max`. Assente quando Claude Code non invia alcun livello di sforzo, ad esempio su un modello che non supporta lo sforzo. Richiede Claude Code v2.1.274 o successiva | |
238| `llm_request.context` | `interaction`, `tool` o `standalone` a seconda dello span genitore | |238| `llm_request.context` | `interaction`, `tool` o `standalone` a seconda dello span genitore | |
239| `duration_ms` | Durata wall-clock inclusi i tentativi | |239| `duration_ms` | Durata effettiva inclusi i nuovi tentativi | |
240| `ttft_ms` | Tempo al primo token in millisecondi | |240| `ttft_ms` | Tempo al primo token in millisecondi | |
241| `first_content_ms` | Tempo dall'inizio della richiesta al primo blocco di contenuto del tentativo riuscito, in millisecondi. Assente sulle richieste che sono ricadute nel percorso non in streaming. Richiede Claude Code v2.1.268 o successivo | |241| `first_content_ms` | Tempo dall'inizio della richiesta al primo blocco di contenuto del tentativo riuscito, in millisecondi. Assente nelle richieste che sono ricadute sul percorso non in streaming. Richiede Claude Code v2.1.268 o successiva | |
242| `input_tokens` | Conteggio dei token di input dal blocco di utilizzo dell'API. Esclude i token letti dalla cache del prompt o scritti in essa, che sono riportati in `cache_read_tokens` e `cache_creation_tokens` | |242| `input_tokens` | Numero di token di input dal blocco di utilizzo dell'API. Esclude i token letti dalla cache del prompt o scritti in essa, che sono riportati in `cache_read_tokens` e `cache_creation_tokens` | |
243| `output_tokens` | Conteggio dei token di output | |243| `output_tokens` | Numero di token di output | |
244| `cache_read_tokens` | Token letti dalla cache del prompt | |244| `cache_read_tokens` | Token letti dalla cache del prompt | |
245| `cache_creation_tokens` | Token scritti nella cache del prompt | |245| `cache_creation_tokens` | Token scritti nella cache del prompt | |
246| `request_id` | ID della richiesta API. Stesso valore dell'[attributo di correlazione degli eventi](#event-correlation-attributes) `request_id` | |246| `request_id` | ID della richiesta API. Stesso valore dell'[attributo di correlazione degli eventi](#event-correlation-attributes) `request_id` | |
247| `gen_ai.response.id` | Stesso valore di `request_id`. Convenzione semantica OpenTelemetry GenAI | |247| `gen_ai.response.id` | Stesso valore di `request_id`. Convenzione semantica GenAI di OpenTelemetry | |
248| `client_request_id` | `x-client-request-id` generato dal client del tentativo finale | |248| `client_request_id` | `x-client-request-id` generato dal client per il tentativo finale | |
249| `attempt` | Tentativi totali effettuati per questa richiesta | |249| `attempt` | Numero totale di tentativi effettuati per questa richiesta | |
250| `success` | `true` o `false` | |250| `success` | `true` o `false` | |
251| `status_code` | Codice di stato HTTP quando la richiesta non è riuscita | |251| `status_code` | Codice di stato HTTP quando la richiesta non è riuscita | |
252| `error` | Messaggio di errore quando la richiesta non è riuscita | |252| `error` | Messaggio di errore quando la richiesta non è riuscita | |
253| `error_class` | Token di classe di errore breve quando la richiesta non è riuscita, come `api_timeout` o `server_overload`. Richiede Claude Code v2.1.268 o successivo | |253| `error_class` | Breve token della classe di errore quando la richiesta non è riuscita, come `api_timeout` o `server_overload`. Richiede Claude Code v2.1.268 o successiva | |
254| `response.has_tool_call` | `true` quando la risposta conteneva blocchi di tool-use | |254| `response.has_tool_call` | `true` quando la risposta conteneva blocchi di utilizzo degli strumenti | |
255| `stop_reason` | `stop_reason` della risposta API, come `end_turn`, `tool_use`, `max_tokens`, `stop_sequence`, `pause_turn` o `refusal` | |255| `stop_reason` | `stop_reason` della risposta API, come `end_turn`, `tool_use`, `max_tokens`, `stop_sequence`, `pause_turn` o `refusal` | |
256| `gen_ai.response.finish_reasons` | Stesso valore di `stop_reason`, avvolto in un array di stringhe. Convenzione semantica OpenTelemetry GenAI | |256| `gen_ai.response.finish_reasons` | Stesso valore di `stop_reason`, racchiuso in un array di stringhe. Convenzione semantica GenAI di OpenTelemetry | |
257 257
258Ogni tentativo di ripetizione viene registrato anche come evento span `gen_ai.request.attempt` con attributi `attempt` e `client_request_id`.258Ogni nuovo tentativo viene registrato anche come evento di span `gen_ai.request.attempt` con gli attributi `attempt` e `client_request_id`.
259 259
260**`claude_code.tool`**260**`claude_code.tool`**
261 261
262| Attributo | Descrizione | Controllato da |262| Attributo | Descrizione | Controllato da |
263| - | - | - |263| - | - | - |
264| `tool_name` | Nome dello strumento | |264| `tool_name` | Nome dello strumento | |
265| `tool_name_safe` | Forma di `tool_name` che non porta nomi scelti dall'utente. I nomi degli strumenti integrati passano verbatim. I nomi degli strumenti MCP appaiono come `mcp_other`, tranne i nomi degli strumenti che corrispondono a poche forme fisse, come gli strumenti `playwright` denominati `browser_*`, che passano verbatim. Richiede Claude Code v2.1.268 o successivo | |265| `tool_name_safe` | Forma di `tool_name` che non contiene nomi scelti dall'utente. I nomi degli strumenti integrati vengono riportati così come sono. I nomi degli strumenti MCP appaiono come `mcp_other`, ad eccezione dei nomi degli strumenti che corrispondono ad alcune forme fisse, come gli strumenti `playwright` denominati `browser_*`, che vengono riportati così come sono. Richiede Claude Code v2.1.268 o successiva | |
266| `bash_command_class` | Per lo strumento Bash: categoria del primo programma del comando da un elenco fisso, come `vcs` o `package_manager`. `other` per un programma al di fuori dell'elenco, `unparsed` quando la riga non può essere analizzata. Richiede Claude Code v2.1.268 o successivo | |266| `bash_command_class` | Per lo strumento Bash: categoria del primo programma del comando da un elenco fisso, come `vcs` o `package_manager`. `other` per un programma al di fuori dell'elenco, `unparsed` quando la riga non può essere analizzata. Richiede Claude Code v2.1.268 o successiva | |
267| `bash_argv0` | Per lo strumento Bash: il primo programma del comando quando è nello stesso elenco fisso, come `git` o `npm`. `other` per qualsiasi programma al di fuori dell'elenco. Richiede Claude Code v2.1.268 o successivo | |267| `bash_argv0` | Per lo strumento Bash: il primo programma del comando quando si trova nello stesso elenco fisso, come `git` o `npm`. `other` per qualsiasi programma al di fuori dell'elenco. Richiede Claude Code v2.1.268 o successiva | |
268| `duration_ms` | Durata wall-clock inclusa l'attesa di autorizzazione e l'esecuzione | |268| `duration_ms` | Durata effettiva inclusi l'attesa del permesso e l'esecuzione | |
269| `result_tokens` | Dimensione approssimativa del token del risultato dello strumento | |269| `result_tokens` | Dimensione approssimativa in token del risultato dello strumento | |
270| `agent_id` | Identificatore del subagente o del compagno di squadra che ha eseguito lo strumento. Assente nella sessione principale | |270| `agent_id` | Identificatore del subagent o del compagno di squadra che ha eseguito lo strumento. Assente nella sessione principale | |
271| `parent_agent_id` | Identificatore dell'agente che ha generato questo. Assente per la sessione principale e per gli agenti generati direttamente da essa | |271| `parent_agent_id` | Identificatore dell'agente che ha generato questo agente. Assente per la sessione principale e per gli agenti generati direttamente da essa | |
272| `workflow.run_id` | Identificatore di esecuzione dell'esecuzione dello strumento Workflow che ha generato questo agente, con prefisso `wf_`. Assente per gli agenti non generati da un workflow | |272| `workflow.run_id` | Identificatore dell'esecuzione dello strumento Workflow che ha generato questo agente, con prefisso `wf_`. Assente per gli agenti non generati da un workflow | |
273| `workflow.name` | Nome del workflow che ha generato questo agente. I nomi creati dall'utente vengono sostituiti con `custom` a meno che il gate non sia impostato | `OTEL_LOG_TOOL_DETAILS` |273| `workflow.name` | Nome del workflow che ha generato questo agente. I nomi creati dall'utente vengono sostituiti con `custom` a meno che il controllo non sia impostato | `OTEL_LOG_TOOL_DETAILS` |
274| `tool_use_id` | L'id del blocco `tool_use` del modello per questa chiamata. Corrisponde a `tool_use_id` su [tool\_result](#tool-result-event) e [tool\_decision](#tool-decision-event) eventi e nei payload dei hook, in modo da poter unire lo span a quei record | |274| `tool_use_id` | L'id del blocco `tool_use` del modello per questa chiamata. Corrisponde al `tool_use_id` negli eventi [tool\_result](#tool-result-event) e [tool\_decision](#tool-decision-event) e nei payload degli hook, così puoi collegare lo span a quei record | |
275| `gen_ai.tool.call.id` | Stesso valore di `tool_use_id`. Convenzione semantica OpenTelemetry GenAI | |275| `gen_ai.tool.call.id` | Stesso valore di `tool_use_id`. Convenzione semantica GenAI di OpenTelemetry | |
276| `file_path` | Percorso del file di destinazione per gli strumenti Read, Edit e Write | `OTEL_LOG_TOOL_DETAILS` |276| `file_path` | Percorso del file di destinazione per gli strumenti Read, Edit e Write | `OTEL_LOG_TOOL_DETAILS` |
277| `full_command` | Stringa di comando per lo strumento Bash | `OTEL_LOG_TOOL_DETAILS` |277| `full_command` | Stringa del comando per lo strumento Bash | `OTEL_LOG_TOOL_DETAILS` |
278| `skill_name` | Nome della skill per lo strumento Skill | `OTEL_LOG_TOOL_DETAILS` |278| `skill_name` | Nome della skill per lo strumento Skill | `OTEL_LOG_TOOL_DETAILS` |
279| `subagent_type` | Tipo di subagente per lo strumento Agent o lo strumento Task legacy | `OTEL_LOG_TOOL_DETAILS` |279| `subagent_type` | Tipo di subagent per lo strumento Agent o per lo strumento Task legacy | `OTEL_LOG_TOOL_DETAILS` |
280 280
281**Evento span `tool.output` su `claude_code.tool`**281**Evento di span `tool.output` su `claude_code.tool`**
282 282
283Se imposti `OTEL_LOG_TOOL_CONTENT=1`, le chiamate Read e Bash possono registrare un evento span `tool.output` sullo span `claude_code.tool`. Le chiamate Edit e Write registrano uno solo quando imposti anche `OTEL_LOG_TOOL_DETAILS=1`. Quella variabile non è limitata a quei due strumenti, quindi controlla la sua [riga nella tabella di configurazione](#common-configuration-variables) per gli argomenti che aggiunge altrove.283Se imposti `OTEL_LOG_TOOL_CONTENT=1`, le chiamate Read e Bash possono registrare un evento di span `tool.output` sullo span `claude_code.tool`. Le chiamate Edit e Write ne registrano uno solo se imposti anche `OTEL_LOG_TOOL_DETAILS=1`. Questa variabile non è limitata a questi due strumenti, quindi controlla la sua [riga nella tabella di configurazione](#common-configuration-variables) per gli argomenti che aggiunge altrove.
284 284
285Gli strumenti MCP, WebFetch e WebSearch registrano questo evento anche su Claude Code v2.1.283 o successivo.285Anche gli strumenti MCP, WebFetch e WebSearch registrano questo evento, su Claude Code v2.1.283 o successiva.
286 286
287Claude Code scrive questo evento dal ritorno riuscito di una chiamata dello strumento, quindi una chiamata che genera un errore non registra nulla, qualunque sia lo strumento. Tra le chiamate che ritornano, non registra alcun evento `tool.output` per:287Claude Code scrive questo evento dal ritorno riuscito di una chiamata a uno strumento, quindi una chiamata che genera un errore non registra nulla, qualunque sia lo strumento. Tra le chiamate che restituiscono un risultato, non registra alcun evento `tool.output` per:
288 288
289* Una chiamata a qualsiasi strumento diverso da Read, Edit, Write, Bash, WebFetch, WebSearch e strumenti MCP289* Una chiamata a qualsiasi strumento diverso da Read, Edit, Write, Bash, WebFetch, WebSearch e gli strumenti MCP
290* Una Read che ritorna qualcosa di diverso dal testo del file, come un'immagine, un PDF o una rilettura di un file il cui contenuto non è cambiato290* Una Read che restituisce qualcosa di diverso dal testo di un file, come un'immagine, un PDF o una nuova lettura di un file il cui contenuto non è cambiato
291* Una chiamata Edit o Write, a meno che non imposti anche `OTEL_LOG_TOOL_DETAILS=1`291* Una chiamata Edit o Write, a meno che tu non imposti anche `OTEL_LOG_TOOL_DETAILS=1`
292* Una chiamata WebFetch o WebSearch che Claude Code ha spostato in background durante l'esecuzione affinché un messaggio in attesa potesse raggiungere Claude. Non viene registrato nemmeno il risultato che arriva in seguito. Per sapere quando Claude Code sposta una chiamata, consulta [Quando Claude Code invia ciò che hai messo in coda](https://code.claude.com/docs/it/interactive-mode.md#when-claude-code-sends-what-you-queued) per il terminale e il [campo `priority`](https://code.claude.com/docs/it/agent-sdk/typescript#sdkusermessage) per le sessioni Agent SDK292* Una chiamata WebFetch o WebSearch che Claude Code ha spostato in background durante l'esecuzione affinché un messaggio in attesa potesse raggiungere Claude. Nemmeno il risultato che arriva in seguito viene registrato. Per sapere quando Claude Code sposta una chiamata, consulta [Quando Claude Code invia ciò che hai messo in coda](https://code.claude.com/docs/it/interactive-mode.md#when-claude-code-sends-what-you-queued) per il terminale e il [campo `priority`](https://code.claude.com/docs/it/agent-sdk/typescript#sdkusermessage) per le sessioni dell'Agent SDK
293 293
294L'evento porta questi attributi, ognuno troncato al limite di contenuto (60 KB per impostazione predefinita). `Controllato da` nomina la variabile di cui un attributo ha bisogno in aggiunta a `OTEL_LOG_TOOL_CONTENT=1`, e per Edit e Write quella variabile controlla l'evento stesso piuttosto che l'attributo.294L'evento include questi attributi, ciascuno troncato al limite del contenuto (60 KB per impostazione predefinita). `Controllato da` indica la variabile di cui un attributo ha bisogno oltre a `OTEL_LOG_TOOL_CONTENT=1`, e per Edit e Write quella variabile controlla l'evento stesso anziché l'attributo.
295 295
296| Attributo | Descrizione | Controllato da |296| Attributo | Descrizione | Controllato da |
297| - | - | - |297| - | - | - |
298| `content` | Testo che lo strumento Read ha restituito, o il testo che una chiamata Write è stata chiesta di scrivere | `OTEL_LOG_TOOL_DETAILS` per lo strumento Write |298| `content` | Testo restituito dallo strumento Read, oppure il testo che una chiamata Write doveva scrivere | `OTEL_LOG_TOOL_DETAILS` per lo strumento Write |
299| `output` | Per lo strumento Bash, l'output combinato del comando, con stderr intercalato in stdout. Per uno strumento MCP, WebFetch o WebSearch, il risultato che lo strumento ha restituito: blocchi di testo uniti da newline, con un'immagine o un documento sostituito da un segnaposto come `[image]` | |299| `output` | Per lo strumento Bash, l'output combinato del comando, con stderr intercalato in stdout. Per uno strumento MCP, WebFetch o WebSearch, il risultato restituito dallo strumento: blocchi di testo uniti da ritorni a capo, con un'immagine o un documento sostituiti da un segnaposto come `[image]` | |
300| `diff` | Patch strutturata che lo strumento Edit ha applicato | `OTEL_LOG_TOOL_DETAILS` |300| `diff` | Patch strutturata applicata dallo strumento Edit | `OTEL_LOG_TOOL_DETAILS` |
301| `file_path` | Percorso del file di destinazione per gli strumenti Read, Edit e Write, ripetendo l'attributo dello span dello stesso nome | `OTEL_LOG_TOOL_DETAILS` |301| `file_path` | Percorso del file di destinazione per gli strumenti Read, Edit e Write, che ripete l'attributo dello span con lo stesso nome | `OTEL_LOG_TOOL_DETAILS` |
302| `bash_command` | Stringa di comando per lo strumento Bash | `OTEL_LOG_TOOL_DETAILS` |302| `bash_command` | Stringa del comando per lo strumento Bash | `OTEL_LOG_TOOL_DETAILS` |
303 303
304L'attributo `tool_name` dello span genitore ti dice da quale strumento proviene un evento. Un attributo tagliato al limite di contenuto è accompagnato da `<attribute>_truncated` e `<attribute>_original_length`.304L'attributo `tool_name` dello span genitore ti indica da quale strumento proviene un evento. Un attributo troncato al limite del contenuto è accompagnato da `<attribute>_truncated` e `<attribute>_original_length`.
305 305
306**`claude_code.tool.blocked_on_user`**306**`claude_code.tool.blocked_on_user`**
307 307
308| Attributo | Descrizione | Controllato da |308| Attributo | Descrizione | Controllato da |
309| - | - | - |309| - | - | - |
310| `duration_ms` | Tempo trascorso in attesa della decisione di autorizzazione | |310| `duration_ms` | Tempo trascorso in attesa della decisione sul permesso | |
311| `decision` | `accept`, `reject` o `cancelled`, dove `cancelled` significa che Claude Code ha smesso di attendere una decisione di permesso sulla chiamata allo strumento e non l'ha eseguita | |311| `decision` | `accept`, `reject` o `cancelled`, dove `cancelled` significa che Claude Code ha smesso di attendere una decisione sul permesso per la chiamata allo strumento e non l'ha eseguita | |
312| `source` | Per un `accept` o un `reject`, da dove proviene la decisione, come `config`, `hook` o `user_temporary`, con i significati indicati nell'[evento Tool decision](#tool-decision-event). Per un `cancelled`, cosa ha terminato l'attesa prima che venisse presa una decisione, come `user_abort` | |312| `source` | Per un `accept` o un `reject`, da dove proviene la decisione, come `config`, `hook` o `user_temporary`, con i significati indicati nell'[evento di decisione dello strumento](#tool-decision-event). Per un `cancelled`, cosa ha terminato l'attesa prima che venisse presa qualsiasi decisione, come `user_abort` | |
313 313
314Una decisione `cancelled` con `source` `user_abort` significa che un messaggio che richiedeva la consegna immediata ha interrotto il turno mentre la richiesta di permesso o il controllo della [modalità auto](https://code.claude.com/docs/it/permission-modes.md#eliminate-prompts-with-auto-mode) era in sospeso. Ad esempio, durante un controllo della modalità auto, l'utente aveva un messaggio in coda e lo [ha inviato immediatamente](https://code.claude.com/docs/it/interactive-mode.md#when-claude-code-sends-what-you-queued).314Una decisione `cancelled` con `source` `user_abort` significa che un messaggio che richiedeva una consegna immediata ha interrotto il turno mentre la richiesta di permesso o il controllo della [modalità auto](https://code.claude.com/docs/it/permission-modes.md#eliminate-prompts-with-auto-mode) era in sospeso. Ad esempio, durante un controllo della modalità auto, l'utente aveva un messaggio in coda e [lo ha inviato immediatamente](https://code.claude.com/docs/it/interactive-mode.md#when-claude-code-sends-what-you-queued).
315 315
316**`claude_code.tool.execution`**316**`claude_code.tool.execution`**
317 317
318| Attributo | Descrizione | Controllato da |318| Attributo | Descrizione | Controllato da |
319| - | - | - |319| - | - | - |
320| `duration_ms` | Tempo trascorso nell'esecuzione del corpo dello strumento | |320| `duration_ms` | Tempo trascorso nell'esecuzione del corpo dello strumento | |
321| `tool_use_id` | Stesso valore dello span genitore `claude_code.tool` | |321| `tool_use_id` | Stesso valore presente sullo span genitore `claude_code.tool` | |
322| `gen_ai.tool.call.id` | Stesso valore di `tool_use_id`. Convenzione semantica OpenTelemetry GenAI | |322| `gen_ai.tool.call.id` | Stesso valore di `tool_use_id`. Convenzione semantica GenAI di OpenTelemetry | |
323| `success` | `true` o `false` | |323| `success` | `true` o `false` | |
324| `error` | Stringa di categoria di errore quando l'esecuzione non è riuscita, come `Error:ENOENT` o `ShellError`. Contiene il messaggio di errore completo quando il gate è impostato | `OTEL_LOG_TOOL_DETAILS` |324| `error` | Stringa della categoria di errore quando l'esecuzione non è riuscita, come `Error:ENOENT` o `ShellError`. Contiene invece il messaggio di errore completo quando il controllo è impostato | `OTEL_LOG_TOOL_DETAILS` |
325| `error_class` | La categoria di errore in forma di identificatore, con caratteri al di fuori di lettere, cifre e sottolineature sostituiti da `_`, come `Error_ENOENT` o `ShellError`. Porta la categoria anche quando `error` porta il messaggio completo. Richiede Claude Code v2.1.268 o successivo | |325| `error_class` | La categoria di errore in forma di identificatore, con i caratteri diversi da lettere, cifre e underscore sostituiti da `_`, come `Error_ENOENT` o `ShellError`. Riporta la categoria anche quando `error` riporta il messaggio completo. Richiede Claude Code v2.1.268 o successiva | |
326 326
327**`claude_code.hook`**327**`claude_code.hook`**
328 328
329Questo span appare solo quando il tracing beta dettagliato è attivo, il che richiede `ENABLE_BETA_TRACING_DETAILED=1` e `BETA_TRACING_ENDPOINT`, una coppia che [cambia anche dove vanno i tuoi log e le tue tracce](https://code.claude.com/docs/it/env-vars.md#variables). Imposta la coppia nella tua shell, nelle impostazioni utente o nelle impostazioni gestite; entrambe le variabili vengono ignorate nelle [impostazioni di progetto e locali](https://code.claude.com/docs/it/settings-reference.md#variables-claude-code-ignores-in-env). `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` da solo non lo produce.329Questo span appare solo quando il tracing beta dettagliato è attivo, il che richiede `ENABLE_BETA_TRACING_DETAILED=1` e `BETA_TRACING_ENDPOINT`, una coppia che [cambia anche la destinazione dei tuoi log e delle tue tracce](https://code.claude.com/docs/it/env-vars.md#variables). Imposta la coppia nella tua shell, nelle impostazioni utente o nelle impostazioni gestite; entrambe le variabili vengono ignorate nelle [impostazioni di progetto e locali](https://code.claude.com/docs/it/settings-reference.md#variables-claude-code-ignores-in-env). `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` da sola non lo produce.
330 330
331Nelle sessioni CLI interattive, il tracing beta dettagliato richiede anche che la tua organizzazione sia nella lista di autorizzazione per la funzione. Le sessioni Agent SDK e non interattive `-p` non richiedono l'autorizzazione.331Nelle sessioni CLI interattive, il tracing beta dettagliato richiede anche che la tua organizzazione sia inserita nella lista di autorizzazione per la funzionalità. L'Agent SDK e le sessioni non interattive `-p` non richiedono l'inserimento nella lista di autorizzazione.
332 332
333| Attributo | Descrizione | Controllato da |333| Attributo | Descrizione | Controllato da |
334| - | - | - |334| - | - | - |
335| `hook_event` | Tipo di evento hook, come `PreToolUse` | |335| `hook_event` | Tipo di evento dell'hook, come `PreToolUse` | |
336| `hook_name` | Nome completo dell'hook, come `PreToolUse:Write` | |336| `hook_name` | Nome completo dell'hook, come `PreToolUse:Write` | |
337| `num_hooks` | Numero di comandi hook corrispondenti eseguiti | |337| `num_hooks` | Numero di comandi hook corrispondenti eseguiti | |
338| `hook_definitions` | Configurazione dell'hook serializzata in JSON | `OTEL_LOG_TOOL_DETAILS` |338| `hook_definitions` | Configurazione degli hook serializzata in JSON | `OTEL_LOG_TOOL_DETAILS` |
339| `duration_ms` | Durata wall-clock di tutti gli hook corrispondenti | |339| `duration_ms` | Durata effettiva di tutti gli hook corrispondenti | |
340| `num_success` | Conteggio degli hook che hanno completato con successo | |340| `num_success` | Numero di hook completati con successo | |
341| `num_blocking` | Conteggio degli hook che hanno restituito una decisione di blocco | |341| `num_blocking` | Numero di hook che hanno restituito una decisione bloccante | |
342| `num_non_blocking_error` | Conteggio degli hook che non hanno avuto esito negativo senza bloccare | |342| `num_non_blocking_error` | Numero di hook che hanno restituito un errore senza bloccare | |
343| `num_cancelled` | Conteggio degli hook annullati prima del completamento | |343| `num_cancelled` | Numero di hook annullati prima del completamento | |
344 344
345**Attributi di contenuto con il tracing beta dettagliato**345**Attributi di contenuto con il tracing beta dettagliato**
346 346
347> [!NOTE]347> [!NOTE]
348>348>
349> Attributi aggiuntivi che portano contenuto come `new_context`, `system_reminders`, `system_prompt_preview`, `user_system_prompt`, `tool_input` e `response.model_output` vengono emessi solo quando il tracing beta dettagliato è attivo. Non fanno parte dello schema di span stabile.349> Ulteriori attributi che contengono contenuto, come `new_context`, `system_reminders`, `system_prompt_preview`, `user_system_prompt`, `tool_input` e `response.model_output`, vengono emessi solo quando il tracing beta dettagliato è attivo. Non fanno parte dello schema stabile degli span.
350 350
351Questi attributi compaiono sugli span seguenti, e `Controllato da` nomina la variabile di cui un attributo ha bisogno in aggiunta al tracing beta dettagliato. I valori più lunghi del limite di contenuto (60 KB per impostazione predefinita) vengono troncati.351Questi attributi appaiono sugli span seguenti, e `Controllato da` indica la variabile di cui un attributo ha bisogno oltre al tracing beta dettagliato. I valori più lunghi del limite del contenuto (60 KB per impostazione predefinita) vengono troncati.
352 352
353| Attributo | Span | Descrizione | Controllato da |353| Attributo | Span | Descrizione | Controllato da |
354| - | - | - | - |354| - | - | - | - |
355| `new_context` | `claude_code.interaction` | Il prompt dell'utente | `OTEL_LOG_USER_PROMPTS` |355| `new_context` | `claude_code.interaction` | Il prompt dell'utente | `OTEL_LOG_USER_PROMPTS` |
356| `new_context` | `claude_code.llm_request` | I nuovi messaggi dell'utente e i risultati degli strumenti inviati con la richiesta | `OTEL_LOG_USER_PROMPTS` |356| `new_context` | `claude_code.llm_request` | I nuovi messaggi dell'utente e i risultati degli strumenti inviati con la richiesta | `OTEL_LOG_USER_PROMPTS` |
357| `system_reminders` | `claude_code.llm_request` | Il testo dei [promemoria di sistema](https://code.claude.com/docs/it/glossary.md#system-reminder) tra i nuovi messaggi della richiesta | `OTEL_LOG_USER_PROMPTS` |357| `system_reminders` | `claude_code.llm_request` | Il testo dei [promemoria di sistema](https://code.claude.com/docs/it/glossary.md#system-reminder) tra i nuovi messaggi della richiesta | `OTEL_LOG_USER_PROMPTS` |
358| `system_prompt_preview` | `claude_code.llm_request` | I primi 500 caratteri del prompt di sistema completo inviato con la richiesta | `OTEL_LOG_USER_PROMPTS` |358| `system_prompt_preview` | `claude_code.llm_request` | Primi 500 caratteri del prompt di sistema completo inviato con la richiesta | `OTEL_LOG_USER_PROMPTS` |
359| `user_system_prompt` | `claude_code.llm_request` | Solo il testo del prompt di sistema che fornisci tramite l'opzione SDK `systemPrompt` o i flag `--system-prompt` e `--append-system-prompt`. Emesso una volta per sessione piuttosto che per richiesta | `OTEL_LOG_USER_PROMPTS` |359| `user_system_prompt` | `claude_code.llm_request` | Solo il testo del prompt di sistema che fornisci tramite l'opzione `systemPrompt` dell'SDK o i flag `--system-prompt` e `--append-system-prompt`. Emesso una volta per sessione anziché per richiesta | `OTEL_LOG_USER_PROMPTS` |
360| `response.model_output` | `claude_code.llm_request` | Testo della risposta del modello alla richiesta | `OTEL_LOG_USER_PROMPTS` |360| `response.model_output` | `claude_code.llm_request` | Testo della risposta del modello alla richiesta | `OTEL_LOG_USER_PROMPTS` |
361| `new_context` | `claude_code.tool` | Il risultato della chiamata allo strumento, qualunque sia lo strumento | `OTEL_LOG_TOOL_CONTENT` |361| `new_context` | `claude_code.tool` | Il risultato della chiamata allo strumento, qualunque sia lo strumento | `OTEL_LOG_TOOL_CONTENT` |
362| `tool_input` | `claude_code.tool` | L'input serializzato della chiamata allo strumento | `OTEL_LOG_TOOL_DETAILS` |362| `tool_input` | `claude_code.tool` | L'input serializzato della chiamata allo strumento | `OTEL_LOG_TOOL_DETAILS` |
363 363
364Con il tracing beta dettagliato e `OTEL_LOG_USER_PROMPTS=1`, Claude Code emette anche un evento `claude_code.system_prompt` che porta il prompt di sistema completo, troncato al limite di contenuto. Arriva la prima volta che una sessione invia ciascun prompt di sistema distinto, e di nuovo dopo la compattazione.364Con il tracing beta dettagliato e `OTEL_LOG_USER_PROMPTS=1`, Claude Code emette anche un evento `claude_code.system_prompt` che contiene il prompt di sistema completo, troncato al limite del contenuto. Arriva la prima volta che una sessione invia ciascun prompt di sistema distinto, e di nuovo dopo la compattazione.
365 365
366### Intestazioni dinamiche366### Header dinamici
367 367
368Per gli ambienti aziendali che richiedono autenticazione dinamica, puoi configurare uno script per generare intestazioni dinamicamente. Le intestazioni dinamiche si applicano solo ai protocolli `http/protobuf` e `http/json`. Con il protocollo `grpc`, Claude Code utilizza solo le variabili di intestazioni statiche, `OTEL_EXPORTER_OTLP_HEADERS` e i suoi varianti specifici per segnale.368Per gli ambienti aziendali che richiedono un'autenticazione dinamica, puoi configurare uno script per generare header in modo dinamico. Gli header dinamici si applicano solo ai protocolli `http/protobuf` e `http/json`. Con il protocollo `grpc`, Claude Code usa solo le variabili degli header statici, `OTEL_EXPORTER_OTLP_HEADERS` e le sue varianti specifiche per segnale.
369 369
370#### Configurazione delle impostazioni370#### Configurazione delle impostazioni
371 371
372Aggiungi al tuo `.claude/settings.json`, sostituendo il percorso con il tuo script:372Aggiungi al tuo `.claude/settings.json`, sostituendo il percorso con quello del tuo script:
373 373
374```json theme={null}374```json theme={null}
375{375{
377}377}
378```378```
379 379
380Il valore può essere il percorso di un file eseguibile, incluso un percorso che contiene spazi, o una riga di comando della shell con argomenti. Su Windows, il valore viene sempre eseguito attraverso la shell, quindi racchiudi tra virgolette un percorso che contiene spazi all'interno del valore JSON.380Il valore può essere il percorso di un file eseguibile, incluso un percorso che contiene spazi, oppure una riga di comando della shell con argomenti. Su Windows, il valore viene sempre eseguito tramite la shell, quindi racchiudi tra virgolette un percorso che contiene spazi all'interno del valore JSON.
381 381
382#### Requisiti dello script382#### Requisiti dello script
383 383
384Lo script deve emettere JSON valido con coppie chiave-valore di stringhe che rappresentano intestazioni HTTP:384Lo script deve produrre un JSON valido con coppie chiave-valore di tipo stringa che rappresentano gli header HTTP:
385 385
386```bash theme={null}386```bash theme={null}
387#!/bin/bash387#!/bin/bash
388# Esempio: Intestazioni multiple388# Example: Multiple headers
389echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"389echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"
390```390```
391 391
392Se l'helper non riesce o stampa output che non soddisfa questi requisiti, le esportazioni non riescono e il tuo backend di telemetria non riceve nulla dalla sessione fino a quando l'helper non funziona di nuovo. Claude Code segnala l'errore in:392Se l'helper non riesce o stampa un output che non soddisfa questi requisiti, le esportazioni non riescono e il tuo backend di telemetria non riceve nulla dalla sessione finché l'helper non funziona di nuovo. Claude Code segnala l'errore in:
393 393
394* Una notifica di avviso nelle sessioni interattive, [`otelHeadersHelper failed; telemetry is not being exported`](https://code.claude.com/docs/it/errors#otelheadershelper-failed), mostrata una volta per sessione quando l'helper non riesce per la prima volta394* Una notifica di avviso nelle sessioni interattive, [`otelHeadersHelper failed; telemetry is not being exported`](https://code.claude.com/docs/it/errors#otelheadershelper-failed), mostrata una volta per sessione quando l'helper non riesce per la prima volta
395* Output di `/status`395* L'output di `/status`
396* Il log di debug, quando si esegue con [`--debug`](https://code.claude.com/docs/it/cli-reference#cli-flags) o dopo aver eseguito `/debug` nella sessione396* Il log di debug, quando esegui con [`--debug`](https://code.claude.com/docs/it/cli-reference#cli-flags) o dopo aver eseguito `/debug` nella sessione
397* stderr, nelle sessioni non interattive avviate con `-p`397* stderr, nelle sessioni non interattive avviate con `-p`
398 398
399#### Comportamento di aggiornamento399#### Comportamento di aggiornamento
400 400
401Lo script dell'helper di intestazioni viene eseguito all'avvio e periodicamente in seguito per supportare l'aggiornamento del token. Per impostazione predefinita, lo script viene eseguito ogni 29 minuti. Personalizza l'intervallo con la variabile di ambiente `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`.401Lo script helper degli header viene eseguito all'avvio e successivamente a intervalli regolari per supportare l'aggiornamento dei token. Per impostazione predefinita, lo script viene eseguito ogni 29 minuti. Personalizza l'intervallo con la variabile d'ambiente `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`.
402 402
403### Supporto per organizzazioni multi-team403### Supporto per organizzazioni con più team
404 404
405Le organizzazioni con più team o dipartimenti possono aggiungere attributi personalizzati per distinguere tra diversi gruppi utilizzando la variabile di ambiente `OTEL_RESOURCE_ATTRIBUTES`:405Le organizzazioni con più team o reparti possono aggiungere attributi personalizzati per distinguere tra gruppi diversi usando la variabile d'ambiente `OTEL_RESOURCE_ATTRIBUTES`:
406 406
407```bash theme={null}407```bash theme={null}
408# Aggiungi attributi personalizzati per l'identificazione del team408# Add custom attributes for team identification
409export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"409export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"
410```410```
411 411
412Questi attributi personalizzati sono inclusi in tutte le metriche e gli eventi, consentendoti di:412Questi attributi personalizzati sono inclusi in tutte le metriche e in tutti gli eventi, consentendoti di:
413 413
414* Filtrare le metriche per team o dipartimento414* Filtrare le metriche per team o reparto
415* Tracciare i costi per centro di costo415* Monitorare i costi per centro di costo
416* Creare dashboard specifici del team416* Creare dashboard specifiche per team
417* Impostare avvisi per team specifici417* Configurare avvisi per team specifici
418 418
419Claude Code allega questi valori come attributi su ogni punto dati di metrica e record di evento, oltre a inviarli nel blocco di risorse OTLP. Poiché la maggior parte dei backend di metriche espone gli attributi dei punti dati come etichette interrogabili, puoi raggruppare e filtrare le metriche per le tue chiavi personalizzate direttamente. Ad eccezione degli [attributi del repository](#repository-attributes) `vcs.*`, le chiavi personalizzate non sostituiscono mai gli [attributi standard](#standard-attributes) come `user.id` o `session.id`: quando una chiave collide, Claude Code mantiene il valore integrato.419Claude Code associa questi valori come attributi su ogni datapoint delle metriche e su ogni record di evento, oltre a inviarli nel blocco delle risorse OTLP. Poiché la maggior parte dei backend di metriche espone gli attributi dei datapoint come etichette interrogabili, puoi raggruppare e filtrare le metriche direttamente in base alle tue chiavi personalizzate. Ad eccezione degli [attributi del repository](#repository-attributes) `vcs.*`, le chiavi personalizzate non sovrascrivono mai gli [attributi standard](#standard-attributes) come `user.id` o `session.id`: quando una chiave entra in conflitto, Claude Code mantiene il valore integrato.
420 420
421Ogni chiave personalizzata diventa un'etichetta su ogni serie di metriche, quindi i valori ad alta cardinalità aumentano il costo di archiviazione nel tuo backend di metriche. Per inviare attributi personalizzati nel blocco di risorse solo e ometterli dalle etichette dei punti dati, imposta `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`. Vedi [Controllo della cardinalità delle metriche](#metrics-cardinality-control).421Ogni chiave personalizzata diventa un'etichetta su ogni serie di metriche, quindi valori ad alta cardinalità aumentano i costi di archiviazione nel tuo backend di metriche. Per inviare gli attributi personalizzati solo nel blocco delle risorse e ometterli dalle etichette dei datapoint, imposta `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`. Consulta [Controllo della cardinalità delle metriche](#metrics-cardinality-control).
422 422
423> [!WARNING]423> [!WARNING]
424>424>
425> La variabile di ambiente `OTEL_RESOURCE_ATTRIBUTES` utilizza coppie chiave=valore separate da virgola con requisiti di formattazione rigorosi:425> La variabile d'ambiente `OTEL_RESOURCE_ATTRIBUTES` usa coppie key=value separate da virgole con requisiti di formattazione rigorosi:
426>426>
427> * **Nessuno spazio consentito**: i valori non possono contenere spazi. Ad esempio, `user.organizationName=My Company` non è valido427> * **Nessuno spazio consentito**: i valori non possono contenere spazi. Ad esempio, `user.organizationName=My Company` non è valido
428> * **Formato**: deve essere coppie chiave=valore separate da virgola: `key1=value1,key2=value2`428> * **Formato**: deve essere composta da coppie key=value separate da virgole: `key1=value1,key2=value2`
429> * **Caratteri consentiti**: solo caratteri US-ASCII escludendo caratteri di controllo, spazi bianchi, virgolette doppie, virgole, punti e virgola e barre rovesciate429> * **Caratteri consentiti**: solo caratteri US-ASCII esclusi i caratteri di controllo, gli spazi bianchi, le virgolette doppie, le virgole, i punti e virgola e le barre rovesciate
430> * **Caratteri speciali**: i caratteri al di fuori dell'intervallo consentito devono essere codificati in percentuale430> * **Caratteri speciali**: i caratteri al di fuori dell'intervallo consentito devono essere codificati con percent-encoding
431>431>
432> Per un valore che avrebbe bisogno di uno spazio, usa sottolineature o camelCase. I seguenti esempi impostano `org.name` con ogni forma:432> Per un valore che richiederebbe uno spazio, usa invece underscore o camelCase. Gli esempi seguenti impostano `org.name` con ciascuna forma:
433>433>
434> ```bash theme={null}434> ```bash theme={null}
435> export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"435> export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
436> export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"436> export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"
437> ```437> ```
438>438>
439> Puoi codificare in percentuale qualsiasi carattere, non solo quelli esclusi. Questo esempio codifica sia lo spazio che l'apostrofo:439> Puoi codificare con percent-encoding qualsiasi carattere, non solo quelli esclusi. Questo esempio codifica sia lo spazio sia l'apostrofo:
440>440>
441> ```bash theme={null}441> ```bash theme={null}
442> export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"442> export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"
443> ```443> ```
444>444>
445> Racchiudere i valori tra virgolette non sfugge agli spazi. Ad esempio, `org.name="My Company"` risulta nel valore letterale `"My Company"` con le virgolette incluse, non `My Company`.445> Racchiudere i valori tra virgolette non esegue l'escape degli spazi. Ad esempio, `org.name="My Company"` produce il valore letterale `"My Company"` con le virgolette incluse, non `My Company`.
446 446
447### Attribuire la telemetria alle sessioni SSH di Desktop447### Attribuire la telemetria alle sessioni SSH di Desktop
448 448
449Per vedere su quale macchina remota è stata eseguita una [sessione SSH di Desktop](https://code.claude.com/docs/it/desktop.md#ssh-sessions), assegna un nome a ciascuna macchina in un attributo personalizzato. Le metriche e gli eventi non indicano la macchina su cui è stata eseguita una sessione.449Per vedere su quale macchina remota è stata eseguita una [sessione SSH di Desktop](https://code.claude.com/docs/it/desktop.md#ssh-sessions), assegna un nome a ogni macchina in un attributo personalizzato. Le metriche e gli eventi non indicano la macchina su cui è stata eseguita una sessione.
450 450
451Su ciascuna macchina remota, aggiungi [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support) al blocco `env` che attiva la telemetria, nel [file delle impostazioni gestite letto dalla sessione](https://code.claude.com/docs/it/desktop.md#managed-settings). Scrivi il nome per esteso nel file di ciascuna macchina. Claude Code non espande il valore, quindi `host.name=$(hostname)` arriva esattamente con quei caratteri.451Su ogni macchina remota, aggiungi [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support) al blocco `env` che attiva la telemetria, nel [file delle impostazioni gestite letto dalla sessione](https://code.claude.com/docs/it/desktop.md#managed-settings). Scrivi il nome per esteso nel file di ogni macchina. Claude Code non espande il valore, quindi `host.name=$(hostname)` arriva come quei caratteri.
452 452
453L'esempio seguente assegna alla macchina il nome `build-7`:453L'esempio seguente assegna alla macchina il nome `build-7`:
454 454
465}465}
466```466```
467 467
468Quando nient'altro imposta la variabile, `host.name` arriva nel blocco di risorse, nelle sessioni SSH di Desktop e nella CLI su quella macchina. Per sapere dove altro compaiono gli attributi personalizzati, vedi [Supporto per organizzazioni multi-team](#multi-team-organization-support).468Quando nient'altro imposta la variabile, `host.name` arriva nel blocco delle risorse, nelle sessioni SSH di Desktop e nella CLI su quella macchina. Per sapere dove altro appaiono gli attributi personalizzati, consulta [Supporto per organizzazioni con più team](#multi-team-organization-support).
469 469
470Se il nome non arriva, verifica una di queste cause:470Se il nome non arriva, verifica una di queste cause:
471 471
472* **L'hai impostata sul computer che esegue Desktop**: Desktop non passa alla sessione SSH un valore impostato lì472* **L'hai impostato sul computer che esegue Desktop**: Desktop non passa alla sessione SSH un valore impostato lì
473* **L'hai esportata in un file di login**: solo le shell di login leggono un file come `/etc/profile`. Un valore che esporti lì con `export` raggiunge Claude Code quando lo avvii da una shell di login. Non raggiunge una sessione SSH di Desktop, perché Desktop non avvia Claude Code tramite una shell di login.473* **L'hai esportato in `/etc/profile` o in un altro file letto solo dalle shell di login**: il nome arriva quando esegui `claude` da una shell di login, ma non in una sessione SSH di Desktop. Desktop non avvia Claude Code tramite una shell di login. Imposta invece la variabile sotto `env` nel [file delle impostazioni gestite](https://code.claude.com/docs/it/desktop.md#managed-settings) sulla macchina remota.
474* **Un valore contiene uno spazio**: in tal caso Claude Code non copia nessuna delle chiavi su eventi o punti dati e non segnala alcun errore. [Rimuovi lo spazio dal valore](#multi-team-organization-support).474* **Un valore contiene uno spazio**: in questo caso Claude Code non copia nessuna delle chiavi su eventi o datapoint e non segnala alcun errore. [Rimuovi lo spazio dal valore](#multi-team-organization-support).
475* **Qualcos'altro imposta già la variabile**: in una sessione avviata dall'app desktop, una variabile già impostata nell'ambiente di avvio [ha la precedenza sui file di impostazioni](https://code.claude.com/docs/it/settings-reference.md#how-env-values-interact-with-your-shell). Il [log di debug](https://code.claude.com/docs/it/debug-your-config.md) indica ogni variabile ignorata. Quando una distribuzione di Desktop di terze parti [specifica un endpoint OTLP](#how-managed-settings-lock-the-otlp-destination) nell'ambiente che fornisce, quell'ambiente contiene il `OTEL_RESOURCE_ATTRIBUTES` proprio di Desktop.475* **Qualcos'altro imposta già la variabile**: in una sessione avviata dall'app desktop, una variabile già impostata nell'ambiente di avvio [ha la precedenza sui file delle impostazioni](https://code.claude.com/docs/it/settings-reference.md#how-env-values-interact-with-your-shell). Il [log di debug](https://code.claude.com/docs/it/debug-your-config.md) indica ogni variabile ignorata. Quando un deploy di Desktop di terze parti [specifica un endpoint OTLP](#how-managed-settings-lock-the-otlp-destination) nell'ambiente che fornisce, quell'ambiente include il proprio `OTEL_RESOURCE_ATTRIBUTES` di Desktop.
476 476
477### Configurazioni di esempio477### Configurazioni di esempio
478 478
479Imposta queste variabili di ambiente prima di eseguire `claude`. Ogni scenario di seguito mostra una configurazione completa, e ogni variabile è descritta sotto [Variabili di configurazione comuni](#common-configuration-variables). Per confermare che una configurazione ha avuto effetto, controlla il tuo backend per la metrica `claude_code.session.count` dopo aver avviato una sessione; la [Guida rapida](#quick-start) copre la verifica solo dei log e cosa controllare quando non arriva nulla.479Imposta queste variabili d'ambiente prima di eseguire `claude`. Ogni scenario seguente mostra una configurazione completa, e ogni variabile è descritta in [Variabili di configurazione comuni](#common-configuration-variables). Per confermare che una configurazione sia stata applicata, controlla nel tuo backend la metrica `claude_code.session.count` dopo aver avviato una sessione; la [Guida rapida](#quick-start) spiega la verifica dei soli log e cosa controllare quando non arriva nulla.
480 480
481Per il debug della console con un intervallo di esportazione di 1 secondo:481Per il debug sulla console con un intervallo di esportazione di 1 secondo:
482 482
483```bash theme={null}483```bash theme={null}
484export CLAUDE_CODE_ENABLE_TELEMETRY=1484export CLAUDE_CODE_ENABLE_TELEMETRY=1
495export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317495export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
496```496```
497 497
498Per Prometheus, raschiato da `http://localhost:9464/metrics`:498Per Prometheus, con scraping da `http://localhost:9464/metrics`:
499 499
500```bash theme={null}500```bash theme={null}
501export CLAUDE_CODE_ENABLE_TELEMETRY=1501export CLAUDE_CODE_ENABLE_TELEMETRY=1
502export OTEL_METRICS_EXPORTER=prometheus502export OTEL_METRICS_EXPORTER=prometheus
503```503```
504 504
505Su un [ambiente self-hosted](https://code.claude.com/docs/it/self-hosted-environments-reference.md#pass-through-session-child-metrics), la sessione lega la porta 9464 solo alla capacità predefinita del runner di uno. A capacità più elevate, il runner ri-espone i contatori e i gauge della sessione sul suo endpoint `/metrics` invece.505In un [ambiente self-hosted](https://code.claude.com/docs/it/self-hosted-environments-reference.md#pass-through-session-child-metrics), la sessione si associa alla porta 9464 solo con la capacità predefinita del runner pari a uno. Con una capacità superiore, il runner espone invece nuovamente i contatori e gli indicatori della sessione sul proprio endpoint `/metrics`.
506 506
507Per inviare metriche a più esportatori:507Per inviare le metriche a più exporter:
508 508
509```bash theme={null}509```bash theme={null}
510export CLAUDE_CODE_ENABLE_TELEMETRY=1510export CLAUDE_CODE_ENABLE_TELEMETRY=1
524export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317524export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317
525```525```
526 526
527Per esportare solo metriche, senza eventi o log:527Per esportare solo le metriche, senza eventi o log:
528 528
529```bash theme={null}529```bash theme={null}
530export CLAUDE_CODE_ENABLE_TELEMETRY=1530export CLAUDE_CODE_ENABLE_TELEMETRY=1
1403* `pre_tokens`: numero approssimativo di token prima della compattazione1403* `pre_tokens`: numero approssimativo di token prima della compattazione
1404* `post_tokens`: numero approssimativo di token dopo la compattazione1404* `post_tokens`: numero approssimativo di token dopo la compattazione
1405* `error`: messaggio di errore quando la compattazione non è riuscita1405* `error`: messaggio di errore quando la compattazione non è riuscita
1406* `precompute_reuse`: impostato solo quando `trigger` è `"manual"` o per una [compattazione in inattività](https://code.claude.com/docs/it/settings-reference.md#idlecompaction), che riporta `trigger` come `"auto"`. La compattazione automatica può preparare un riepilogo in background prima che la finestra di contesto si riempia, e questo attributo registra se la compattazione ha riutilizzato quel riepilogo preparato. `"hit"` significa che è stato riutilizzato; `"miss_custom_instructions"`, `"miss_hook"` e `"miss_not_ready"` indicano il motivo per cui è stato invece calcolato un nuovo riepilogo1406* `precompute_reuse`: impostato solo quando `trigger` è `"manual"`, oppure quando `trigger` è `"auto"` per una [compattazione in inattività](https://code.claude.com/docs/it/settings-reference.md#idlecompaction) in una sessione interattiva nel terminale. La compattazione automatica può preparare un riepilogo in background prima che la finestra di contesto si riempia, e questo attributo registra se la compattazione ha riutilizzato quel riepilogo preparato. `"hit"` indica che è stato riutilizzato; `"miss_custom_instructions"`, `"miss_hook"` e `"miss_not_ready"` indicano il motivo per cui è stato invece calcolato un nuovo riepilogo
1407 1407
1408#### Evento di completamento del subagent1408#### Evento di completamento del subagent
1409 1409
