Control API - logs, audit og usage
Brug FoxIDs Control API til at forespørge på diagnostiske logs, audithændelser og usage-data og til at konfigurere de logtyper, et miljø udsender. Ressourcerne har forskellige formål og adgangsrettigheder:
- Log hjælper operatører med at diagnosticere fejl, advarsler, protokolstrømme, hændelser og metrikker.
- Audit registrerer sikkerheds- og administrative handlinger, herunder loginaktivitet og Control API-anmodninger om oprettelse, opdatering og sletning.
- Usage samler aktivitet til drifts- og faktureringsanalyse.
Før du kalder disse handlinger, konfigurer Control API-godkendelse og adgangsrettigheder. Swagger forbliver den nøjagtige reference for alle forespørgselsparametre, enum-værdier, indstillinger og svarskemaer:
Forespørgselsomfang og endpoints
FoxIDs giver tre forespørgselsomfang.
| Omfang | Endpoint-base | Diagnostisk log | Audit | Usage |
|---|---|---|---|---|
| Et miljø | /api/{tenant_name}/{track_name} |
!tracklog |
!tracklogaudit |
!tracklogusage |
| Din tenant | /api/{tenant_name}/master |
!mytenantlog |
!mytenantlogaudit |
!mytenantlogusage |
| Implementeringsadministration | /api/master/master |
!tenantlog |
!tenantlogaudit |
!tenantlogusage |
Præfiks basen med FoxIDs Control-værten, for eksempel https://control.foxids.com. Skift vært for en selv-hostet implementering. Send adgangstokenet i Authorization: Bearer {access_token}-overskriften.
Miljøforespørgsler bruger miljøet fra ruten. Tenant forespørgsler kan valgfrit vælge et miljø med trackName. Forespørgsler om implementering og administration kan vælge et tenant og miljø med tenantName og trackName. Implementeringsdiagnosticeringsforespørgslen kan også omfatte anmodninger, der er afvist før tenant, og miljørouting.
Brug adgangsrettighederne track:log, track:audit eller track:usage, eventuelt begrænset til et bestemt miljø. Deployment-wide audit og usage kræver de tilsvarende master-adgangsrettigheder. Se de komplette tabeller over adgangsrettigheder.
Forespørg på diagnostiske logs
En diagnostisk loganmodning angiver fromTime og toTime som Unix-tid i sekunder. En enkelt anmodning kan højst dække 24 timer. Vælg en eller flere kategorier såsom fejl, advarsler, spor, hændelser og metrics, og brug filter til fritekstfiltrering.
Et svar indeholder op til 300 af de nyeste matchende poster. Marker responseTruncated; når det er true, skal du indsnævre tidsintervallet eller filteret og forespørge igen i stedet for at antage, at resultatet er komplet.
Application Insights understøtter ikke forespørgsel efter spor og hændelser sammen gennem denne handling. Send separate anmodninger, når begge kategorier er påkrævet. Hold tidsintervaller så snævre som praktisk muligt for at forbedre forespørgselsydeevnen og reducere mængden af returnerede følsomme data.
Forespørgselsendpoints kræver et søgbart primært loglager. De kan ikke hente logs, når deploymentets primære logoutput er standardoutput (Stdout). I den konfiguration skal du i stedet forespørge platformens container- eller værtslogsystem. FoxIDs understøtter Control-forespørgsler mod konfigurerede Application Insights- og OpenSearch-lagre.
Forespørg på audithændelser
En revisionsanmodning angiver fromTime og toTime som Unix-tid i sekunder og kan højst dække syv dage. toTime skal være lig med eller senere end fromTime. Den valgfrie filter udfører en generel fritekstsøgning på tværs af revisionsfelter og hændelsesdata.
Et svar indeholder op til 300 af de nyeste matchende revisionsbegivenheder. Markér responseTruncated, og opdel eller indsnævre forespørgslen, når et komplet resultat er påkrævet.
Revisionsbegivenheder omfatter brugervendt godkendelsesaktivitet og administrative mutationer. Control API POST-, PUT- og DELETE-handlinger revideres automatisk, mens skrivebeskyttede GET-anmodninger ikke er det. En revisionsbegivenhed kan indeholde nyttige korrelationsværdier såsom tenant, miljø, godkendelsesmetode, applikation, bruger, session, klient-IP og brugeragent, når disse værdier er tilgængelige for handlingen.
Audit er designet til at vise, hvilken handling der skete, og dens kontekst. Det er ikke en transaktionskø og bør ikke bruges som den eneste trigger til forretningskritisk synkronisering. Søgeresultater afhænger også af det konfigurerede logopbevaring og opbevaring.
Forespørg på usage
Brugsanmodninger vælger et tidsrum, en UTC-forskydning og et opsummeringsniveau. Inkluder flag bestemmer, om svaret indeholder tenants, miljøer, godkendelsesmetoder, brugere, logins, tokenanmodninger, yderligere brug og Control API-aktivitet.
Vælg det smalleste omfang og kun de mål, som forbrugeren har brug for. Dette holder svarene mindre og undgår unødvendig afsløring af tenant eller brugerdetaljer. Brug Swagger til det aktuelle tidsrum og opsummeringsværdier.
Konfigurer miljølogning
Miljølogkonfiguration bruger:
| Operation | Endpoint | Formål |
|---|---|---|
| Hent indstillinger | GET /!tracklogsetting |
Læs aktiverede diagnostiske logtyper for rutemiljøet. |
| Gem indstillinger | POST /!tracklogsetting |
Udskift miljøets logindstillinger. |
| Få streams | GET /!tracklogstreamssettings |
Læs ekstern logstrømkonfiguration. |
| Gem streams | POST /!tracklogstreamssettings |
Udskift ekstern logstrømkonfiguration. |
Indstillingerne styrer informationssporinger, kravsporinger, meddelelsessporinger og metrics. Fejl, advarsler, kritiske fejl og hændelser forbliver tilgængelige uafhængigt som beskrevet i Logføring. POST erstatter den komplette indstillingsressource; Hent den aktuelle ressource, bevar uændrede egenskaber, og gem derefter den komplette repræsentation.
En logstrøm videresender udvalgte kategorier til en ekstern destination uafhængigt af det primære loglager. Dette kan bruges til at sende et kontrolleret sæt miljølogfiler til en separat Application Insights-ressource.
Krav og meddelelsesspor kan indeholde personlige data, tokens og komplette protokolmeddelelser. Aktiver dem kun for et defineret diagnostisk behov, begræns adgangen, indstil en passende opbevaringsperiode, og sluk dem igen, når undersøgelsen er afsluttet.
Driftsvejledning
- Brug UTC Unix-tidsstempler i integrationer og anvend kun
timeOffset, hvor brugspræsentation kræver en lokal grænse. - Opdel lange undersøgelser i anmodninger inden for endpointets maksimale tidsinterval.
- Hold fritekstfiltre specifikke og undgå at stole på displaytekst som en permanent maskin-id.
- Beskyt returnerede log- og auditdata som driftsfølsomme oplysninger.
- Brug audit til at undersøge og dokumentere handlinger, ikke som erstatning for en garanteret notifikations- eller synkroniserings-API.
- Forvent, at ændringer i logindstillinger og streams auditeres, fordi de er Control API-mutationer.
Almindelige fejlsvar
400 Bad Requestnår et tidsinterval, en vælger, tenant, et miljø eller en indstillingsressource er ugyldig.401 Unauthorized, når adgangstokenet mangler eller er ugyldigt.403 Forbidden, når den, der ringer, mangler den nødvendige log-, revisions- eller brugsadgangsrettighed.404 Not Found, når det valgte miljø eller indstillingsressource ikke eksisterer.
Brug svarteksten til valideringsdetaljer og Swagger UI til de svar, der er erklæret af hver handling.