Consultar e exibir registros

A consulta de registros no Google Distributed Cloud (GDC) com isolamento físico permite inspecionar eventos operacionais e de auditoria nas cargas de trabalho do projeto depois de coletar registros. É possível filtrar, visualizar e exportar fluxos de registros no painel de registros do Grafana com expressões da linguagem de consulta de registros (LogQL). Para fluxos de trabalho programáticos, consulte a API Log Query da sua organização por HTTP ou gRPC seguindo os métodos de acesso padrão da API.

Antes de começar

Para consultar e visualizar registros, você precisa ter as permissões necessárias.

Solicitar papéis da organização do IAM

Entre em contato com o admin. da organização do IAM para solicitar os seguintes papéis:

• Leitor do Grafana da organização (organization-grafana-viewer): visualize dados observáveis relacionados à organização nos painéis da instância de monitoramento do Grafana.
• Consultor de registros (log-query-api-querier-pa): acesse a API Log Query para consultar registros da plataforma no projeto platform-obs.

Solicitar papéis do IAM para o projeto

Entre em contato com o administrador do projeto do IAM para solicitar os seguintes papéis:

• Leitor do Grafana do projeto (project-grafana-viewer): visualize dados observáveis relacionados ao projeto nos painéis da instância de monitoramento do Grafana no namespace do projeto.
• Consultor de registros (log-query-api-querier): acessa a API Log Query para consultar registros de aplicativos no namespace do projeto.

A tabela a seguir resume os requisitos de Role para as personas de PA e AO:

Persona	Objeto	Cluster	Papel	Namespace	Grupo/Usuário
PA	grafana	servidor de API Management	project-grafana-viewer	platform-obs	Grupo
PA	log-query-api	servidor de API Management	log-query-api-querier-pa	platform-obs	Grupo
PA	grafana	servidor de API Management	project-grafana-viewer	platform-obs	Usuário
PA	log-query-api	servidor de API Management	log-query-api-querier-pa	platform-obs	Usuário
AO	grafana	servidor de API Management	project-grafana-viewer	PROJECT_NAMESPACE	Grupo
AO	log-query-api	servidor de API Management	log-query-api-querier	PROJECT_NAMESPACE	Grupo
AO	grafana	servidor de API Management	project-grafana-viewer	PROJECT_NAMESPACE	Usuário
AO	log-query-api	servidor de API Management	log-query-api-querier	PROJECT_NAMESPACE	Usuário

Selecione uma das configurações a seguir para conceder ao Grafana acesso a um grupo de usuários (Config 1) ou a um usuário individual (Config 2) no servidor da API de gerenciamento. Para cada configuração, execute o comando kubectl para criar o RoleBinding diretamente ou salve o manifesto YAML de RoleBinding no caminho do arquivo de infraestrutura como código (IaC) especificado para aplicá-lo pelo GitOps:

Importante: antes de confirmar a configuração no repositório de IaC, verifique se o arquivo kustomization.yaml existe na pasta em que você cria o arquivo YAML.

Configuração 1

Essa configuração concede permissões a um grupo de usuários para acessar o Grafana de PA e AO no servidor de API Management. Depois de definir essa configuração, consulte a seção Painéis do Grafana deste documento para ver os registros no Grafana.

• Comando kubectl

  Execute o seguinte comando para criar o RoleBinding diretamente:

  kubectl --kubeconfig KUBECONFIG create rolebinding RULE_NAME -n platform-obs --group=GROUP_NAME --role=project-grafana-viewer
  

  Exemplo:

  kubectl --kubeconfig KUBECONFIG_PATH create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --group=my-team --namespace=platform-obs
  

• Caminho do arquivo de IaC

  Como alternativa, para gerenciar o RoleBinding usando IaC, crie o arquivo YAML no seguinte caminho:

  /infrastructure/zonal/zones/ZONE/org-admin/rolebindings/GROUP_NAME/YAML_FILE
  

