Skip to main content
Questa pagina mostra un esempio per ogni famiglia di risposte della API di telemetria. Tutti i valori sono fittizi. Per i codici di errore e il ripristino, vedi Errori API.

​
Leggi una risposta

Leggi ogni risposta in questo ordine:
  1. Leggi lo stato HTTP.
  2. Verifica che il corpo abbia la forma prevista dalla route.
  3. Verifica che ogni project_id rientri nell’ambito di progetti richiesto.
  4. Lascia invariati i valori enum canonici e gli identificatori.
  5. Segui next_action solo se il client supporta il suo code e il suo target.
  6. Tratta null, un campo omesso e una lista vuota come stati diversi.
Un 200 OK può contenere una lista vuota. Una lista di log vuota significa che nessun log corrisponde alla richiesta. Non significa che anche problemi, tracce o azioni siano vuoti. Non collegare segnali solo perché i loro timestamp sono vicini. Segui una traccia solo quando la risposta contiene il suo trace_id esatto. Un 404 e una lista vuota sono risultati diversi. Una route di lista restituisce [] quando nessun record corrisponde. Una route di dettaglio restituisce 404 con code: not_found quando non trova un record leggibile. Nessuno dei due risultati dimostra che l’ingestione non è riuscita.

​
Cosa inviare

Le risposte sono utili quanto la telemetria che invii. Invia questi valori in ogni envelope o configurazione dell’SDK:
  • release e environment.
  • Nomi stabili per servizi, azioni e metriche.
  • Il contesto di traccia quando log, span, azioni e problemi appartengono alla stessa richiesta.
  • Valori di gravità canonici: info, warning, error e critical.
  • Attributi utili al debug, senza segreti né dati personali superflui.
Vedi Invia telemetria con l’SDK e Controlla i dati acquisiti.

​
Risposta di ingestione

Gli SDK pubblici leggono la risposta di POST /v1/events al posto tuo. Il codice dell’applicazione non deve gestirla.

​
Risposta a un batch dell’SDK

Un batch dell’SDK riuscito restituisce 200 OK con il numero di elementi accettati per ogni flusso:
I conteggi riguardano solo questo batch. Un nuovo tentativo con un batch che LogBrew ha già accettato restituisce 0 per ogni flusso e il numero di eventi in already_accepted. Mantieni gli ID originali degli eventi quando riprovi.

​
Risposta all’envelope nativo

POST /api/telemetry/ingest restituisce 200 OK con il numero di elementi accettati per ogni flusso:
La risposta nativa non ha i campi metrics e context_updated. Non aggiungerli. already_accepted conta gli elementi il cui id LogBrew ha già accettato in precedenza per il progetto. Vedi l’envelope nativo diretto.

​
Errori di ingestione

Un 401 con code: ingest_key_invalid significa che il token bearer di ingestione è revocato, scaduto o non valido per il progetto. Su POST /v1/events, un token bearer mancante o che non è una chiave di ingestione restituisce 401 con code: unauthorized. Usa il token bearer di ingestione attuale, limitato al progetto. Non riprovare con un token bearer dell’account. Un batch dell’SDK rifiutato restituisce 422 con code: validation_failed:
Altri valori di error sono SDK event batch requires at least one event e SDK event type is not supported by this ingest route. Controlla la versione dell’SDK e la configurazione del trasporto. Non inviare un batch vuoto. Non cambiare tipi o ID degli eventi solo per far superare la validazione al batch. Una richiesta con un metodo diverso da POST restituisce 405 con code: method_not_allowed. Un corpo JSON illeggibile restituisce code: invalid_json.

​
Formato delle risposte di lista della telemetria

Per impostazione predefinita, le route di lista restituiscono un array JSON semplice. Una lista vuota riuscita è []. Con pagination=cursor, la route restituisce un envelope. La chiave della collezione corrisponde al segnale: next_cursor è un oggetto con i campi per continuare, oppure null sull’ultima pagina. Le righe vanno dalla più recente alla meno recente. Vedi paginazione con cursore.

​
Risposta dei log

Una pagina con cursore di log con limit=1:
I log includono level per compatibilità e severity per la visualizzazione. Entrambi contengono il valore canonico. triage contiene il risultato di una regola di gravità. Vedi risposte delle regole di gravità. trace_id e span_id sono null quando il log non ha un collegamento a una traccia. In quel caso next_action è inspect_related_logs con target telemetry_logs. Log, problemi e azioni usano le stesse 2 coppie di next_action. GET /api/logs/{log_id} restituisce un log con la stessa forma.

​
Risposta dei problemi

GET /api/telemetry/issues/{issue_id} restituisce un problema raggruppato. La lista restituisce gli stessi oggetti. Questo esempio usa la versione di risposta predefinita 1:
Nella versione 1, status è unresolved, resolved o ignored. Per un problema archiviato, triage.ignored è true. Per le coppie di next_action e le letture che seguono, vedi Indaga su un problema. first_seen_at e last_seen_at sono gli orari della prima e dell’ultima occorrenza. Non cambiano quando cambia lo stato. Alcuni campi compaiono solo quando LogBrew ha i dati: symbolication.status è resolved, invalid_metadata, artifact_not_found, source_not_resolved o unavailable. La lista, i cambi di stato e le modifiche alle regole non restituiscono symbolication. Con response_version=2, il problema ha gli stessi campi, con queste modifiche:
Questo esempio mostra solo alcuni campi. Una priorità derivata è high per error e critical, medium per warning e low per info. Usa triage.effective_severity, quindi una regola di gravità per i problemi può cambiarla. Con response_version=3, il problema ha tutti i campi della versione 2 e assignee. assignee è null quando il problema non ha un assegnatario:
Un problema non mostra alcun assegnatario quando il membro assegnato non può più leggere il progetto. Con response_version=4, assignee ha anche type. Un assegnatario user ha user_id, name ed email, come nella versione 3. Un assegnatario team ha team_id, slug e name. La versione 3 mostra un team assegnatario come null. La CLI richiede la versione 4:
Qualsiasi altro response_version restituisce 422 con code: validation_failed. Una pagina con cursore usa la stessa versione per ogni problema in issues.

​
Risposta della lista degli assegnatari

GET /api/telemetry/issues/assignees?project_id=<project_id> restituisce ogni account a cui si possono assegnare problemi nel progetto:
Aggiungi response_version=2 per ottenere anche teams: ogni team dell’organizzazione del progetto, con team_id, slug e name. Se l’account non può leggere il progetto, la route restituisce 404 con code: not_found.

​
Risposta delle azioni

distinct_id segue un attore o una sessione. Tratta distinct_id e session_id come identificatori opachi. session_id e trace_id sono null quando mancano. span_id è omesso quando manca. Un’azione non ha gravità. Vedi Eventi di prodotto.

​
Risposta delle metriche

Ogni elemento è un campione. Non usare il numero di campioni come conteggio di eventi o di utenti. unit, temporality, trace_id e span_id sono null quando mancano. Un valore null non è zero.

​
Risposta delle release

Una riga copre un progetto, una release, un ambiente e un servizio. I suoi conteggi descrivono solo quella riga. trace_health.status è unknown quando la riga non ha tracce, altrimenti no_errors_observed o errors_observed. error_rate_basis_points è la quota di tracce con uno span di errore, da 0 a 10000. Non è un tasso di errore su tutte le richieste. next_action punta al primo tipo di segnale che ha dati, in questo ordine: Vedi Release.

​
Risposta della ricerca di tracce

