Consultar e exibir registros

Esta página fornece instruções detalhadas sobre como consultar e visualizar seus registros usando a interface do usuário do Grafana para receber insights sobre os eventos e a atividade do seu serviço.

Depois de coletar registros das cargas de trabalho e serviços implantados no appliance isolado do Google Distributed Cloud (GDC), você pode começar a analisá-los. Para analisar os registros, visualize e filtre-os em painéis informativos do Grafana ou chamadas gRPC para acesso programático.

Você pode acessar seus registros da seguinte maneira:

  • Painéis do Grafana: tenha insights sobre o registro de atividades do seu projeto no painel de registros da sua instância do Grafana. Com ele, é possível consultar e identificar registros específicos, oferecendo observabilidade granular de dados adaptada às suas necessidades. O Grafana oferece uma interface fácil de usar para filtrar e analisar dados de carga de trabalho, além de criar dashboards e painéis personalizados para uma visualização abrangente.

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, você pode 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ê a função 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, é possível escolher a fonte de dados para recuperar registros operacionais do projeto e ter uma visão integrada das consultas. Para filtrar os resultados, pesquise registros por rótulos usando expressões da 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 aplicativos (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 administradores 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 seus registros

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

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

Identificar seu endpoint do Grafana

Para operador de aplicativos (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 administradores 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

Consultar 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 seu endpoint do Grafana e mostra 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 Analisar, selecione uma fonte de dados para recuperar registros, de acordo com o tipo de universo:

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

  • Registros operacionais: mostram registros operacionais.

  • Registros de auditoria: mostram os registros de auditoria.

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

  • Registros de auditoria ZONE_NAME: mostram os 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 à sua consulta, selecione Mista como a fonte de dados.

  1. Insira uma consulta para pesquisar registros no painel "Registros" usando expressões da LogQL (linguagem de consulta de registros). 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 executar a consulta.

    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 dos registros em texto simples ou nos formatos CSV. Também é possível selecionar um período para seus registros.

    A opção "Registros de auditoria" é selecionada na página "Analisar" para obter 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 diferentes registros, consulte Exemplos de consultas e rótulos.

    Selecionar um período para seus registros

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

    1. Clique no menu Seletor de período no Grafana.

    2. No menu, faça uma destas 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 configurações de tempo para alterar as configurações de Fuso horário e Ano fiscal nos controles de período.

    As configurações de hora 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.

    Enviar uma consulta

    Envie uma consulta ao endpoint da 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. Você pode usar um formato semelhante para comandos wget:

    1. Autentique a solicitação cURL:

      1. Faça o download e instale a CLI gdcloud.

      2. Defina a propriedade core/organization_console_url do 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 da API Log Query de onde você quer consultar os registros e o domínio a que 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 sua solicitação cURL com o comando gdcloud auth print-identity-token. Para mais informações, consulte gdcloud auth print-identity-token.

    2. Se 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:

    3. Se você quiser listar valores de rótulos 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 da API de consulta de registros de onde você quer consultar os 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 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 da API de consulta de registros de onde você quer consultar os 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 os 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 várias linguagens de programação e oferece um método de comunicação mais eficiente em comparação com 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.
    • Implemente 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:

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

Exemplos de consultas e rótulos

Confira abaixo 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 registros de auditoria do cluster:

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