• Arquivo YAML

  Salve o seguinte manifesto RoleBinding no arquivo YAML no caminho do arquivo IaC:

  apiVersion: rbac.authorization.k8s.io/v1
  kind: RoleBinding
  metadata:
    name: RULE_NAME
    namespace: platform-obs
  subjects:
  - kind: Group
    name: GROUP_NAME
    apiGroup: rbac.authorization.k8s.io
  roleRef:
    kind: Role
    name: project-grafana-viewer
    apiGroup: rbac.authorization.k8s.io
  

Configuração 2

Essa configuração concede permissões para um usuário acessar o PA e o AO Grafana no servidor da API de gerenciamento. Depois de definir essa configuração, consulte a seção Painéis do Grafana deste documento para ver os registros no Grafana.

• Comando kubectl

  Execute o seguinte comando para criar o RoleBinding diretamente:

  kubectl --kubeconfig KUBECONFIG create rolebinding RULE_NAME -n platform-obs --user=EMAIL_ADDRESS --role=project-grafana-viewer
  

  Exemplo:

  kubectl --kubeconfig KUBECONFIG_PATH create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --user=[e-mail] --namespace=platform-obs
  

• Caminho do arquivo de IaC

  Como alternativa, para gerenciar o RoleBinding usando IaC, crie o arquivo YAML no seguinte caminho:

  /infrastructure/zonal/zones/ZONE/org-admin/rolebindings/EMAIL_ADDRESS/YAML_FILE
  

• Arquivo YAML

  Salve o seguinte manifesto RoleBinding no arquivo YAML no caminho do arquivo IaC:

  apiVersion: rbac.authorization.k8s.io/v1
  kind: RoleBinding
  metadata:
    name: RULE_NAME
    namespace: platform-obs
  subjects:
  - kind: User
    name: EMAIL_ADDRESS
    apiGroup: rbac.authorization.k8s.io
  roleRef:
    kind: Role
    name: project-grafana-viewer
    apiGroup: rbac.authorization.k8s.io
  

Substitua:

• KUBECONFIG: o caminho para o arquivo kubeconfig do cluster específico que contém o NAMESPACE em que esse RoleBinding é aplicado.
• KUBECONFIG_PATH: o caminho para o arquivo kubeconfig nos comandos de exemplo.
• RULE_NAME: o nome exclusivo desse recurso RoleBinding no namespace, como pa-project-grafana-viewer.
• NAMESPACE: o namespace do Kubernetes em que o RoleBinding é criado e aplicado. Procure a coluna Namespace na tabela anterior.
• EMAIL_ADDRESS: o identificador do usuário que está recebendo o papel, como [e-mail].
• ROLE: o nome do Role que contém as permissões que você quer conceder ao usuário. Procure os papéis disponíveis na tabela anterior.
• GROUP_NAME: o nome do Group ao qual o usuário do PA pertence, como pa-group.
• ZONE: o nome da zona.
• YAML_FILE: o nome do arquivo YAML do recurso RoleBinding.

Para mais informações sobre esses papéis, consulte Preparar permissões do IAM.

Consultar e filtrar registros

Selecione um dos métodos a seguir para criar consultas e filtrar registros das cargas de trabalho do projeto:

Observação :uma única consulta de registro no Loki pode verificar no máximo 200 GB de dados de registro e retornar até 5.000 linhas de registro por vez. Para evitar exceder esses limites em grandes volumes de registros, reduza o período da consulta ou refine os filtros de rótulo. Para mais informações, consulte Limites do sistema.

Painel de registros do Grafana

Nesta seção, descrevemos como acessar os registros usando o painel "Registro" no Grafana.

Identificar o endpoint do Grafana

O URL a seguir é o endpoint da instância do Grafana do seu projeto:

  https://GDC_URL/PROJECT_NAMESPACE/grafana

Substitua:

• GDC_URL: o URL da sua organização no GDC.

• PROJECT_NAMESPACE: o namespace do projeto.

  Por exemplo, o endpoint do Grafana para o projeto platform-obs na organização org-1 é https://org-1/platform-obs/grafana.

Ver registros na interface do usuário do Grafana

Consulte os registros na interface do usuário do Grafana:

1. No console do GDC, selecione seu projeto.
2. No menu de navegação, selecione Operações > Logging.

3. Clique em Ver tudo no Grafana Loki.

   Uma nova página abre o endpoint do Grafana e exibe a interface do usuário.