GET /api/telemetry/traces?pagination=cursor restituisce una riga per ogni traccia, più un resoconto naming_quality per la pagina restituita:
naming_quality copre solo la pagina restituita. Non è un punteggio dell’intero account. truncated: true significa che esiste un’altra pagina. Quando la pagina ha un nome generico, una route non riconosciuta o un’operazione generica, next_action è improve_trace_naming con target sdk_configuration. Senza pagination=cursor, la route restituisce un array semplice di tracce, senza naming_quality. next_cursor contiene time e trace_id. Inviali come cursor_time e cursor_trace_id. GET /api/telemetry/traces/{trace_id} restituisce gli span di una traccia. GET /api/telemetry/traces/{trace_id}/summary restituisce lo span radice, gli span di errore, i servizi, la durata e il percorso più lento, senza gli attributi grezzi degli span. Un 404 sul riepilogo significa che nessuna traccia corrisponde all’ambito completo. Non riprovare senza i filtri. Vedi risposte degli span e del riepilogo di una traccia.

​
Liste vuote e record mancanti

Una lettura di lista può non avere corrispondenze. Una lettura di dettaglio segue un contratto diverso: Un log mancante restituisce questo 404:
Un problema mancante usa "error": "issue not found". Un riepilogo di traccia mancante usa "error": "trace not found". Un ID sconosciuto e un ID che l’account non può leggere restituiscono la stessa risposta. Una lista con un project_id che l’account non può leggere restituisce 200 con una lista vuota. Controlla l’ID del progetto prima di segnalare che non esistono dati.

​
Selezioni di progetti rifiutate

Le liste di log, problemi, azioni, metriche, release e tracce accettano un progetto con project_id oppure da 2 a 50 progetti con project_ids. Il catalogo degli attributi dei log accetta gli stessi selettori. La cronologia delle occorrenze di un problema non li accetta. Una richiesta con sia project_id sia project_ids restituisce 422:
Anche project_ids con un UUID non valido, un ID ripetuto, meno di 2 o più di 50 ID restituisce 422 con code: validation_failed. Se l’account non può leggere uno dei progetti di un insieme project_ids, l’intera richiesta restituisce 404. Non restituisce gli altri progetti come risultato parziale:
Mostra l’errore, non una lista vuota o un conteggio pari a zero. Leggi di nuovo la lista dei progetti. Non rimuovere un progetto in silenzio e non riprovare su tutti i progetti. Una credenziale delegata, come una connessione MCP, restituisce 403 con code: forbidden per un progetto fuori dalla sua connessione. Vedi ambito del progetto.

​
Errori del cursore

Log, problemi, azioni, metriche e occorrenze dei problemi usano cursor_time e cursor_id. Un cursore rifiutato restituisce 422 con code: validation_failed. Questi errori non significano che la lista sia vuota. Per esempio:
Copia l’intero next_cursor dalla pagina precedente. Non sostituire cursor_time con l’ora attuale. Se hai perso il cursore, ricomincia con pagination=cursor e i filtri originali. Una chiave di query sconosciuta o un valore del tipo sbagliato restituisce 422 con "error": "invalid query parameters".

​
Risposte del cursore delle release

Un cursore delle release ha 5 campi. Una richiesta riuscita senza corrispondenze restituisce 200:
Quando next_cursor non è null, invia tutti e 5 i valori nella richiesta successiva: cursor_project_id indica una posizione. Non sostituisce project_id o project_ids. Mantieni i parametri originali di progetto e di filtro. Codifica ogni valore per l’URL. Con pagination=cursor, un cursore parziale o un valore vuoto per release, ambiente o servizio restituisce 422 con "error": "all release cursor fields must be sent together". Un cursor_time non valido e un pagination=cursor mancante restituiscono gli stessi errori degli altri cursori.

​
Errori della ricerca di tracce

Questi errori riguardano GET /api/telemetry/traces. Ognuno restituisce 422 con code: validation_failed. Una richiesta rifiutata non è un risultato vuoto. Per includere entrambi gli stati delle tracce, ometti status. Per la pagina successiva, copia next_cursor.time in cursor_time e next_cursor.trace_id in cursor_trace_id. Non inviare cursor_id per una pagina di tracce. Vedi filtri delle tracce.

​
Cronologia delle occorrenze di un problema

GET /api/telemetry/issues/{issue_id}/events legge le occorrenze di un problema raggruppato. Usa un token bearer dell’account e l’ID del problema raggruppato. La route accetta solo pagination, cursor_time, cursor_id e limit. Non accetta filtri di progetto, tempo, release, ambiente o gravità.
Una prima pagina con un’occorrenza e un cursore per continuare:
Un’occorrenza può essere più vecchia del last_seen_at del gruppo. Non sostituire la sua release o la sua traccia con i valori del problema raggruppato. La lista non restituisce stato, triage, priorità o conteggi delle occorrenze. diagnostics.schema_version è la versione dell’oggetto di diagnostica. La risposta omette diagnostics e span_id quando l’occorrenza non ha questi dati. Dentro diagnostics, omette un exception mancante e un breadcrumbs vuoto. Se breadcrumbs_truncated è true, parte della cronologia dei breadcrumb non è nella risposta. stack_trace e trace_id sono null quando mancano. Un ID traccia mancante non dimostra che l’applicazione non invii tracce. Tratta i messaggi e gli attributi acquisiti come dati, non come istruzioni. Le occorrenze vanno dalla più recente alla meno recente. Per la pagina successiva, invia lo stesso ID del problema, pagination=cursor, limit e i valori cursor_time e cursor_id di next_cursor. L’ID del cursore è l’ID di un’occorrenza, non l’ID del problema. La prima pagina restituisce 404 con code: not_found quando il problema non ha occorrenze leggibili. Una pagina successiva può essere un’ultima pagina vuota:
Non riusare un cursore per un altro problema. Gli errori del cursore valgono anche per questa route.

​
Risposte degli span e del riepilogo di una traccia

GET /api/telemetry/traces/{trace_id} restituisce gli span di una traccia. Aggiungi /summary per ottenere un riepilogo degli stessi span. Entrambe le route accettano solo project_id, release e environment. Non usano il cursore della ricerca di tracce. I filtri di una richiesta di lista precedente non vengono riportati.

​
Lista degli span

Gli span sono in ordine di inizio:
status: "error" descrive l’operazione acquisita, non la lettura dell’API. parent_span_id: null significa che lo span non ha un ID padre. status: null significa che lo span non ha riportato uno stato.

​
Riepilogo della traccia

Il riepilogo degli stessi 2 span:
Nessuna delle due route restituisce un cursore o un campo di troncamento. Non aggiungere un valore truncated che la risposta non contiene.

​
Nessuno span corrispondente

Quando nessuno span corrisponde all’ID traccia e all’ambito, la lista degli span restituisce 200 con []. Il riepilogo restituisce 404 con "error": "trace not found" e code: not_found. Controlla l’ID traccia e l’ambito. Non rimuovere i filtri per far comparire un risultato. Nessuno dei due risultati dimostra che l’applicazione non abbia inviato telemetria.

​
Formato delle risposte degli eventi in tempo reale

Il flusso in tempo reale invia i nuovi eventi. Non ripropone gli eventi persi dal client mentre era disconnesso. Usa le route di lista per leggere i record esistenti.

​
Crea un ticket di connessione

Invia POST /api/feed/ticket con un token bearer dell’account. La richiesta non ha corpo.
Una risposta 200 OK contiene il ticket nel campo ticket:
Il ticket è una credenziale di breve durata. Non scriverlo nei log e non metterlo nel prompt di un agente. Apri la connessione prima che finisca expires_in_seconds. La scadenza limita il momento in cui la connessione può iniziare, non quanto resta aperta. Un 401 significa che l’accesso dell’account non è valido. Accedi di nuovo prima di richiedere un ticket. Un metodo diverso da POST restituisce 405 con code: method_not_allowed.

