Consulta y visualización de registros

La consulta de registros en el dispositivo de Google Distributed Cloud (GDC) aislado te permite inspeccionar los eventos operativos y de auditoría en las cargas de trabajo de tu proyecto después de recopilar los registros. Puedes filtrar, visualizar y exportar transmisiones de registros en el panel de registros de Grafana con expresiones de lenguaje de consulta de registros (LogQL). Para los flujos de trabajo programáticos, consulta la API de Log Query de tu organización a través de HTTP o gRPC siguiendo los métodos de acceso estándar a la API.

Antes de comenzar

Para obtener los permisos que necesitas para consultar y visualizar registros en la interfaz de usuario de Grafana, pídele a tu administrador de IAM de la organización o al administrador de IAM del proyecto que te otorgue uno de los roles predefinidos de visualizador de Grafana de la organización o de visualizador de Grafana del proyecto. Según el nivel de acceso y los permisos que necesites, puedes obtener roles de Grafana en una organización o un proyecto.

Como alternativa, para obtener los permisos que necesitas para consultar registros desde la API de Log Query, pídele al administrador de IAM de tu proyecto que te otorgue el rol de emisor de consultas de la API de Log Query en el espacio de nombres de tu proyecto.

Para obtener más información sobre estos roles, consulta Prepara los permisos de IAM.

Crea consultas para tus registros

Consultar los registros desde la IU de la instancia de supervisión del sistema te permite elegir la fuente de datos para recuperar los registros operativos de tu proyecto y obtener una vista integrada de tus consultas. Para filtrar los resultados, busca registros por etiquetas con expresiones del lenguaje de consulta. Por ejemplo, puedes establecer las etiquetas cluster y namespace en tus consultas con los valores que identifican el espacio de nombres del clúster y del proyecto, respectivamente.

Extremo de la instancia de supervisión del sistema

Para el operador de aplicaciones (AO)

La siguiente URL es el extremo de la instancia de supervisión de tu proyecto:

https://GDC_URL/PROJECT_NAMESPACE/grafana

Reemplaza lo siguiente:

  • GDC_URL: Es la URL de tu organización en GDC.
  • PROJECT_NAMESPACE: Es el espacio de nombres de tu proyecto.

Para el administrador de la plataforma (PA)

La siguiente URL es el extremo de la instancia de supervisión de tu proyecto:

https://GDC_URL/platform-obs/grafana

Reemplaza GDC_URL por la URL de tu organización en GDC.

Consulta y filtra tus registros

Selecciona uno de los siguientes métodos para compilar consultas y filtrar registros de las cargas de trabajo de tu proyecto:

En esta sección, se describe cómo acceder a tus registros con el panel de registros en Grafana.

Identifica tu extremo de Grafana

Para el operador de aplicaciones (AO)

La siguiente URL es el extremo de la instancia de supervisión de tu proyecto:

https://GDC_URL/PROJECT_NAMESPACE/grafana

Reemplaza lo siguiente:

  • GDC_URL: Es la URL de tu organización en GDC.
  • PROJECT_NAMESPACE: Es el espacio de nombres de tu proyecto.

Para el administrador de la plataforma (PA)

La siguiente URL es el extremo de la instancia de supervisión de tu proyecto:

https://GDC_URL/platform-obs/grafana

Reemplaza GDC_URL por la URL de tu organización en GDC.

Visualiza registros en la interfaz de usuario de Grafana

Consulta los registros en la interfaz de usuario de Grafana:

  1. En la consola de GDC, selecciona tu proyecto.
  2. En el menú de navegación, selecciona Operaciones > Logging.
  3. Haz clic en Ver todo en Grafana Loki.

Se abrirá una página nueva con tu extremo de Grafana y se mostrará la interfaz de usuario.

  1. En la interfaz de usuario, haz clic en Explorar Explorar en el menú de navegación para abrir la página Explorar.
  2. En el menú de la barra Explorar, selecciona una fuente de datos para recuperar los registros, según tu tipo de universo:

  • Universos de una sola zona: Selecciona una de las siguientes fuentes de datos para mostrar los datos de registro de la zona única de tu universo:

  • Registros operativos: Muestra los registros operativos.

  • Registros de auditoría: Muestra los registros de auditoría.

  • Registros operativos ZONE_NAME: Muestra los registros operativos de una zona en particular.

  • Registros de auditoría ZONE_NAME: Muestra los registros de auditoría de una zona en particular.

