Consulta y visualización de registros

En esta página, se proporcionan instrucciones detalladas para consultar y visualizar tus registros con la interfaz de usuario de Grafana y, así, obtener estadísticas sobre los eventos y la actividad de tu servicio.

Después de recopilar registros de tus cargas de trabajo y servicios implementados en el dispositivo aislado de Google Distributed Cloud (GDC), puedes comenzar a analizarlos. Para analizar los registros, puedes visualizarlos y filtrarlos en paneles informativos de Grafana o en llamadas a gRPC para acceder a ellos de forma programática.

Puedes acceder a tus registros de la siguiente manera:

  • Paneles de Grafana: Obtén estadísticas sobre el registro de actividad de tu proyecto a través del panel de registros de tu instancia de Grafana. Este panel te permite consultar y detectar registros específicos, lo que proporciona una observabilidad de datos detallada y adaptada a tus necesidades. Grafana proporciona una interfaz fácil de usar para filtrar y analizar los datos de tu carga de trabajo, y crear paneles personalizados para una visualización integral.

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 del proyecto que te otorgue uno de los roles predefinidos de Visualizador de Grafana de la organización o Visualizador de Grafana del proyecto. Según el nivel de acceso y los permisos que necesites, es posible que obtengas roles de Grafana en una organización o un proyecto.

Como alternativa, para obtener los permisos que necesitas para consultar los registros de la API de Log Query, pídele al administrador de IAM del proyecto que te otorgue el rol de consultor 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 registros desde la IU de la instancia de supervisión del sistema te permite elegir la fuente de datos para recuperar 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 consultas. Por ejemplo, puedes establecer las etiquetas cluster y namespace en tus consultas con los valores que identifican tu clúster y el espacio de nombres del proyecto, respectivamente.

Extremo de la instancia de supervisión del sistema

Para el operador de la aplicación (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: 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.

Cómo consultar y filtrar tus registros

Selecciona uno de los siguientes métodos para crear 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 la aplicación (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: 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 los registros en la interfaz de usuario de Grafana

Registra las consultas en la interfaz de usuario de Grafana:

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

Se abrirá una nueva página 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 registros, según el tipo de universo:

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

  • Registros operativos: Muestra los registros operativos.

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

  • Registros operativos ZONE_NAME: Muestran 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 entre zonas en un solo panel y agregar varias zonas a tu consulta, selecciona Mixta como fuente de datos.

  1. Ingresa una consulta para buscar registros en el panel de registros con expresiones de LogQL (lenguaje de consultas de registros). Puedes realizar este paso de una 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 búsqueda. 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 intervalo de tiempo 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 intervalo de tiempo 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 desde 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 extremo de la 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 manejarla 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 de curl para consultar la API, y puedes usar un formato similar para los comandos de wget:

    1. Autentica la solicitud cURL:

      1. Descarga y, luego, 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 te quieres conectar. 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 sea exitoso, podrás usar el encabezado de autorización en tu solicitud de cURL a través del comando gdcloud auth print-identity-token. Para obtener más información, consulta gcloud auth print-identity-token.

    2. Si deseas 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 extremo de la API de Log Query desde el que 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 extremo de la API de Log Query desde el que 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 su valor.

    4. Si deseas consultar los registros de un proyecto específico, crea una consulta logs_filter y agrégala al 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 extremo de la API de Log Query desde el que 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 para construir una búsqueda 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.
    • Implementa 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 desde un programa en Go con un cliente de gRPC no autenticado. En el ejemplo, se supone que creaste un paquete de Go que incluye un archivo de compilación de Bazel para importar dependencias de código:

    1. Guarda el siguiente código en un programa en 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 en 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 extremo de la API de Log Query desde el que deseas consultar los registros.

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

Ejemplos de búsquedas y etiquetas

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