Esta página foi traduzida pela API Cloud Translation.

Consulte e veja registos

Esta página fornece instruções detalhadas sobre como consultar e visualizar os seus registos usando a interface do utilizador do Grafana e a API Log Query para obter estatísticas sobre os eventos e a atividade do seu serviço.

Depois de recolher registos das suas cargas de trabalho e serviços implementados no Google Distributed Cloud (GDC) air-gapped, pode começar a analisá-los. Para analisar registos, pode visualizá-los e filtrá-los em painéis informativos do Grafana ou aceder aos mesmos diretamente a partir da API Log Query através de chamadas HTTP ou gRPC para acesso programático.

Pode aceder aos seus registos através de um dos dois métodos seguintes:

Painéis do Grafana: obtenha estatísticas sobre o registo de atividade do seu projeto através do painel de registo da sua instância do Grafana. Este painel permite-lhe consultar e identificar registos específicos, oferecendo observabilidade de dados detalhada adaptada às suas necessidades. O Grafana oferece uma interface intuitiva para filtrar e analisar os dados da sua carga de trabalho, criando painéis de controlo e painéis personalizados para uma visualização abrangente.
API Log Query: para acesso programático, consulte os registos diretamente a partir da API Log Query do projeto. A API Log Query é uma API não Kubernetes que suporta HTTP e gRPC, expondo os seus próprios pontos finais. Aceda a esta API apenas numa organização específica na Distributed Cloud seguindo os métodos de acesso à API padrão.

Antes de começar

Para receber as autorizações necessárias para consultar e visualizar registos na interface do utilizador do Grafana, peça ao administrador da IAM da organização ou ao administrador da IAM do projeto que lhe conceda uma das funções predefinidas de visualizador do Grafana da organização ou visualizador do Grafana do projeto. Consoante o nível de acesso e as autorizações de que precisa, pode obter funções do Grafana numa organização ou num projeto.

Em alternativa, para obter as autorizações necessárias para consultar registos da API Log Query, peça ao administrador de IAM do projeto para lhe conceder a função de consultor da API Log Query no espaço de nomes do seu projeto.

Para mais informações sobre estas funções, consulte o artigo Prepare as autorizações de IAM.

Consulte e filtre os seus registos

Selecione um dos seguintes métodos para criar consultas e filtrar registos das cargas de trabalho do seu projeto:

Painel de registos do Grafana

Esta secção descreve como aceder aos seus registos através do painel de registos no Grafana.

Identifique o seu ponto final do Grafana

O seguinte URL é o ponto final da instância do Grafana do seu projeto:

  https://GDC_URL/PROJECT_NAMESPACE/grafana

Substitua o seguinte:

GDC_URL: o URL da sua organização no GDC.
PROJECT_NAMESPACE: o espaço de nomes do seu projeto.

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

Veja registos na interface do utilizador do Grafana

Registos de consultas na interface do utilizador do Grafana:

Na consola do GDC, selecione o seu projeto.
No menu de navegação, selecione Operações > Registo.
Clique em Ver tudo no Grafana Loki.

É aberta uma nova página com o seu ponto final do Grafana e apresenta a interface do utilizador.
Na interface do utilizador, clique em explorar Explorar no menu de navegação para abrir a página Explorar.
No menu da barra Explorar, selecione uma origem de dados para obter registos, de acordo com o tipo de universo:
- Universos de zona única: selecione uma das seguintes origens de dados para apresentar dados de registo da zona única do seu universo:
  - Registos operacionais: apresentam registos operacionais.
  - Registos de auditoria: apresenta registos de auditoria.