Además, para tener visualizaciones de datos de varias zonas en un solo panel y agregar varias zonas a tu consulta, selecciona Mixto como fuente de datos.

  1. Ingresa una consulta para buscar registros en el panel de registros con expresiones de LogQL (lenguaje de consulta de registros). Puedes realizar este paso de cualquiera de las siguientes maneras:

    • Usa la interfaz interactiva del compilador de consultas. Luego, haz clic en Ejecutar consulta.
    • Ingresa tu consulta directamente en el campo de texto y presiona Mayúsculas + Intro para ejecutarla.

    En la página, se muestran los registros que coinciden con tu consulta. Después de consultar los registros, puedes exportarlos. Haz clic en Exportar para descargar los registros en formato de texto sin formato o CSV. También puedes seleccionar un período para tus registros.

    La opción Registros de auditoría está seleccionada en la página Explorar para obtener registros de auditoría.

    Figura 1. Opción de menú para consultar los registros de auditoría desde la interfaz de usuario de Grafana.

    En la figura 1, la opción Registros de auditoría muestra la interfaz que te permite compilar consultas desde Grafana para recuperar registros de auditoría.

    Para ver ejemplos de etiquetas y valores para consultar diferentes registros, consulta Consultas y etiquetas de ejemplo.

    Selecciona un intervalo de tiempo para tus registros

    Para consultar registros en un período, sigue estos pasos:

    1. Haz clic en el menú Selector de tiempo en Grafana.

    2. En el menú, realiza una de las siguientes acciones:

      • Selecciona opciones de período relativo, por ejemplo, los últimos 30 minutos.
      • Establece períodos absolutos personalizados eligiendo fechas y horas específicas en el calendario y haciendo clic en Aplicar período.

    3. De manera opcional, haz clic en Cambiar la configuración de hora para cambiar la configuración de Zona horaria y Año fiscal en los controles de período.

    La configuración de hora se guarda por panel. Para obtener más información sobre las consultas en un intervalo de tiempo, consulta https://grafana.com/docs/loki/latest/reference/api/#query-loki-over-a-range-of-time.

    Envía una consulta

    Envía una consulta al endpoint de API de Log Query con clientes HTTP o gRPC.

    HTTP

    Sigue las instrucciones para acceder directamente a la API con un cliente HTTP. Puedes confiar en kubectl para administrar la autenticación o controlarla por tu cuenta.

    Consulta la API de Log Query con clientes HTTP, como curl, wget o un cliente HTTP que crees y administres. En el siguiente ejemplo, se usa la herramienta curl para consultar la API, y puedes usar un formato similar para los comandos de wget:

    1. Autentica la solicitud cURL:

      1. Descarga e instala la CLI de gdcloud.

      2. Configura la propiedad core/organization_console_url de gdcloud:

        gdcloud config set core/organization_console_url https://GDC_URL

        Reemplaza GDC_URL por la URL de una organización en GDC.

      3. Accede con el proveedor de identidad configurado:

        gdcloud auth login

      4. Usa tu usuario y contraseña para autenticarte y acceder.

      5. Exporta el token de identidad de la cuenta especificada a una variable de entorno:

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

        Reemplaza LOG_QUERY_API_ENDPOINT por el extremo de la API de Log Query desde el que deseas consultar los registros y el dominio al que quieres conectarte. Por lo tanto, el valor de la marca audiences puede ser, por ejemplo, https://operational-log-query-api.org-1.zone1.google.gdch.test.

        Cuando el acceso se realice correctamente, podrás usar el encabezado de autorización en tu solicitud de cURL con el comando gdcloud auth print-identity-token. Para obtener más información, consulta gdcloud auth print-identity-token.

    2. Si quieres enumerar todas las etiquetas de un proyecto, envía la siguiente consulta:

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

      Reemplaza lo siguiente:

      • LOG_QUERY_API_ENDPOINT: Es el endpoint de API de Log Query desde donde deseas consultar los registros.
      • PROJECT_NAMESPACE: Es el espacio de nombres de tu proyecto.

    3. Si deseas enumerar valores de etiqueta específicos para un proyecto, envía la siguiente 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

      Reemplaza lo siguiente:

      • LOG_QUERY_API_ENDPOINT: Es el endpoint de API de Log Query desde donde deseas consultar los registros.
      • PROJECT_NAMESPACE: Es el espacio de nombres de tu proyecto.
      • LABEL: Es la etiqueta específica de la que deseas consultar su valor.

    4. Si deseas consultar los registros de un proyecto específico, crea una consulta logs_filter y, luego, inclúyela en el cuerpo de la solicitud:

      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

      Reemplaza lo siguiente:

      • LOG_QUERY_API_ENDPOINT: Es el endpoint de API de Log Query desde donde deseas consultar los registros.
      • PROJECT_NAMESPACE: Es el espacio de nombres de tu proyecto.
      • LABEL: Es la etiqueta específica para la que deseas consultar los registros.
      • LABEL_VALUE: Es el valor de la etiqueta para el que deseas consultar los registros.

      Consulta la documentación de la API para ver todas las opciones de construcción de una consulta de logs_filter.

    gRPC

    gRPC es ampliamente compatible con los lenguajes de programación y proporciona un método de comunicación más eficiente en comparación con los clientes HTTP.

    Para consultar registros con gRPC, debes cumplir con los siguientes requisitos previos:

    • Crea tu propia biblioteca cliente basada en los búferes de protocolo proporcionados por Google.
    • Implementar la autenticación en el cliente
    • Implementa reintentos.

    Para obtener información sobre los búferes de protocolo, consulta la documentación de la API.

    En el siguiente ejemplo, se muestra cómo consultar registros de un programa de Go con un cliente de gRPC no autenticado. En el ejemplo, se supone que creaste un paquete de golang que incluye un archivo de compilación de Bazel para importar dependencias de código:

    1. Guarda el siguiente código en un programa de Go llamado 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. Ejecuta el programa de Go:

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

      Reemplaza lo siguiente:

      • PATH_TO_API: Es la ruta de acceso al archivo de la API.
      • LOG_QUERY_API_ENDPOINT: Es el endpoint de API de Log Query desde donde deseas consultar los registros.

      Si no se especifica la marca del servidor, la solicitud predeterminada llega a localhost.

Consultas y etiquetas de muestra

Estas son algunas de las etiquetas predeterminadas que puedes usar para consultar registros:

  • cluster: el nombre del clúster
  • namespace: Es el espacio de nombres de tu proyecto.
  • node: Es el nombre del nodo.
  • pod: Es el nombre del Pod.
  • container: Es el nombre del contenedor.

En las siguientes muestras de código, se indica el uso de etiquetas y valores para consultar diferentes registros:

  • Selecciona los registros del servidor:

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

  • Selecciona los registros de auditoría del clúster:

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