Consultar e exibir registros

A consulta de registros no dispositivo do 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 padrão de acesso à API.

Antes de começar

Para receber as permissões necessárias para consultar e visualizar registros na interface do usuário do Grafana, peça ao administrador do IAM da organização ou do projeto para conceder a você um dos papéis predefinidos de Leitor do Grafana da organização ou do projeto. Dependendo do nível de acesso e das permissões necessárias, é possível receber papéis do Grafana em uma organização ou um projeto.

Como alternativa, para receber as permissões necessárias para consultar registros da API Log Query, peça ao administrador do IAM do projeto para conceder a você o papel de consultor da API Log Query no namespace do projeto.

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

Criar consultas para seus registros

Ao consultar registros na UI da instância de monitoramento do sistema, você pode escolher a fonte de dados para recuperar registros operacionais do seu projeto e ter uma visão integrada das suas consultas. Para filtrar os resultados, pesquise registros por rótulos usando expressões de linguagem de consulta. Por exemplo, é possível definir os rótulos cluster e namespace nas consultas com os valores que identificam o cluster e o namespace do projeto, respectivamente.

Endpoint da instância de monitoramento do sistema

Para operador de aplicativo (AO)

O URL a seguir é o endpoint da instância de monitoramento 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.

Para administrador da plataforma (PA)

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

https://GDC_URL/platform-obs/grafana

Substitua GDC_URL pelo URL da sua organização no GDC.

Consultar e filtrar registros

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

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

Identificar o endpoint do Grafana

Para operador de aplicativo (AO)

O URL a seguir é o endpoint da instância de monitoramento 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.

Para administrador da plataforma (PA)

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

https://GDC_URL/platform-obs/grafana

Substitua GDC_URL pelo URL da sua organização no GDC.

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.

  1. Na interface do usuário, clique em Análise Análise no menu de navegação para abrir a página Análise.
  2. 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.

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

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

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

  1. 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.

    A opção "Registros de auditoria" está selecionada na página "Explorar" para receber registros de auditoria.

    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 mostra 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 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 as 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 período, consulte https://grafana.com/docs/loki/latest/reference/api/#query-loki-over-a-range-of-time.

    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"}