- Universos multizona: o Grafana pode ligar-se a diferentes zonas e mostrar dados entre zonas. Selecione uma das seguintes origens de dados para apresentar dados de registo de qualquer zona do seu universo, independentemente da zona em que tem sessão iniciada:
  - Registos operacionais ZONE_NAME: apresentam registos operacionais de uma zona específica.
  - Registos de auditoria ZONE_NAME: apresentam registos de auditoria de uma zona específica.
  Além disso, para ter visualizações de dados entre zonas num único painel de controlo e adicionar várias zonas à sua consulta, selecione Misto como origem de dados.
  
  Nota: os registos de auditoria só estão disponíveis para administradores da plataforma, mesmo que não possam criar nem configurar destinos de registo de auditoria. Os operadores de aplicações só podem aceder aos registos operacionais.
Introduza uma consulta para pesquisar registos no painel Registo através de expressões LogQL (linguagem de consulta de registos). Pode concluir este passo de qualquer uma das seguintes formas:
- Use a interface interativa do criador de consultas. Em seguida, clique em Executar consulta.
- Introduza a consulta diretamente no campo de texto e prima Shift+Enter para executar a consulta.
A página apresenta os registos que correspondem à sua consulta. Depois de consultar os registos, pode exportá-los. Clique em Exportar para transferir registos em texto simples ou formatos CSV. Também pode selecionar um intervalo de tempo para os seus registos.

Figura 1. Opção de menu para consultar registos de auditoria a partir da interface do utilizador do Grafana.

Na figura 1, a opção Registos de auditoria apresenta a interface que lhe permite criar consultas a partir do Grafana para obter registos de auditoria.

Para ver exemplos de etiquetas e valores para consultar diferentes registos, consulte o artigo Consultas e etiquetas de exemplo.

Selecione um intervalo de tempo para os seus registos

Para consultar registos num intervalo de tempo, siga estes passos:

Clique no menu Selecionador de hora no Grafana.
No menu, execute uma das seguintes ações:
- Selecione opções de intervalo de tempo relativo, por exemplo, os últimos 30 minutos.
- Defina intervalos de tempo absolutos personalizados escolhendo datas e horas específicas no calendário e clicando em Aplicar intervalo de tempo.
Opcionalmente, clique em Alterar definições de hora para alterar as definições de Fuso horário e Ano fiscal nos controlos do intervalo de tempo.

As definições de tempo são guardadas por painel de controlo. Para mais informações sobre consultas num intervalo de tempo, consulte https://grafana.com/docs/loki/latest/reference/api/#query-loki-over-a-range-of-time.

Log Query API

Esta secção descreve como aceder aos seus registos através da API Log Query.

Identifique o ponto final da API Log Query

A API Log Query expõe os dois seguintes pontos finais para consultar registos de auditoria e operacionais:

Ponto final do registo de auditoria:
```
audit-log-query-api.ORG_DOMAIN
```
Nota: os registos de auditoria só estão disponíveis para administradores da plataforma, mesmo que não possam criar nem configurar destinos de registo de auditoria. Os operadores da aplicação só podem aceder aos registos operacionais.
Ponto final do registo operacional:
```
operational-log-query-api.ORG_DOMAIN
```

Substitua ORG_DOMAIN pelo nome do domínio da organização. Pode ver esta propriedade através do comando gdcloud config list. O nome do domínio tem de seguir a sintaxe org-name.zone.google.gdch.com. Por exemplo, uma organização denominada org-1, na zona zone1 e num ambiente de teste tem um domínio como org-1.zone1.google.gdch.test.

A API Log Query tem as seguintes três opções de ponto final:

labels: apresenta todas as etiquetas de um projeto.
labels/labels/LABEL/values: lista valores de etiquetas específicos para um projeto.
logs: liste os registos de um projeto específico.

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

Envie uma consulta

Envie uma consulta para o ponto final da API Log Query através de clientes HTTP ou gRPC.

HTTP

Siga as instruções para aceder diretamente à API com um cliente HTTP. Pode confiar no kubectl para gerir a autenticação ou processar a autenticação por si.

