Control API: log, controllo e utilizzo

Utilizza FoxIDs Control API per eseguire query su log di diagnostica, eventi di controllo e dati di utilizzo e per configurare i tipi di log emessi da un ambiente. Queste risorse hanno scopi e diritti di accesso diversi:

I log aiutano gli operatori a diagnosticare errori, avvisi, flussi di protocollo, eventi e metriche.
Il controllo registra le azioni amministrative e di sicurezza, tra cui l'attività di accesso e le Control API richieste di creazione, aggiornamento ed eliminazione.
Utilizzo aggrega l'attività per l'analisi operativa e di fatturazione.

Prima di chiamare queste operazioni, configurare Control API i diritti di autenticazione e accesso. Swagger rimane il riferimento esatto per tutti i parametri di query, valori enum, impostazioni e schemi di risposta:

Ambito ed endpoint della query

FoxIDs fornisce tre ambiti di query.

Ambito	Base dell'endpoint	Registro diagnostico	Controllo	Utilizzo
Un ambiente	`/api/{tenant_name}/{track_name}`	`!tracklog`	`!tracklogaudit`	`!tracklogusage`
Il tuo tenant	`/api/{tenant_name}/master`	`!mytenantlog`	`!mytenantlogaudit`	`!mytenantlogusage`
Amministrazione della distribuzione	`/api/master/master`	`!tenantlog`	`!tenantlogaudit`	`!tenantlogusage`

Prefisso la base con l'host FoxIDs Control, ad esempio https://control.foxids.com. Modificare l'host per una distribuzione self-hosted. Invia il token di accesso nell'intestazione Authorization: Bearer {access_token}.

Le query sull'ambiente utilizzano l'ambiente dalla route. Tenant query possono facoltativamente selezionare un ambiente con trackName. Le query di amministrazione della distribuzione possono selezionare un tenant e un ambiente con tenantName e trackName. La query di diagnostica della distribuzione può includere anche le richieste rifiutate prima del giorno tenant e il routing dell'ambiente.

Utilizza i diritti di accesso track:log, track:audit o track:usage, facoltativamente limitati a un ambiente specifico. Il controllo e l'utilizzo a livello di distribuzione richiedono i diritti di accesso master corrispondenti. Consulta le tabelle complete sui diritti di accesso.

Interrogare i log diagnostici

Una richiesta di log diagnostico specifica fromTime e toTime come tempo Unix in secondi. Una singola richiesta può coprire al massimo 24 ore. Seleziona una o più categorie come errori, avvisi, tracce, eventi e metriche e utilizza filter per il filtraggio del testo libero.

Una risposta contiene fino a 300 delle voci corrispondenti più recenti. Controlla responseTruncated; quando è true, restringere l'intervallo di tempo o filtrare ed eseguire nuovamente la query anziché dare per scontato che il risultato sia completo.

Application Insights non supporta l'esecuzione di query su tracce ed eventi insieme tramite questa operazione. Invia richieste separate quando sono richieste entrambe le categorie. Mantieni gli intervalli di tempo quanto più ristretti possibile per migliorare le prestazioni delle query e ridurre la quantità di dati sensibili restituiti.

Gli endpoint della query richiedono un repository di log primario ricercabile. Non possono recuperare i log quando l'output del log primario della distribuzione è l'output standard (Stdout). In tale configurazione, interroga invece il contenitore della piattaforma o il sistema di registrazione dell'host. FoxIDs supporta le query di controllo sui repository Application Insights e OpenSearch configurati.

Eseguire query sugli eventi di controllo

Una richiesta di controllo specifica fromTime e toTime come tempo Unix in secondi e può coprire al massimo sette giorni. toTime deve essere uguale o successivo a fromTime. Il filter facoltativo esegue una ricerca generale a testo libero tra i campi di controllo e i dati dell'evento.

Una risposta contiene fino a 300 degli eventi di controllo corrispondenti più recenti. Seleziona responseTruncated e dividi o restringi la query quando è richiesto un risultato completo.