​
Apri la connessione

Collega un client WebSocket a wss://api.logbrew.co/api/feed/live?ticket=<feed-ticket>. Codifica il ticket per l’URL. Non mettere nell’URL un token bearer dell’account o un token bearer di ingestione. Un 401 significa che il ticket o l’accesso dell’account non è valido. Crea un nuovo ticket dopo aver eseguito di nuovo l’accesso. Attendi prima di riconnetterti dopo un errore. Non riconnetterti in un ciclo stretto.

​
Leggi i messaggi

Ogni messaggio è un envelope { "type": "...", "data": ... }. Leggi type prima di analizzare data. Salta i tipi che il client non supporta.
Un evento native_issue usa la versione 1 della risposta dei problemi: un problema archiviato mostra ignored e l’evento non ha priorità. Metriche e release non sono tipi di eventi in tempo reale. Leggile con le loro route di lista. Il ticket non seleziona un progetto. Controlla il project_id di ogni evento prima di mostrarlo nella vista di un progetto. logbrew watch --json usa questo flusso. Vedi il riferimento della CLI.

​
Gestisci una connessione chiusa

Altre disconnessioni possono non avere un motivo LogBrew. Dopo esserti riconnesso, leggi di nuovo le route di lista e abbina i record per ID.

​
Esempi di risposte sullo stato dei problemi

PATCH /api/telemetry/issues/{issue_id} con { "status": "resolved" } restituisce 200 OK con il problema raggruppato aggiornato, con la stessa forma della risposta dei problemi. La chiave di query response_version seleziona la versione. Non restituisce un flag di successo. Il corpo imposta 1 o più campi tra status, priority e assignee. status accetta unresolved, resolved o archived. ignored è un vecchio nome di archived. Vedi Aggiorna un problema. Controlla id, status e priority restituiti prima di mostrare il successo. Non costruire il risultato dai valori inviati. Un cambio di stato non elimina occorrenze e non cambia first_seen_at e last_seen_at. Non cambia severity né una regola di gravità. Una modifica rifiutata restituisce 422 con code: validation_failed:
Un campo che ha già il valore richiesto non cambia. Dopo un timeout o una risposta persa, invia di nuovo la stessa richiesta oppure leggi prima il problema. Non inviare una modifica diversa prima di aver letto lo stato attuale. Vedi Scritture. POST /api/telemetry/issues/bulk restituisce 200 OK con 1 risultato per ogni ID di problema richiesto, nell’ordine della richiesta. Ogni problema trovato usa la forma della versione 3. Un risultato not_found ha issue: null:
Questo esempio mostra solo alcuni campi del problema. outcome è updated, unchanged o not_found. Una richiesta ripetuta restituisce unchanged e non cambia nulla. Vedi Aggiorna più problemi insieme. Una richiesta multipla fallisce per intero in questi casi:

​
Ambito delle richieste di analisi

Le route di analisi, la route delle serie di metriche e la route del volume dei segnali leggono un progetto e un intervallo di tempo. Ogni richiesta richiede project_id e since. since accetta una durata compatta come 24h o 7d, oppure un timestamp RFC3339. until accetta un timestamp RFC3339 e per impostazione predefinita è l’ora della richiesta. L’intervallo include since, esclude until e non può superare 31 giorni. service_name, release e environment sono filtri esatti facoltativi. Ogni valore deve avere da 1 a 256 caratteri dopo che LogBrew ha rimosso gli spazi iniziali e finali. La route di confronto dei segmenti mette questi filtri dentro ogni segmento, non al primo livello. Se l’account non può leggere il progetto, queste route restituiscono 200 OK con conteggi a zero. Non restituiscono 404. Un risultato vuoto non conferma l’accesso al progetto. Confronta project_id con i progetti che l’account può leggere. Una richiesta tramite una connessione MCP che non include il progetto restituisce 403 e forbidden. Ogni risposta inizia con schema_version, query e purpose. query riporta l’ambito effettivo. Omette i filtri che non hai inviato. purpose è un testo semplice che spiega a quale domanda risponde la route. Un tasso è omesso quando il suo denominatore è zero. Un tasso omesso non è 0 e non è null. Leggi coverage prima di fidarti di un tasso.

​
Errori comuni dell’ambito

Questi errori usano HTTP 422 e validation_failed: Per esempio, una richiesta senza project_id restituisce:
Le route delle serie di metriche e del volume dei segnali usano le stesse regole di ambito, con un proprio testo di error. Le loro sezioni più sotto elencano questi errori. Una chiave di query sconosciuta restituisce 422 come descritto in Parametri di query non validi. Un campo JSON sconosciuto, un campo JSON obbligatorio mancante o un valore enum non supportato restituisce invalid_json. Vedi JSON non valido. Una richiesta con il metodo HTTP sbagliato restituisce 405 e method_not_allowed. Il suo testo next indica il metodo e i campi supportati. Vedi Metodo non supportato.

​
Risposta della panoramica di analisi di prodotto

GET /api/telemetry/analytics/overview mostra l’attività di un progetto: volume delle azioni, utenti, sessioni, una serie temporale, le azioni principali e le visualizzazioni di pagina, le visualizzazioni di schermata e le interazioni classificate. Usala per trovare i nomi esatti degli eventi da usare nelle altre route di analisi. Invia response_version=3. Le versioni 1 e 2 restituiscono gli stessi conteggi, ma il loro valore estimation.method è un token più vecchio. La versione 1 non controlla il tipo di soggetto quando conta gli utenti identificati. Le versioni 2 e 3 contano solo i soggetti di tipo user e aggiungono i conteggi dei soggetti anonimi e subject_coverage. Questa richiesta legge un’ora in fasce temporali di cinque minuti e restituisce due righe in ogni lista dei principali:

​
Panoramica riuscita

In questo risultato fittizio, il progetto ha 120 azioni in due delle dodici fasce temporali. Venti azioni provengono da soggetti anonimi. Ogni azione ha un ID di sessione. Metà delle azioni ha un ID traccia.

​
Leggi la panoramica

I cinque conteggi di subject_coverage sommati danno il totale degli eventi della loro sezione. Solo identified_user_events conta per gli utenti. anonymous_actions è summary.actions meno identified_actions. series contiene solo le fasce temporali con attività. expected_buckets è il numero di fasce temporali possibili nell’intervallo. Non disegnare una fascia mancante come uno zero misurato, a meno che il grafico non dichiari questa regola. Le fasce temporali sono allineate ai confini degli intervalli UTC. Un intervallo che inizia dentro una fascia include quella fascia parziale. classified_activity conta visualizzazioni di pagina, visualizzazioni di schermata e interazioni. Anche le visualizzazioni di schermata e le interazioni sono azioni. Le visualizzazioni di pagina no. Non sommare summary.actions a classified_activity.summary.events. Copia kind e event_name da classified_activity.top_events nei passaggi del funnel, nei selettori di fidelizzazione, nei selettori del ciclo di vita, negli ancoraggi dei percorsi e nei target dei segmenti. Un valore true in top_events_truncated significa che esistono nomi con volume più basso. Aumenta top_limit fino a 20 per vederne altri. analysis_level è no_data, event_only, user_level o user_and_session. Se il progetto non ha azioni né eventi classificati, next_action.code è capture_product_activity. Vedi Analisi di prodotto.

​
Errori della panoramica