4. Na interface do usuário, clique em Análise Análise no menu de navegação para abrir a página Análise.

5. No menu da barra Explorar, selecione uma fonte de dados para recuperar registros, de acordo com o tipo de universo:

   • Universos de zona única: selecione uma das seguintes fontes de dados para exibir dados de registro da zona única do seu universo:

     • Registros operacionais: mostre os registros operacionais.
     • Registros de auditoria: mostre os registros de auditoria.

   • Universos de várias zonas: o Grafana pode se conectar a diferentes zonas e mostrar dados entre zonas. Selecione uma das seguintes fontes de dados para exibir dados de registro de qualquer zona do seu universo, independentemente da zona em que você fez login:

     • Registros operacionais ZONE_NAME: mostram registros operacionais de uma zona específica.
     • Registros de auditoria ZONE_NAME: exibe registros de auditoria de uma zona específica.

     Além disso, para ter visualizações de dados entre zonas em um único painel e adicionar várias zonas à consulta, selecione Misto como a fonte de dados.

     Observação :os registros de auditoria estão disponíveis apenas para administradores da plataforma, mesmo que eles não possam criar ou configurar destinos de registro de auditoria. Os operadores de aplicativos só podem acessar registros operacionais.

6. Insira uma consulta para pesquisar registros no painel "Registro" usando expressões LogQL (linguagem de consulta de registro). Você pode fazer isso de duas maneiras:

   • Use a interface interativa do criador de consultas. Em seguida, clique em Executar consulta.
   • Digite sua consulta diretamente no campo de texto e pressione Shift+Enter para executá-la.

   A página mostra os registros que correspondem à sua consulta. Depois de consultar os registros, é possível exportá-los. Clique em Exportar para fazer o download de registros em formatos de texto simples ou CSV. Também é possível selecionar um período para os registros.

   

   Figura 1. Opção de menu para consultar registros de auditoria na interface do usuário do Grafana.

   Na figura 1, a opção Registros de auditoria exibe a interface que permite criar consultas do Grafana para recuperar registros de auditoria.

   Para exemplos de rótulos e valores para consultar registros diferentes, consulte Exemplos de consultas e rótulos.

Selecione um período para os registros

Para consultar registros em um período, siga estas etapas:

1. Clique no menu Seletor de horário no Grafana.

2. No menu, realize uma das seguintes ações:

   • Selecione as opções de período relativo, por exemplo, os últimos 30 minutos.
   • Defina períodos absolutos personalizados escolhendo datas e horários específicos no calendário e clicando em Aplicar período.

3. Se quiser, clique em Mudar configurações de horário para alterar as configurações de Fuso horário e Ano fiscal nos controles de período.

   As configurações de horário são salvas por painel. Para mais informações sobre consultas em um intervalo de tempo, consulte https://grafana.com/docs/loki/latest/reference/api/#query-loki-over-a-range-of-time.

API Log Query

Nesta seção, descrevemos como acessar seus registros usando a API Log Query.

Identificar o endpoint de API Log Query

A API Log Query expõe os dois endpoints a seguir para consultar registros de auditoria e operacionais:

• Endpoint do registro de auditoria:

  audit-log-query-api.ORG_DOMAIN
  

  Observação :os registros de auditoria estão disponíveis apenas para administradores da plataforma, mesmo que eles não possam criar ou configurar destinos de registro de auditoria. Os operadores de aplicativos só podem acessar registros operacionais.

• Endpoint de registro operacional:

  operational-log-query-api.ORG_DOMAIN
  

Substitua ORG_DOMAIN pelo nome de domínio da organização. Para ver essa propriedade, use o comando gdcloud config list. O nome de domínio precisa seguir a sintaxe org-name.zone.google.gdch.com. Por exemplo, uma organização chamada org-1, na zona zone1 e em um ambiente de teste, tem um domínio como org-1.zone1.google.gdch.test.

A API Log Query tem as três opções de endpoint a seguir:

• labels: lista todos os rótulos de um projeto.
• labels/labels/LABEL/values: lista valores de rótulo específicos para um projeto.
• logs: lista os registros de um projeto específico.

