O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Consultar e exibir registros

Nesta página, você encontra instruções detalhadas sobre como consultar e visualizar seus registros usando a interface do usuário do Grafana e a API Log Query para receber insights sobre os eventos e as atividades do serviço.

Depois de coletar registros das cargas de trabalho e serviços implantados no Google Distributed Cloud (GDC) isolado por air-gap, você pode começar a analisá-los. Para analisar os registros, é possível visualizá-los e filtrá-los em painéis informativos do Grafana ou acessá-los diretamente da API Log Query usando chamadas HTTP ou gRPC para acesso programático.

É possível acessar os registros de uma das duas maneiras a seguir:

Painéis do Grafana: receba 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 os dados da carga de trabalho, criando painéis personalizados para uma visualização abrangente.
API Log Query: para acesso programático, consulte os registros diretamente na API Log Query do seu projeto. A API de consulta de registros é uma API não Kubernetes que oferece suporte a HTTP e gRPC, expondo seus próprios endpoints para você. Acesse essa API apenas em uma organização específica no Distributed Cloud seguindo os métodos padrão de acesso à 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 administrador do IAM da organização 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.
Consultador 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 IAM do projeto para solicitar os seguintes papéis:

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

A tabela a seguir resume os requisitos do 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 seguintes configurações 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 RoleBinding no caminho do arquivo de infraestrutura como código (IaC) especificado para aplicá-lo pelo GitOps:

Configuração 1

Essa configuração concede permissões a um grupo de usuários para 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 --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 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 configurar, 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=my-email@example.com --namespace=platform-obs

Caminho do arquivo 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 este 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 esse RoleBinding é criado e aplicado. Procure a coluna Namespace na tabela anterior.
EMAIL_ADDRESS: o identificador do usuário que está recebendo o papel, como application-operator@example.com.
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 a que o usuário do PA pertence, como pa-group.
ZONE: o nome da zona.
YAML_FILE: o nome do arquivo YAML para o recurso RoleBinding.

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

Consultar e filtrar seus registros

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

Painel de registros do Grafana

Nesta seção, descrevemos como acessar seus registros usando o painel "Registros" 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:

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

Uma nova página abre o endpoint do Grafana e exibe a interface do usuário.
Na interface do usuário, clique em Análise Análise no menu de navegação para abrir a página Análise.
No menu da barra Explorar, 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: mostre os registros de auditoria.
- Universos multizona: o Grafana pode se conectar a diferentes zonas e mostrar dados entre elas. Selecione uma das seguintes fontes de dados para mostrar dados de registro de qualquer zona do seu universo, independente da zona em que você fez login:
  - 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 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.
Insira uma consulta para pesquisar registros no painel "Registro" usando expressões LogQL (linguagem de consulta de registro). Você pode fazer isso de uma das seguintes 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 baixar os registros em texto simples ou nos formatos 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 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:

Clique no menu Seletor de horário no Grafana.
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.
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 horário são salvas por painel. Para mais informações sobre consultas em um intervalo de tempo, acesse 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 não seja possível 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. É possível conferir essa propriedade usando 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 seguintes três opções de endpoint:

labels: lista todos os rótulos de um projeto.
labels/labels/LABEL/values: lista valores de rótulo específicos de 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 confiar no 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 criado e gerenciado por você. O exemplo a seguir usa a ferramenta curl para consultar a API. Você pode usar um formato semelhante para comandos wget:

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, você poderá usar 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.
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:
- LOG_QUERY_API_ENDPOINT: o endpoint de API Log Query de onde você quer consultar registros.
- PROJECT_NAMESPACE: o namespace do projeto.
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 de 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.
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 conferir 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:

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
}

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 de consulta de registros de onde você quer consultar os 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

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