Oltre agli errori comuni dell’ambito, la panoramica restituisce 422 e validation_failed per questi valori: L’interval predefinito è auto. Seleziona l’intervallo più piccolo che richiede al massimo 300 fasce temporali. Il top_limit predefinito è 10.

​
Risposta del funnel ordinato

POST /api/telemetry/analytics/funnel misura il completamento in ordine di un percorso da 2 a 8 passaggi. Copia ogni kind e event_name esatto da classified_activity.top_events nella panoramica. Un nome di azione simile non è una corrispondenza. Questo corpo della richiesta conta le sessioni che visualizzano /pricing e poi completano la registrazione entro un’ora:
analysis_unit è session o identified_user. Il valore predefinito è session. Il kind di un passaggio è page_view, screen_view o interaction. La route del funnel non accetta response_version.

​
Funnel riuscito

Una risposta 200 OK:
I tassi sono frazioni da 0 a 1. Leggi coverage prima di fidarti di un tasso. selected_unit_coverage_rate è la quota di eventi dei passaggi selezionati che LogBrew ha potuto usare. La risposta non restituisce identità grezze. Vedi Analisi di prodotto.

​
Leggi conversione e copertura

entry_rate è entered_units diviso candidate_units: 50 su 60. overall_conversion_rate è completed_units diviso entered_units: 15 su 50, cioè il 30%. Non è 15 diviso tutti i candidati. Questi conteggi non spiegano perché le unità si sono fermate. La copertura conta eventi, non sessioni. Qui 120 eventi corrispondono a un passaggio e 20 di questi non hanno un ID di sessione. Il risultato esclude quei 20 eventi dai conteggi delle sessioni. Non trattarli come 20 sessioni fallite. Il primo passaggio non ha conversion_from_previous. L’ultimo passaggio non ha drop_off_to_next_units né drop_off_to_next_rate. Un’unità raggiunge un passaggio successivo solo quando gli orari dei passaggi sono strettamente crescenti. Eventi con lo stesso timestamp non possono soddisfare due passaggi consecutivi. L’ultimo passaggio deve avvenire entro conversion_window_seconds dal primo. La modalità per sessione conta sessioni, non persone. Usa identified_user solo per eventi che portano un ID soggetto opaco di tipo user. Questa modalità può unire eventi di sessioni diverse dentro la finestra di conversione. Mantieni la stessa unità e gli stessi passaggi quando confronti i risultati. Il conversion_window_seconds predefinito è 24 ore oppure la durata dell’intervallo, se più breve. Il massimo è la durata dell’intervallo in secondi interi, arrotondata per eccesso.

​
Risultati vuoti del funnel

Una risposta vuota riuscita elenca comunque i passaggi richiesti con units a zero. Se non ci sono unità candidate, summary omette entry_rate e overall_conversion_rate. La route non restituisce 404 perché nessun evento corrisponde. Leggi coverage e next_action per trovare la causa:

​
Richieste di funnel rifiutate

Oltre agli errori comuni dell’ambito, queste richieste restituiscono 422 e validation_failed. Meno di 2 o più di 8 passaggi:
Un conversion_window_seconds pari a 0, o un valore oltre la durata dell’intervallo:
Un event_name vuoto, più lungo di 256 caratteri o che contiene un carattere di controllo restituisce product analytics funnel event_name must be non-empty, control-free, and at most 256 characters. Un passaggio interaction deve anche essere un nome di azione valido. Altrimenti l’errore è product analytics interaction event_name must be a bounded stable action name. Correggi la richiesta prima di inviarla di nuovo. Non rimuovere passaggi e non cambiare l’unità di analisi solo per ottenere un risultato non vuoto.

​
Analisi per eventi esatti e automatica

Fidelizzazione e ciclo di vita accettano due forme di richiesta. Usa response_version per scegliere la forma che risponde alla tua domanda: Un selettore esatto contiene kind e event_name. kind è page_view, screen_view o interaction. Copia event_name da classified_activity.top_events. Non indovinare il nome di un evento dall’etichetta di un pulsante. Entrambe le forme contano solo gli utenti: ID soggetto opachi di tipo user. I soggetti anonimi e gli eventi senza un ID soggetto utilizzabile non contano come utenti. Le risposte non restituiscono mai ID soggetto. Gli intervalli fissi sono hour, day, week e thirty_day. Sono durate fisse. thirty_day è 30 giorni, non un mese di calendario. Se ometti interval, l’API usa hour per un intervallo di 48 ore o meno e day per un intervallo più lungo.

​
Richiesta di fidelizzazione per eventi esatti

Invia questo corpo a POST /api/telemetry/analytics/retention. Chiede se gli utenti completano un altro checkout dopo il loro primo checkout nell’intervallo:
Il primo evento iniziale corrispondente nell’intervallo fa da ancoraggio per ogni utente. Un ritorno deve avvenire strettamente dopo quell’ancoraggio e prima di until. Entrambi i selettori possono indicare lo stesso evento.

​
Fidelizzazione per eventi esatti riuscita

In questo esempio fittizio, due utenti completano il checkout. Il primo utente completa il checkout alle 12:00 del 1° giugno e di nuovo alle 13:00. Il secondo utente completa il checkout alle 12:00 del 2 giugno. Alle 13:00 del 2 giugno, il secondo utente visualizza una pagina ma non completa un altro checkout.

​
Leggi la fidelizzazione

La copertura conta tutti e quattro gli eventi classificati, ma solo tre corrispondono a ciascun selettore di checkout. La visualizzazione di pagina non conta come ritorno. Uno dei due utenti ripete il checkout, quindi return_rate_after_start è 0.5. Solo il primo utente ha un giorno intero di osservazione dopo l’ancoraggio. Quell’utente ritorna entro il giorno, quindi il tasso della curva è 1.0. Il secondo utente ha solo 12 ore di osservazione. Quell’utente non è idoneo per il periodo 0, quindi la cella della seconda coorte omette retention_rate. Non contare quell’utente come perso. weighted_retention_rate divide tutti gli utenti fidelizzati per tutti gli utenti idonei. fully_observed_cohort_average_rate è la media semplice dei tassi delle coorti in cui ogni utente è idoneo. Le coorti sono fasce temporali fisse che iniziano da since. cohorts contiene solo le coorti che hanno utenti. Con mode: "return_on_or_after", la curva omette window_end_seconds.

​
Fidelizzazione automatica

Invia response_version: 2 senza start_event né return_event. Ogni visualizzazione di pagina, visualizzazione di schermata e interazione supportata conta come inizio e come ritorno. Questa versione seleziona un insieme di eventi. Non seleziona un formato di acquisizione dell’SDK.
La risposta ha le stesse forme di summary, curve, cohorts e next_action della risposta per eventi esatti. Questo estratto mostra i campi che cambiano. In questo esempio, gli stessi due utenti hanno tre eventi e nessuna visualizzazione di pagina:
In modalità automatica, start_events e return_events sono entrambi uguali a classified_events. Questi conteggi sono eventi, non utenti.

​
Fidelizzazione senza utenti idonei

Un risultato riuscito può non avere utenti nelle coorti. Questo estratto mostra un periodo richiesto senza coorti:
Leggi coverage e next_action. Distinguono un ambito senza eventi classificati (capture_product_activity) da eventi senza utenti (identify_product_users o identify_returning_users). Un tasso mancante non è uno zero misurato.

​
Errori di fidelizzazione