Gli eventi di controllo includono attività di autenticazione rivolta all'utente e mutazioni amministrative. Le azioni Control API POST, PUT e DELETE vengono controllate automaticamente, mentre le richieste GET di sola lettura no. Un evento di controllo può contenere valori di correlazione utili come tenant, ambiente, metodo di autenticazione, applicazione, utente, sessione, IP client e agente utente quando tali valori sono disponibili per l'azione.

L'audit è progettato per mostrare quale azione si è verificata e il suo contesto. Non è una coda di eventi transazionali e non deve essere utilizzata come unico trigger per la sincronizzazione fondamentale per l'azienda. I risultati della ricerca dipendono anche dal repository e dalla conservazione dei log configurati.

Utilizzo delle query

Le richieste di utilizzo selezionano un ambito temporale, un offset UTC e un livello di riepilogo. I flag di inclusione determinano se la risposta contiene tenants, ambienti, metodi di autenticazione, utenti, accessi, richieste di token, utilizzo aggiuntivo e attività Control API.

Scegli l'ambito più ristretto e solo le dimensioni necessarie al consumatore. Ciò mantiene le risposte più piccole ed evita di esporre inutilmente tenant o i dettagli dell'utente. Utilizzare Swagger per l'ambito temporale corrente e i valori di riepilogo.

Configurare la registrazione dell'ambiente

La configurazione del registro dell'ambiente utilizza:

Operazione	Punto finale	Scopo
Ottieni le impostazioni	`GET /!tracklogsetting`	Lettura dei tipi di log diagnostici abilitati per l'ambiente di instradamento.
Salva impostazioni	`POST /!tracklogsetting`	Sostituisci le impostazioni di registro dell'ambiente.
Ottieni flussi	`GET /!tracklogstreamssettings`	Leggere la configurazione del flusso di log esterno.
Salva flussi	`POST /!tracklogstreamssettings`	Sostituisci la configurazione del flusso di log esterno.

Le impostazioni controllano le tracce delle informazioni, le tracce delle attestazioni, le tracce dei messaggi e le metriche. Errori, avvisi, errori critici ed eventi rimangono disponibili in modo indipendente come descritto in Registrazione. POST sostituisce la risorsa delle impostazioni complete; ottieni la risorsa corrente, mantieni le proprietà invariate e quindi salva la rappresentazione completa.

Un flusso di log inoltra le categorie selezionate a una destinazione esterna indipendentemente dal repository di log primario. Può essere utilizzato per inviare una serie controllata di log di ambiente a una risorsa Application Insights separata.

Le tracce delle attestazioni e dei messaggi possono contenere dati personali, token e messaggi di protocollo completi. Abilitali solo per un'esigenza diagnostica definita, limita l'accesso, imposta un periodo di conservazione appropriato e disattivali nuovamente al termine dell'indagine.

Guida operativa

Utilizza i timestamp Unix UTC nelle integrazioni e applica timeOffset solo laddove la presentazione dell'utilizzo richiede un confine locale.
Suddividi le lunghe indagini in richieste entro l'intervallo di tempo massimo dell'endpoint.
Mantieni specifici i filtri di testo libero ed evita di fare affidamento sul testo visualizzato come identificatore permanente della macchina.
Proteggi i dati di registro e di controllo restituiti come informazioni sensibili dal punto di vista operativo.
Utilizza il controllo per indagare ed evidenziare le azioni, non per sostituire una notifica o una sincronizzazione garantita API.
È previsto che le modifiche alle impostazioni di registro e ai flussi vengano controllate perché sono mutazioni Control API.

Risposte agli errori comuni

400 Bad Request quando un intervallo di tempo, un selettore, tenant, un ambiente o una risorsa di impostazioni non sono validi.
401 Unauthorized quando il token di accesso manca o non è valido.
403 Forbidden quando il chiamante non dispone del diritto di accesso al registro, al controllo o all'utilizzo richiesto.
404 Not Found quando l'ambiente o la risorsa delle impostazioni selezionati non esiste.

Utilizza il corpo della risposta per i dettagli di convalida e Swagger UI per le risposte dichiarate da ciascuna operazione.