Control API - registros, auditoria e uso

Use FoxIDs Control API para consultar logs de diagnóstico, eventos de auditoria e dados de uso e para configurar os tipos de log emitidos por um ambiente. Esses recursos têm finalidades e direitos de acesso diferentes:

Registros ajudam os operadores a diagnosticar erros, avisos, fluxos de protocolo, eventos e métricas.
Auditoria registra ações administrativas e de segurança, incluindo atividades de login e Control API solicitações de criação, atualização e exclusão.
Uso agrega atividades para análise operacional e de faturamento.

Antes de chamar essas operações, configure Control API autenticação e direitos de acesso. Swagger continua sendo a referência exata para todos os parâmetros de consulta, valores de enumeração, configurações e esquemas de resposta:

Escopo e endpoints da consulta

FoxIDs fornece três escopos de consulta.

Escopo	Base de endpoint	Registro de diagnóstico	Auditoria	Uso
Um ambiente	`/api/{tenant_name}/{track_name}`	`!tracklog`	`!tracklogaudit`	`!tracklogusage`
Seu tenant	`/api/{tenant_name}/master`	`!mytenantlog`	`!mytenantlogaudit`	`!mytenantlogusage`
Administração de implantação	`/api/master/master`	`!tenantlog`	`!tenantlogaudit`	`!tenantlogusage`

Prefixe a base com o host FoxIDs Control, por exemplo https://control.foxids.com. Altere o host para uma implantação auto-hospedada. Envie o token de acesso no cabeçalho Authorization: Bearer {access_token}.

As consultas de ambiente usam o ambiente da rota. Consultas Tenant podem opcionalmente selecionar um ambiente com trackName. As consultas de administração de implementação podem selecionar um tenant e um ambiente com tenantName e trackName. A consulta de diagnóstico de implementação também pode incluir solicitações rejeitadas antes de tenant e roteamento de ambiente.

Use direitos de acesso track:log, track:audit ou track:usage, opcionalmente restritos a um ambiente específico. A auditoria e o uso em toda a implantação exigem os direitos de acesso master correspondentes. Consulte as tabelas completas de direitos de acesso.

Consultar logs de diagnóstico

Uma solicitação de log de diagnóstico especifica fromTime e toTime como tempo Unix em segundos. Uma única solicitação pode abranger no máximo 24 horas. Selecione uma ou mais categorias, como erros, avisos, rastreios, eventos e métricas, e use filter para filtragem de texto livre.

Uma resposta contém até 300 das entradas correspondentes mais recentes. Verifique responseTruncated; quando for true, restrinja o intervalo de tempo ou filtre e consulte novamente em vez de assumir que o resultado está completo.

Application Insights não oferece suporte à consulta de traces e eventos juntos por meio desta operação. Envie solicitações separadas quando ambas as categorias forem necessárias. Mantenha os intervalos de tempo tão restritos quanto possível para melhorar o desempenho da consulta e reduzir a quantidade de dados confidenciais retornados.

Os pontos de extremidade de consulta exigem um repositório de log primário pesquisável. Eles não podem recuperar logs quando a saída de log principal da implantação for a saída padrão (Stdout). Nessa configuração, consulte o contêiner da plataforma ou o sistema de log do host. FoxIDs oferece suporte a consultas de controle em repositórios Application Insights e OpenSearch configurados.

Consultar eventos de auditoria

Uma solicitação de auditoria especifica fromTime e toTime como tempo Unix em segundos e pode abranger no máximo sete dias. toTime deve ser igual ou posterior a fromTime. O filter opcional executa uma pesquisa geral de texto livre nos campos de auditoria e nos dados do evento.

Uma resposta contém até 300 dos eventos de auditoria correspondentes mais recentes. Marque responseTruncated e divida ou restrinja a consulta quando um resultado completo for necessário.

Os eventos de auditoria incluem atividades de autenticação voltadas ao usuário e mutações administrativas. As ações Control API POST, PUT e DELETE são auditadas automaticamente, enquanto as solicitações GET somente leitura não são. Um evento de auditoria pode conter valores de correlação úteis, como tenant, ambiente, método de autenticação, aplicativo, usuário, sessão, IP do cliente e agente do usuário, quando esses valores estiverem disponíveis para a ação.

A auditoria foi projetada para mostrar qual ação ocorreu e seu contexto. Não é uma fila de eventos transacionais e não deve ser usada como o único gatilho para sincronização crítica para os negócios. Os resultados da pesquisa também dependem do repositório e da retenção de log configurados.

Uso de consultas

As solicitações de uso selecionam um escopo de tempo, um deslocamento UTC e um nível de resumo. Os sinalizadores de inclusão determinam se a resposta contém tenants, ambientes, métodos de autenticação, usuários, logins, solicitações de token, uso adicional e atividade Control API.

Escolha o escopo mais estreito e apenas as dimensões necessárias ao consumidor. Isso mantém as respostas menores e evita a exposição desnecessária de tenant ou detalhes do usuário. Use Swagger para o escopo de tempo atual e os valores de resumo.

Configurar o log do ambiente

A configuração do log do ambiente usa:

Operação	Ponto final	Propósito
Obter configurações	`GET /!tracklogsetting`	Leia os tipos de log de diagnóstico habilitados para o ambiente de rota.
Salvar configurações	`POST /!tracklogsetting`	Substitua as configurações de log do ambiente.
Obtenha transmissões	`GET /!tracklogstreamssettings`	Leia a configuração do fluxo de log externo.
Salvar transmissões	`POST /!tracklogstreamssettings`	Substitua a configuração do fluxo de log externo.

As configurações controlam rastreamentos de informações, rastreamentos de declarações, rastreamentos de mensagens e métricas. Erros, avisos, erros críticos e eventos permanecem disponíveis de forma independente, conforme descrito em Logging. POST substitui o recurso de configurações completo; obtenha o recurso atual, preserve as propriedades inalteradas e salve a representação completa.

Um fluxo de log encaminha categorias selecionadas para um destino externo independentemente do repositório de log primário. Isso pode ser usado para enviar um conjunto controlado de registros de ambiente para um recurso Application Insights separado.

Os rastreamentos de declarações e mensagens podem conter dados pessoais, tokens e mensagens de protocolo completas. Ative-os apenas para uma necessidade de diagnóstico definida, restrinja o acesso, defina um período de retenção apropriado e desligue-os novamente quando a investigação for concluída.

Orientação operacional

Use carimbos de data/hora UTC Unix em integrações e aplique timeOffset somente quando a apresentação de uso exigir um limite local.
Divida investigações longas em solicitações dentro do intervalo de tempo máximo do endpoint.
Mantenha os filtros de texto livre específicos e evite depender do texto exibido como um identificador permanente da máquina.
Proteja os dados de log e auditoria retornados como informações operacionalmente confidenciais.
Use a auditoria para investigar e evidenciar ações, não para substituir uma notificação ou sincronização garantida API.
Espere que as alterações nas configurações de registro e nos fluxos sejam auditadas porque são Control API mutações.

Respostas de erros comuns

400 Bad Request quando um intervalo de tempo, seletor, tenant, ambiente ou recurso de configurações é inválido.
401 Unauthorized quando o token de acesso está ausente ou é inválido.
403 Forbidden quando o chamador não possui o registro, a auditoria ou o direito de acesso de uso necessários.
404 Not Found quando o ambiente ou recurso de configurações selecionado não existe.

Use o corpo da resposta para detalhes de validação e Swagger UI para as respostas declaradas por cada operação.