Oltre agli errori comuni dell’ambito, queste richieste restituiscono 422 e validation_failed: Il limite di celle dipende dall’intervallo e dai periodi, non dal numero di utenti. Un intervallo di 30 giorni con interval: "hour" ha 720 fasce temporali di coorte. Con interval_count: 1, sono 720 celle, cioè più di 500:
Per usare la fidelizzazione automatica, rimuovi entrambi i selettori. Non modificare l’SDK per correggere questa richiesta di lettura.

​
Richiesta del ciclo di vita per un evento esatto

Invia questo corpo a POST /api/telemetry/analytics/lifecycle. Classifica gli utenti in base a un evento, non a tutta l’attività del progetto:
history_period_count imposta i periodi completi prima di since che LogBrew legge come cronologia. Accetta da 2 a 31. Il valore predefinito è 2. Un utente può essere inattivo per questo evento mentre svolge altre attività.

​
Ciclo di vita per un evento esatto riuscito

Questo esempio fittizio usa due giorni di cronologia e due giorni di analisi. Le lettere identificano solo gli utenti dell’esempio. La risposta non restituisce ID utente. Il 2 giugno C visualizza anche una pagina. Quell’evento non corrisponde al selettore di checkout.

​
Leggi il ciclo di vita

Il 1° giugno A è di ritorno, B è riattivato, C è nuovo e D è inattivo. Il 2 giugno A e B sono di ritorno, mentre C è inattivo per il checkout nonostante la visualizzazione di pagina. La variazione netta del 2 giugno è 2 - 3 = -1. In ogni fascia temporale, gli utenti nuovi, di ritorno e riattivati sommati danno active_subjects. returning_subjects più dormant_subjects è uguale a previous_active_subjects. net_active_change è active_subjects meno previous_active_subjects. Non sommare i conteggi giornalieri degli attivi per ottenere gli utenti distinti. Qui i conteggi giornalieri sommati danno 5, ma analysis_active_subjects è 3. Tra cronologia e analisi compaiono quattro utenti distinti. fully_observed è false per un’ultima fascia temporale che termina dopo until. I suoi conteggi possono cambiare quando l’intero periodo diventa osservabile. Il next_action suggerisce un’indagine. Non mostra una causa.

​
Ciclo di vita automatico

Invia response_version: 2 senza il selettore event. Ogni visualizzazione di pagina, visualizzazione di schermata e interazione supportata conta come attività:
La risposta ha le stesse forme di summary, buckets e next_action della risposta per eventi esatti. Questo estratto mostra i campi che cambiano:
In modalità automatica, coverage.selected_events è uguale a coverage.analysis_classified_events. La quinta voce di limitations è Returning, resurrected, and dormant compare any supported classified product activity; no event is ranked, selected, or inferred.

​
Ciclo di vita senza utenti

Se né l’intervallo di analisi né la cronologia contengono utenti utilizzabili, buckets è vuoto e summary omette latest_fully_observed_period:
Gli utenti che compaiono solo nella cronologia possono comunque produrre fasce temporali con utenti inattivi quando l’intervallo di analisi non ha attività.

​
Errori del ciclo di vita

Oltre agli errori comuni dell’ambito, queste richieste restituiscono 422 e validation_failed: Per esempio, dieci periodi di cronologia week richiedono 70 giorni:

​
Leggi l’ambito di analisi selezionato

Le risposte per eventi esatti hanno schema_version: 1. Il loro query riporta i selettori e omette activity_scope. Le risposte automatiche hanno schema_version: 2 e query.activity_scope: "all_classified_activity". Omettono i selettori. Un selettore diverso può cambiare il risultato anche se l’attività acquisita non cambia.

​
Risposta delle serie di metriche

GET /api/telemetry/metrics/series legge un nome di metrica esatto in un progetto. Copia il nome da GET /api/telemetry/metrics. Questa richiesta raggruppa un contatore delta per servizio:

​
Serie di metriche riuscita

Questa risposta fittizia contiene una serie di un contatore delta. Tre campioni con valori 2, 3 e 5 cadono nella prima fascia temporale. Due campioni con valori 1 e 4 cadono nell’ultima. Nessun campione cade nella fascia centrale, quindi la risposta non ha un punto per quella fascia.

​
Leggi una serie di metriche

Il primo punto registra 10 job completati, non 10 campioni. rate_per_second divide quella variazione per la fascia temporale di 300 secondi. last è l’ultima variazione registrata, non la somma. Vedi significato delle aggregazioni delle metriche. Il tipo e la temporalità di una serie determinano il suo aggregation.code e le statistiche di ogni punto. Un punto omette le statistiche che non si applicano. Una statistica mancante non è zero. limited è una risposta riuscita, non un errore. Aggiunge aggregation.limitation, che spiega perché LogBrew mostra solo valori grezzi. ready non dimostra un’acquisizione completa. Leggi coverage prima di disegnare un grafico:
  • samples conta i campioni di tutte le serie corrispondenti, incluse le serie che la risposta non restituisce.
  • series conta le serie corrispondenti. returned_series e points contano i dati restituiti.
  • truncated è true quando series_limit ha rimosso serie con volume più basso.
  • expected_buckets_per_series è il numero di fasce temporali possibili nell’intervallo.
Non aggiungere un punto per una fascia temporale senza campioni. Non inserire uno zero e non copiare il valore precedente. Ogni punto restituisce fino a 3 trace_exemplars. Un esemplare di traccia collega un campione a una traccia. Non spiega tutti i campioni della fascia temporale. Se nessun punto ha un esemplare di traccia, next_action.target è metric_samples.

​
Ambito ed errori delle serie di metriche

project_id, name e since sono obbligatori. name può avere al massimo 200 caratteri. interval è auto, 1m, 5m, 15m, 1h, 6h o 1d. Il valore predefinito è auto, che seleziona l’intervallo più piccolo con al massimo 300 fasce temporali. Un intervallo esplicito non può richiedere più di 500 fasce temporali. group_by è none, service_name, release o environment. Il valore predefinito è none. Senza raggruppamento, tipi, unità e temporalità diversi restano in serie separate. series_limit accetta da 1 a 20. Il valore predefinito è 10. Un risultato vuoto restituisce 200 con series: [] e samples a zero. L’oggetto coverage omette first_seen_at e last_seen_at. Questo non dimostra che l’applicazione non abbia mai inviato la metrica. Controlla il progetto, il nome della metrica e l’intervallo di tempo. Se ometti name, la richiesta restituisce 422:
Fasce temporali di un minuto su sette giorni restituiscono 422:
Altri errori 422 sono metric series group_by is not supported, metric series interval is not supported e metric series_limit must be between 1 and 20.

​
Risposta dell’analisi dei percorsi

POST /api/telemetry/analytics/paths trova gli eventi con nome che precedono o seguono un evento selezionato nella stessa sessione. L’evento selezionato è l’ancoraggio. Copia il suo kind e il suo event_name da classified_activity.top_events. La route restituisce schema_version: 1. Non accetta response_version né analysis_unit.
direction e anchor sono obbligatori.

​
Percorsi riusciti

In questo risultato fittizio, quattro sessioni contengono l’ancoraggio. I due percorsi restituiti rappresentano tre di quelle sessioni. Un percorso in posizione più bassa non viene restituito.

​
Leggi i percorsi