Consulte a API Log Query através de clientes HTTP, como curl, wget ou um cliente HTTP que cria e gere. O exemplo seguinte usa a ferramenta curl para consultar a API, e pode usar um formato semelhante para comandos wget:

Autentique o pedido cURL:
1. Transfira e instale a CLI gcloud.
2. Defina a propriedade gdcloud: core/organization_console_url
```
gdcloud config set core/organization_console_url https://GDC_URL
```
  Substitua GDC_URL pelo URL de uma organização no GDC.
3. Inicie sessão com o Fornecedor de identidade configurado:
```
gdcloud auth login
```
4. Use o seu nome de utilizador e palavra-passe para autenticar e iniciar sessão.
5. Exporte o token de identidade para a 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 ponto final da API Log Query a partir do qual quer consultar registos e o domínio ao qual quer estabelecer ligação. Por conseguinte, o valor da flag audiences pode ser, por exemplo, https://operational-log-query-api.org-1.zone1.google.gdch.test.
  
  Quando o início de sessão for bem-sucedido, pode usar o cabeçalho de autorização no seu pedido cURL através do comando gdcloud auth print-identity-token. Para mais informações, consulte gdcloud auth print-identity-token.
Se quiser apresentar uma lista de todas as etiquetas 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 o seguinte:
- LOG_QUERY_API_ENDPOINT: o ponto final da API Log Query a partir do qual quer consultar os registos.
- PROJECT_NAMESPACE: o espaço de nomes do seu projeto.
Se quiser listar valores de etiquetas 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 o seguinte:
- LOG_QUERY_API_ENDPOINT: o ponto final da API Log Query a partir do qual quer consultar os registos.
- PROJECT_NAMESPACE: o espaço de nomes do seu projeto.
- LABEL: a etiqueta específica para a qual quer consultar o respetivo valor.
Se quiser consultar registos de um projeto específico, crie uma consulta logs_filter e inclua-a no corpo do pedido:
```
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 o seguinte:
- LOG_QUERY_API_ENDPOINT: o ponto final da API Log Query a partir do qual quer consultar os registos.
- PROJECT_NAMESPACE: o espaço de nomes do seu projeto.
- LABEL: a etiqueta específica para a qual quer consultar registos.
- LABEL_VALUE: o valor da etiqueta para o qual quer consultar os registos.
Consulte a documentação da API para ver todas as opções de criação de uma consulta logs_filter.

gRPC

O gRPC é amplamente suportado em várias linguagens de programação e oferece um método de comunicação mais eficiente em comparação com os clientes HTTP.

Para consultar registos através do gRPC, tem de cumprir os seguintes pré-requisitos:

Crie a sua própria biblioteca de cliente com base nos buffers de protocolo fornecidos pela 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 seguinte mostra como consultar registos de um programa Go através de um cliente gRPC não autenticado. O exemplo pressupõe que criou um pacote golang que inclui um ficheiro de compilação do Bazel para importar dependências de código:

Guarde o seguinte código num programa Go com o nome 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
}

Execute o programa Go:
```
go run PATH_TO_API/client.go -server=LOG_QUERY_API_ENDPOINT:443
```
Substitua o seguinte:
- PATH_TO_API: o caminho para o ficheiro da API.
- LOG_QUERY_API_ENDPOINT: o ponto final da API Log Query a partir do qual quer consultar os registos.
Se a flag do servidor não for especificada, o pedido predefinido é enviado para localhost.

Consultas e etiquetas de exemplo

Seguem-se algumas das etiquetas predefinidas que pode usar para consultar registos:

cluster: o nome do cluster.
namespace: o espaço de nomes do seu projeto.
node: o nome do nó.
pod: o nome do agrupamento.
container: o nome do contentor.

Os seguintes exemplos de código mostram a utilização de etiquetas e valores para consultar diferentes registos:

Selecione registos do servidor:

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

Selecione os registos de auditoria do cluster:
```
{cluster="admin", resources="k8s_audit"}
```