Para saber mais informações, consulte a documentação da API.

Enviar uma consulta

Envie uma consulta para o endpoint de API Log Query usando clientes HTTP ou gRPC.

HTTP

Siga as instruções para acessar diretamente a API com um cliente HTTP. Você pode usar o kubectl para gerenciar a autenticação ou fazer isso por conta própria.

Consulte a API Log Query usando clientes HTTP, como curl, wget ou um cliente HTTP que você cria e gerencia. O exemplo a seguir usa a ferramenta curl para consultar a API, e é possível usar um formato semelhante para comandos wget:

1. Autentique a solicitação cURL:

   1. Baixe e instale a CLI gdcloud.

   2. Defina a propriedade core/organization_console_url da gdcloud:

      gdcloud config set core/organization_console_url https://GDC_URL
      

      Substitua GDC_URL pelo URL de uma organização no GDC.

   3. Faça login com o provedor de identidade configurado:

      gdcloud auth login
      

   4. Use seu usuário e senha para autenticar e fazer login.

   5. Exporte o token de identidade da conta especificada para uma variável de ambiente:

      export TOKEN="$($HOME/gdcloud auth print-identity-token --audiences=https://LOG_QUERY_API_ENDPOINT)"
      

      Substitua LOG_QUERY_API_ENDPOINT pelo endpoint de API Log Query de onde você quer consultar os registros e o domínio ao qual quer se conectar. Portanto, o valor da flag audiences pode ser, por exemplo, https://operational-log-query-api.org-1.zone1.google.gdch.test.

      Quando o login for concluído, use o cabeçalho de autorização na solicitação cURL com o comando gdcloud auth print-identity-token. Para mais informações, consulte gdcloud auth print-identity-token.

2. Se você quiser listar todos os rótulos de um projeto, envie a seguinte consulta:

   curl -H "Authorization: Bearer ${TOKEN}" \
   https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/labels \
   -H "Content-Type: application/json" -v
   

   Substitua:

   • LOG_QUERY_API_ENDPOINT: o endpoint de API Log Query de onde você quer consultar registros.
   • PROJECT_NAMESPACE: o namespace do projeto.

3. Se você quiser listar valores de rótulo específicos para um projeto, envie a seguinte consulta:

   curl -H "Authorization: Bearer ${TOKEN}" \
   https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/labels/labels/LABEL/values \
   -H "Content-Type: application/json" -v
   

   Substitua:

   • LOG_QUERY_API_ENDPOINT: o endpoint de API Log Query de onde você quer consultar registros.
   • PROJECT_NAMESPACE: o namespace do projeto.
   • LABEL: o rótulo específico para o qual você quer consultar o valor.

4. Se você quiser consultar registros de um projeto específico, crie uma consulta logs_filter e inclua-a no corpo da solicitação:

   curl -X GET -H "Authorization: Bearer ${TOKEN}" \
   https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/logs \
   -H "Content-Type: application/json" -d \
   '{"logs_filter": {"labels_equal": {"LABEL": "LABEL_VALUE"}}}' -v
   

   Substitua:

   • LOG_QUERY_API_ENDPOINT: o endpoint de API Log Query de onde você quer consultar registros.
   • PROJECT_NAMESPACE: o namespace do projeto.
   • LABEL: o rótulo específico para o qual você quer consultar registros.
   • LABEL_VALUE: o valor do rótulo para o qual você quer consultar registros.

   Consulte a documentação da API para ver todas as opções de criação de uma consulta logs_filter.

gRPC

O gRPC é amplamente compatível com linguagens de programação e oferece um método de comunicação mais eficiente em comparação com os clientes HTTP.

Para consultar registros usando gRPC, você precisa atender aos seguintes pré-requisitos:

• Crie sua própria biblioteca de cliente com base nos buffers de protocolo fornecidos pelo Google.
• Implementar a autenticação no cliente.
• Implemente novas tentativas.

Para informações sobre os buffers de protocolo, consulte a documentação da API.

O exemplo a seguir mostra como consultar registros de um programa Go usando um cliente gRPC não autenticado. O exemplo pressupõe que você criou um pacote golang que inclui um arquivo de build do Bazel para importar dependências de código:

1. Salve o código a seguir em um programa Go chamado client.go:

   package main
   import (
           "context"
           "crypto/tls"
           "flag"
           "fmt"
           "google.golang.org/grpc/credentials"
           "google.golang.org/grpc/metadata"
           pb "<import path to generated log query api protos>/pkg/apis/public/logging/v1/proto"
           "google.golang.org/grpc"
   )
   
   var serverAddr = flag.String("server", "localhost:8080", "server address")
   
   func main() {
           flag.Parse()
           tc := credentials.NewTLS(&tls.Config{InsecureSkipVerify: true})
           conn, err := grpc.Dial(*serverAddr, grpc.WithTransportCredentials(tc))
   
           if err != nil {
                   panic(error.Error(fmt.Errorf("create client connection failed: %v", err)))
           }
           defer conn.Close()
   
           c := pb.NewLogsClient(conn)
           md := metadata.Pairs("clienttest", "test")
           ctx := metadata.NewOutgoingContext(context.Background(), md)
   
           err = listLabels(ctx, c, "project-foo")
           if err != nil {
                   panic(error.Error(err))
           }
   
           if err := listLabelValues(ctx, c, "project-foo", "resource-bar"); err != nil {
                   panic(error.Error(err))
           }
   
           if err := listLogs(ctx, c, "project-foo", &pb.ListLogsFilter{
                   LabelsEqual:    map[string]string{"resource-bar": "resource-bar-value"},
                   OrderAscending: true,
           }); err != nil {
                   panic(error.Error(err))
           }
   }
   
   // List all labels for a project.
   
   func listLabels(ctx context.Context, c pb.LogsClient, project string) error {
           lbr := &pb.ListLabelsRequest{
                   Parent:   project,
                   PageSize: 1000, // PageSize can be configured to limit the number of responses per page.
           }
           resp, err := c.ListLabels(ctx, lbr)
           if err != nil {
                   return fmt.Errorf("list labels: %v", err)
           }
           fmt.Printf("%v", resp)
           return nil
   }
   
   // List specific label values for a project.
   
   func listLabelValues(ctx context.Context, c pb.LogsClient, project string, label string) error {
           lbr := &pb.ListLabelValuesRequest{
                   Parent:   project,
                   Label:    label,
                   PageSize: 1000, // PageSize can be configured to limit the number of responses per page.
           }
           resp, err := c.ListLabelValues(ctx, lbr)
           if err != nil {
                   return fmt.Errorf("list label values: %v", err)
           }
           fmt.Printf("%v", resp)
           return nil
   }
   
   // List logs for a specific project.
   
   func listLogs(ctx context.Context, c pb.LogsClient, project string, lf *pb.ListLogsFilter) error {
           lbr := &pb.ListLogsRequest{
                   Parent:     project,
                   LogsFilter: lf,
                   PageSize:   5, // PageSize can be configured to limit the number of responses per page.
           }
           resp, err := c.ListLogs(ctx, lbr)
           if err != nil {
                   return fmt.Errorf("list logs: %v", err)
           }
           fmt.Printf("logs: %v", resp)
           return nil
   }
   

2. Execute o programa Go:

   go run PATH_TO_API/client.go -server=LOG_QUERY_API_ENDPOINT:443
   

   Substitua:

   • PATH_TO_API: o caminho para o arquivo da API.
   • LOG_QUERY_API_ENDPOINT: o endpoint de API Log Query de onde você quer consultar registros.

   Se a flag do servidor não for especificada, a solicitação padrão será enviada para localhost.

Exemplos de consultas e rótulos

Veja a seguir alguns dos rótulos padrão que podem ser usados para consultar registros:

• cluster: o nome do cluster.
• namespace: o namespace do projeto.
• node: o nome do nó.
• pod: o nome do pod.
• container: o nome do contêiner.

Os exemplos de código a seguir mostram o uso de rótulos e valores para consultar diferentes registros:

• Selecione os registros do servidor:

  {cluster="admin", namespace="kube-system", resources="k8s_container", container="kube-apiserver"}
  

• Selecione os registros de auditoria do cluster:

  {cluster="admin", resources="k8s_audit"}