share_of_anchored_sessions divide le sessioni di un percorso per tutte e quattro le sessioni con l’ancoraggio. Le quote sono 50% e 25%, non 67% e 33%. unrepresented_sessions conta le sessioni con l’ancoraggio che nessun percorso restituito rappresenta. paths_truncated: true significa che il risultato è incompleto. La copertura conta eventi, non sessioni. Qui cinque eventi corrispondono all’ancoraggio, ma uno non ha un ID di sessione. Quell’evento non può entrare in un percorso. Ogni percorso restituisce fino a 3 esemplari di traccia. Usa un ID traccia della tua risposta. Un collegamento a una traccia non mostra che cosa ha causato un’azione dell’utente o un errore. I nodi sono in ordine temporale in entrambe le direzioni. Un percorso non è la riproduzione completa di una sessione. LogBrew legge al massimo 1024 eventi con nome per sessione prima di selezionare l’ancoraggio: i primi eventi per following e gli ultimi per preceding. Un ancoraggio fuori da questo limite può essere omesso.

​
Filtra l’ancoraggio per proprietà

Invia fino a quattro property_filters, ognuno con una key e un value esatti. Copia la chiave dal catalogo delle proprietà. I filtri si applicano solo all’ancoraggio, non agli eventi intorno. I valori distinguono tra maiuscole e minuscole. Quando ci sono filtri, query li riporta e coverage.anchor_property_filters indica: Chiavi mancanti e valori diversi richiedono correzioni diverse. Non sommarli. L’oggetto è omesso quando la richiesta non ha filtri sulle proprietà.

​
Percorsi vuoti e richieste rifiutate

Un array paths vuoto può essere una risposta 200 riuscita. Leggi summary, coverage e next_action. Questi codici distinguono le cause: capture_product_activity, choose_captured_path_anchor, capture_anchor_properties, improve_anchor_property_coverage, verify_anchor_property_values, sessionize_product_activity e narrow_or_move_path_anchor. Oltre agli errori comuni dell’ambito, queste richieste restituiscono 422 e validation_failed: Per esempio, depth: 0 restituisce:

​
Catalogo delle proprietà di analisi

GET /api/telemetry/analytics/properties elenca le chiavi delle proprietà presenti negli eventi di prodotto classificati di un progetto. Usa le chiavi nei confronti tra segmenti e nei filtri sull’ancoraggio dei percorsi. Il catalogo restituisce chiavi e conteggi. Non restituisce mai valori delle proprietà o identità.

​
Leggi le chiavi delle proprietà disponibili

Invia project_id e since. Puoi anche inviare until, service_name, release, environment, limit e response_version. limit accetta da 1 a 50 chiavi. Il valore predefinito è 20. Invia response_version=2 per ottenere il valore pubblico di estimation.method.

​
Catalogo delle proprietà riuscito

In questo risultato fittizio esistono 100 eventi classificati. Cinque di questi sono stati acquisiti prima dell’indice delle proprietà attuale.
source è standard_context per una chiave di contesto standard, come resource.runtime.name, oppure custom_tag per una chiave che inizia con tag.. value_type è sempre string. properties è ordinato per events, dal valore più alto. tag.plan è presente in 60 dei 100 eventi classificati. Ha circa 3 valori distinti. Il descrittore non mostra quei valori. Usa i valori che conosci dalla tua applicazione. Non indovinare un valore da un conteggio. Un evento può avere diverse chiavi, quindi non sommare i conteggi events delle singole chiavi. Un array properties vuoto non dimostra che il progetto non abbia eventi di prodotto. Leggi summary, coverage e next_action.

​
Errori del catalogo delle proprietà

Oltre agli errori comuni dell’ambito, limit=0 o limit=51 restituisce 422:
Un response_version diverso da 1 o 2 restituisce product analytics response_version must be 1 or 2. LogBrew controlla response_version prima degli altri valori. Una richiesta POST restituisce 405:

​
Confronto tra segmenti di analisi

POST /api/telemetry/analytics/segments/compare confronta con quale frequenza sessioni o utenti raggiungono un evento esatto in 2-4 segmenti di un progetto. Un segmento seleziona gli eventi per servizio, release, ambiente e valori delle proprietà. Il primo segmento è il riferimento.

​
Definisci il confronto

Invia questo corpo JSON con l’autenticazione dell’account e Content-Type: application/json. Qui basic e premium sono valori di piano dell’applicazione di esempio, non piani LogBrew:
target e segments sono obbligatori. analysis_unit è session o identified_user. Il valore predefinito è session, che conta sessioni, non persone. interval accetta gli stessi valori della panoramica. Il valore predefinito è auto. Ogni segmento richiede una key univoca, una label e un insieme di filtri diverso:
  • key: da 1 a 32 byte. Inizia con una lettera ASCII minuscola o con una cifra. Usa solo lettere ASCII minuscole, cifre, _ e -.
  • label: da 1 a 80 caratteri, senza caratteri di controllo.
  • service_name, release, environment: facoltativi. Ogni valore ha da 1 a 256 caratteri, senza caratteri di controllo.
  • property_filters: da 0 a 4 filtri. Ogni chiave può comparire una sola volta in un segmento. Un evento deve corrispondere a tutti i filtri del segmento. I valori distinguono tra maiuscole e minuscole, hanno da 1 a 256 caratteri e LogBrew rimuove gli spazi iniziali e finali.
Un segmento senza filtri seleziona tutta l’attività classificata del progetto nell’intervallo di tempo. I segmenti possono sovrapporsi. Un’etichetta o una chiave diversa non rende validi due insiemi di filtri identici.

​
Confronto tra segmenti riuscito

In questo risultato fittizio, il riferimento raggiunge il checkout in 10 sessioni su 50. Il segmento premium lo raggiunge in 18 sessioni su 60.

​
Leggi tassi e differenze

eligible_units stima le sessioni o gli utenti con attività classificata nel segmento. reached_units stima quanti di loro hanno raggiunto il target. reach_rate è reached_units diviso eligible_units. Gli eventi senza l’ID dell’unità selezionata non contano per queste unità. Il tasso del riferimento è 20%. Il tasso premium è 30%. La differenza è di 10 punti percentuali. L’incremento relativo è 50%, non 10%. I piccoli errori decimali derivano dall’aritmetica in virgola mobile. Arrotonda i tassi per la visualizzazione, ma calcola con i valori restituiti. Il segmento di riferimento non ha comparison_to_baseline. L’incremento relativo è omesso quando il tasso di raggiungimento del riferimento è zero. In query, un filtro di segmento che non hai inviato è null. Una lista property_filters vuota è omessa. coverage.property_filters ha gli stessi campi della copertura dei filtri sull’ancoraggio dei percorsi. Qui matching_events è uguale a classified_events. Tieni separati chiavi mancanti e valori diversi. I segmenti possono sovrapporsi e una sessione può comparire in più fasce temporali. Non sommare i conteggi delle unità tra segmenti o fasce temporali. Il confronto è descrittivo. confidence.causal_inference è not_established e confidence.statistical_significance è not_tested. Un tasso del 30% contro il 20% non dimostra che un piano abbia causato più checkout.

​
Errori del confronto tra segmenti

Oltre agli errori comuni dell’ambito, queste richieste restituiscono 422 e validation_failed: Gli errori di interval sono gli stessi degli errori della panoramica. Per esempio, due segmenti con chiavi diverse e filtri identici restituiscono:
Un’etichetta diversa o un ordine diverso dei filtri sulle proprietà non cambia gli eventi selezionati. Un errore di validazione non è una prova che nessun evento corrisponda. Una richiesta GET restituisce 405:

​
Risposta del volume dei segnali

GET /api/telemetry/summary/volume conta i segnali conservati per un progetto e un intervallo di tempo. Richiede project_id e since. Non accetta project_ids. until non può essere nel futuro. Se lo ometti, la fine è l’ora della richiesta. Un since compatto come 24h conta all’indietro da until. interval è auto, 1m, 5m, 15m, 1h, 6h o 1d. Il valore predefinito auto seleziona l’intervallo più piccolo con al massimo 120 fasce temporali. Una richiesta non può richiedere più di 500 fasce temporali. L’unico response_version è 1.

​
Conteggi dei segnali

Questa risposta fittizia copre due fasce temporali di un minuto. La richiesta è stata eseguita alle 12:02 UTC senza until. L’account ha una policy di conservazione di 30 giorni. Leggi la policy e il limite restituiti. Non dare per scontato che questi valori valgano per il tuo account.

​
Leggi ogni conteggio nella sua unità

total è la somma dei conteggi delle fasce temporali della serie. peak è il conteggio più alto di una sua fascia. non_empty_buckets conta le fasce con un conteggio superiore a zero. Le cinque serie compaiono sempre in questo ordine. Non combinare conteggi di segnali diversi in un unico punteggio di impatto. Le fasce temporali iniziano da query.since. Una fascia include il suo inizio ed esclude la sua fine. L’ultima fascia può essere più breve dell’intervallo. La risposta non ha una serie con il conteggio delle release. Non leggere release_volume_not_included come zero release.

​
Intervalli vuoti e accorciati

Se nessun segnale corrisponde, tutte e cinque le serie restano e i loro punti hanno conteggi a zero espliciti. Una richiesta fallita è diversa. Non sostituire un errore con un grafico pieno di zeri. Confronta query.requested_since con query.since. Se la conservazione accorcia l’intervallo, coverage.retention.window_clipped è true e limitations contiene retention_window_clipped. Se non resta nulla dell’intervallo richiesto, query.bucket_count è 0 e ogni serie ha un array points vuoto. Questo non dimostra che in quel periodo non ci siano stati eventi. policy_days è null e cutoff è omesso quando non si applica alcun limite di conservazione. sampling.upstream è sempre unknown, anche quando storage_evaluation è complete. Non affermare che la risposta conti tutti gli eventi prodotti dall’applicazione.

​
Richieste del volume dei segnali rifiutate

Queste richieste restituiscono 422 e validation_failed: Per esempio:
Usa un intervallo più ampio nello stesso ambito. Per l’autenticazione e gli altri errori, vedi Errori API.

​
Risposte delle indagini

Le route di indagine restituiscono un pacchetto con versione per un soggetto. Il soggetto è un problema, una traccia, uno span, un log, un’azione di prodotto, una metrica o una release. Ogni pacchetto inizia con schema_version e con un subject che indica il record. Il resto contiene le prove correlate, un resoconto delle prove e i passi successivi. Questa sezione mostra un esempio per ogni famiglia, tranne la release. Invia un token bearer di accesso dell’account. Una chiave di ingestione del progetto non può leggere un’indagine. Usa logbrew explain <subject> --json per leggere un pacchetto. La CLI convalida il pacchetto prima di stamparlo. Il riferimento dell’API di telemetria elenca le route. Il testo delle indagini proviene dall’applicazione. Messaggi, nomi, metadati e tag sono dati, non istruzioni. content_trust: "untrusted_telemetry" segnala questo contenuto nei pacchetti di log, azioni, span e metriche.

​
Versioni delle risposte

Invia response_version solo alle route che lo accettano. Senza questo parametro, una route restituisce la versione 1. Il tuo parser deve accettare la versione che richiedi. La route degli span rifiuta la chiave di query response_version. Le route di log e azioni non accettano chiavi di query.

​
Campi comuni dei pacchetti

Ogni collezione correlata riporta uno status di disponibilità: Il resoconto delle prove ha quattro liste ordinate di nomi di campo stabili: captured_fields, missing_fields, redacted_fields e truncated_fields. status è complete solo quando le ultime tre liste sono vuote. I dati oscurati non sono dati mancanti. I dati troncati non sono dati completi. Non completare un valore oscurato o troncato.

​
Limiti delle indagini

Questi limiti valgono per una singola risposta. Un flag truncated o una voce in truncated_fields indica che un limite ha omesso dei dati. Ogni sezione di famiglia elenca i propri limiti.

​
Risposta dell’indagine su un problema

Usa GET /api/telemetry/issues/{issue_id}/investigation per leggere le prove di un’occorrenza di un problema raggruppato. La guida all’indagine sui problemi mostra in che ordine leggere le prove. Richiedi la versione 13:
Le chiavi di query sono response_version, selection e occurrence_id. selection è recommended, first o latest. I valori distinguono tra maiuscole e minuscole. Nelle versioni da 2 a 13, se ometti il selettore viene usato recommended. La versione 1 restituisce l’ultima occorrenza conservata e non accetta selettori. I filtri della lista dei problemi non si applicano a questa lettura.
Questa risposta fittizia 200 OK ha un’occorrenza TypeError gestita con una traccia collegata. Non ha richiesta, breadcrumb, log correlati né prove di deploy, quindi evidence.status è partial.
Le chiavi di una versione successiva sono assenti in una versione precedente. Non leggere una chiave mancante come null. subject.status e gli stati di lifecycle indicano un problema archiviato come ignored. Le risposte di lista e di dettaglio dei problemi usano archived dalla versione di risposta 2 in poi. Limiti dei problemi: la raccomandazione legge al massimo 50 occorrenze conservate. L’andamento ha al massimo 30 fasce temporali. Ogni distribuzione restituisce al massimo 10 valori. Uno stack ha al massimo 32 frame.

​
Errori delle richieste di indagine su un problema

Usa selection oppure occurrence_id. Non inviarli entrambi, nemmeno quando selezionano la stessa occorrenza:
Un’occorrenza mancante non significa che manchi il problema. Un 404 non indica se un altro account può leggere il problema.

​
Risposta dell’indagine su una traccia

Usa GET /api/telemetry/traces/{trace_id}/investigation per leggere una traccia con il suo percorso di errore, il percorso più lento e i segnali correlati. Le chiavi di query sono response_version, project_id, release e environment. Sono tutte facoltative. Richiedi la versione 3:
La versione 2 aggiunge cause e fix a ogni problema correlato. La versione 3 aggiunge span_id a problemi, azioni e metriche correlati, quando è stato acquisito.
Questa risposta fittizia ha uno span server radice e uno span client fallito. Lo span fallito è anche lo span figlio più lento. Gli span non hanno contesto strutturato, quindi spans.context è mancante.
trace.parentage è mancante quando uno span indica un padre che LogBrew non ha conservato. L’anteprima degli span ha al massimo 64 span. Ogni percorso di analisi ha al massimo 64 span. Le letture correlate usano al massimo 8 ambiti di deploy. Una prossima azione con target trace_span indica uno span_id di questo pacchetto. Per leggere quello span, chiama la route dello span con project_id, environment e release dello span.

​
Risposta dell’indagine su uno span

Usa GET /api/telemetry/traces/{trace_id}/spans/{span_id}/investigation per leggere un’operazione in una traccia. Invia project_id, environment e release. Sono obbligatori tutti e tre. Copiali dallo span selezionato. Non inviare l’id della riga dello span come span_id.
Questa risposta fittizia descrive lo span client fallito dell’esempio della traccia. Un log di errore ha lo stesso ID span. Lo span è durato più del 95° percentile approssimativo degli span simili conservati.
Il riferimento legge le 24 ore prima dell’inizio dello span. since è incluso e until è escluso. error_rate_basis_points: 500 significa 5%. subject_percentile_basis_points: 9500 significa che il 95% degli span simili conservati non è durato più di questo span. I percentili sono approssimativi. Tieni baseline.limitations insieme ai valori. Un riferimento not_found non ha span simili conservati. Un riferimento unavailable è una lettura non riuscita, non un conteggio pari a zero. parent_chain_status: "complete" significa che la catena conservata arriva a una radice. Non dimostra che LogBrew abbia conservato tutti gli span della richiesta. La topologia restituisce al massimo 64 antenati, 50 figli diretti e 50 collegamenti tra servizi.

​
Risposta dell’indagine su un log

Usa GET /api/logs/{log_id}/investigation per leggere un log e le prove correlate. Questa route non ha chiavi di query. Copia l’ID del log da una lista di log.
La lettura può restituire prove fuori dai filtri della lista dei log. Le letture correlate usano progetto, ambiente e release del log, e i 5 minuti prima e dopo il log. Anche i log vicini usano lo stesso servizio. Non richiedono un ID traccia. Le letture sulla traccia esatta richiedono l’ID traccia del log e possono includere altri servizi. Il riepilogo della traccia usa lo stesso ID traccia e lo stesso ambito, senza l’intervallo di tempo.
Questa risposta fittizia ha un log di avviso senza contesto di traccia e un log vicino. La risposta non ricostruisce un collegamento a una traccia dai timestamp.
Un ID traccia può essere presente anche quando lo stato della traccia è not_found o unavailable. Un riepilogo della traccia disponibile non garantisce un exact_span.

​
Risposta dell’indagine su un’azione

Usa GET /api/telemetry/actions/{action_id}/investigation per leggere un’azione di prodotto, il suo stato riportato e le prove correlate. Questa route non ha chiavi di query. Le letture correlate usano lo stesso intervallo e gli stessi ambiti di un’indagine su un log.
correlations, timeline e next_actions usano le forme dell’indagine su un log. Le azioni correlate escludono l’azione oggetto dell’indagine.
Questa risposta fittizia descrive un’azione di checkout fallita di un utente che ha eseguito l’accesso. L’azione non ha un ID traccia.
La risposta non restituisce mai identificatori di soggetto o di sessione. Il resoconto delle prove elenca sempre subject.distinct_id come oscurato, e subject.session_id quando è stata acquisita una sessione. Per questo motivo ogni pacchetto di azione è partial e include improve_capture. Non rimuovere i controlli sulla privacy per soddisfarlo.

​
Risposta dell’indagine su una metrica

Usa GET /api/telemetry/metrics/investigation per leggere un nome di metrica in un progetto e in un intervallo di tempo. La risposta contiene la serie attuale, un confronto con l’intervallo precedente di pari durata, l’ultimo campione, gli esemplari di traccia e i deploy completati. La versione 2 aggiunge la descrizione della metrica presa dall’ultimo campione conservato. La versione 1 riporta sempre description_status: "not_captured".
project_id, name e since sono obbligatori. since è incluso e until è escluso. Per impostazione predefinita until è l’ora attuale. Il confronto legge anche l’intervallo precedente di pari durata.
Questo istogramma fittizio ha 5 campioni in due fasce temporali di 5 minuti. L’ultima fascia ha un p95 di 48 ms. L’ultima fascia dell’intervallo precedente ha un p95 di 24 ms.
relative_change_percent è (current - previous) / abs(previous) * 100. È null quando il valore precedente è zero o mancante. expected_buckets_per_series conta le fasce temporali possibili, non quelle con dati. Non disegnare le fasce vuote come zero. Un deploy vicino a una variazione non dimostra di averla causata. Un progetto che l’account non può leggere restituisce 200 OK con analysis.status: "no_samples", non 404. Un risultato vuoto non descrive gli altri tipi di segnale. Limiti delle metriche: l’intervallo è al massimo di 31 giorni. Ogni serie ha al massimo 500 fasce temporali. series_limit va da 1 a 20, con 10 come valore predefinito. La risposta restituisce al massimo 20 esemplari e 20 deploy. interval è auto, 1m, 5m, 15m, 1h, 6h o 1d. group_by è none, service_name, release o environment. Altri valori restituiscono 422.

​
Errori delle indagini

Un 404 significa che nessun progetto leggibile contiene il record. Ogni route restituisce anche 401 senza un’autenticazione valida e 405 per un metodo diverso da GET. Vedi Errori API per le risposte di risorsa non trovata, percorso, autenticazione e metodo. Una lettura facoltativa delle prove può fallire dentro una risposta 200 OK. In quel caso la collezione riporta unavailable. Non mostrarla come not_found o come zero record.

​
Valori di gravità

I valori di gravità mostrati agli utenti sono info, warning, error e critical. SDK e runtime possono inviare alias comuni come trace, debug, warn o fatal. Le risposte REST e in tempo reale restituiscono sempre il valore canonico. Per esempio, LogBrew accetta warn in ingresso e restituisce warning. L’ingestione rifiuta i valori di gravità sconosciuti.

​
Risposte delle regole di gravità

Una regola di gravità cambia il modo in cui LogBrew mostra un log o un problema. Non cambia la gravità acquisita dall’applicazione. Log e problemi restituiscono un oggetto triage: Usa triage.effective_severity per la visualizzazione. Mantieni severity come valore acquisito. Per impostazione predefinita, la lista dei log omette i log ignorati. Invia status=ignored o status=all su GET /api/logs per includerli. L’account deve avere il permesso di gestire i problemi nel progetto. L’accesso in lettura non basta. Senza questo permesso, una modifica alla regola restituisce 403 con code: forbidden.

​
Modifica una regola dei log

PUT /api/logs/{log_id}/triage-rule imposta la regola per il log e per i log successivi con la stessa firma. Il corpo richiede sia severity sia ignored:
Una risposta 200 OK contiene il log completo. Il suo severity resta warning. Il suo triage mostra la regola:
Questo estratto mostra solo i campi modificati. Nella richiesta, severity è source, info, warning, error o critical. source ripristina la gravità acquisita. Non riattiva un log ignorato. Per mostrare di nuovo il log, invia "ignored": false.

​
Modifica una regola dei problemi

PUT /api/telemetry/issues/{issue_id}/triage-rule imposta la gravità mostrata per un problema raggruppato e per le sue occorrenze successive. Il corpo accetta solo severity:
Una risposta 200 OK contiene il problema completo nella versione 1. Il severity acquisito e lo status non cambiano:
Questo estratto mostra solo alcuni campi. Una regola non risolve, non archivia e non riapre un problema. Per questo usa il cambio di stato. Una priorità derivata segue la nuova gravità effettiva. Leggi il problema con response_version=2 o 3 per vederla. Una gravità non supportata restituisce 422:
Un campo sconosciuto nel corpo, come status in una regola dei problemi, restituisce 422 con code: invalid_json. Un log o un problema mancante o illeggibile restituisce 404 con code: not_found. Se la risposta va persa, leggi di nuovo il log o il problema prima di inviare di nuovo la regola.

​
Formato delle risposte di errore

Gli errori dell’applicazione restituiscono un envelope JSON. Questo esempio mostra una richiesta rifiutata; il testo di error e di next dipende dall’errore:
Usa code per le diramazioni del programma e next_action per l’automazione. Mostra error e next alle persone come testo semplice. Non analizzarne la formulazione. Alcuni errori aggiungono campi, come limit, reset_at o retry_after_seconds. Una risposta senza corpo JSON non ha un code LogBrew. Vedi Errori API per tutti i codici.

​
Leggi i dati con la CLI

La CLI legge le stesse route e restituisce lo stesso JSON con --json. Inizia con una ricerca ampia, poi restringi:
Aggiungi --pagination cursor per ottenere l’envelope con cursore. La CLI richiede la versione 4 della risposta dei problemi. Vedi Leggi la pagina successiva e Monitoraggio in tempo reale.