Escribe métricas personalizadas mediante un agente de sidecar

---

En este instructivo, se muestra cómo escribir, implementar y llamar a un servicio de Cloud Run que informa métricas personalizadas a Google Cloud Managed Service para Prometheus mediante el sidecar de OpenTelemetry.

Objetivos

• Escribir, compilar e implementar un servicio en Cloud Run con el sidecar de OpenTelemetry
• Genera métricas personalizadas y, luego, infórmalos a Google Cloud Managed Service para Prometheus.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

• Cloud Build
• Artifact Registry
• Google Cloud Managed Service para Prometheus
• Cloud Run

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios. Es posible que los usuarios nuevos de Google Cloud califiquen para obtener una prueba gratuita.

Antes de comenzar

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Cloud Run, Cloud Monitoring, Artifact Registry, and Cloud Build APIs.

   Enable the APIs

7. Instala e inicializa la CLI de gcloud
8. Actualiza Google Cloud CLI: gcloud components update

Roles obligatorios

Si deseas obtener los permisos que necesitas para completar el instructivo, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

• Editor de Cloud Build (roles/cloudbuild.builds.editor)
• Administrador de Cloud Run (roles/run.admin)
• Crea cuentas de servicio (roles/iam.serviceAccountCreator)
• Administrador de IAM de proyecto (roles/resourcemanager.projectIamAdmin)
• Escritor de métricas de Monitoring (roles/monitoring.metricWriter)
• Usuario de cuenta de servicio (roles/iam.serviceAccountUser)
• Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer)
• Administrador de almacenamiento (roles/storage.admin)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Nota: Los roles básicos de IAM también pueden contener permisos para completar el instructivo. No deberías otorgar roles básicos en un entorno de producción, pero puedes otorgarlos en un entorno de desarrollo o de prueba.

Además, ten en cuenta que la cuenta de servicio de Cloud Run necesita el rol Escritor de métricas de Monitoring (roles/monitoring.metricWriter). La cuenta de servicio predeterminada de Compute Engine tiene este rol de forma predeterminada, pero es posible que debas agregarla si cambiaste sus permisos o si usas una cuenta de servicio diferente.

Configura los valores predeterminados de gcloud

A fin de configurar gcloud con los valores predeterminados para el servicio de Cloud Run, sigue estos pasos:

1. Configura el proyecto predeterminado:

   gcloud config set project PROJECT_ID

   Reemplaza PROJECT_ID por el nombre del proyecto que creaste para este instructivo.

2. Configura gcloud en la región que elegiste:

   gcloud config set run/region REGION

   Reemplaza REGION por la región de Cloud Run compatible que prefieras.

Ubicaciones de Cloud Run

Cloud Run es regional, lo que significa que la infraestructura que ejecuta los servicios se ubica en una región específica, y Google la administra para que esté disponible de manera redundante en todas las zonas de esa región.

El cumplimiento de los requisitos de latencia, disponibilidad o durabilidad es el factor principal para seleccionar la región en la que se ejecutan los servicios de Cloud Run. Por lo general, puedes seleccionar la región más cercana a los usuarios, pero debes considerar la ubicación de los otros productos de Google Cloud que usa el servicio de Cloud Run. Si usas productos de Google Cloud en varias ubicaciones, la latencia y el costo del servicio pueden verse afectados.

Cloud Run está disponible en las siguientes regiones:

Sujetas a los Precios del nivel 1

• asia-east1 (Taiwán)
• asia-northeast1 (Tokio)
• asia-northeast2 (Osaka)
• europe-north1 (Finlandia) Bajo nivel de CO₂
• europe-southwest1 (Madrid) Bajo nivel de CO₂
• europe-west1 (Bélgica) Bajo nivel de CO₂
• europe-west4 (Países Bajos)
• europe-west8 (Milán)
• europe-west9 (París) Bajo nivel de CO₂
• me-west1 (Tel Aviv)
• us-central1 (Iowa) Bajo nivel de CO₂
• us-east1 (Carolina del Sur)
• us-east4 (Virginia del Norte)
• us-east5 (Columbus)
• us-south1 (Dallas)
• us-west1 (Oregón) Bajo nivel de CO₂

Sujetas a los Precios del nivel 2

• asia-east2 (Hong Kong)
• asia-northeast3 (Seúl, Corea del Sur)
• asia-southeast1 (Singapur)
• asia-southeast2 (Yakarta)
• asia-south1 (Bombay, India)
• asia-south2 Delhi (India)
• australia-southeast1 (Sídney)
• australia-southeast2 (Melbourne)
• europe-central2 (Varsovia, Polonia)
• europe-west12 (Turín)
• europe-west2 (Londres, Reino Unido)
• europe-west3 (Fráncfort, Alemania)
• europe-west6 (Zúrich, Suiza) Bajo nivel de CO₂
• me-central1 (Doha)
• northamerica-northeast1 (Montreal) Bajo nivel de CO₂
• northamerica-northeast2 (Toronto) Bajo nivel de CO₂
• southamerica-east1 (São Paulo, Brasil) Bajo nivel de CO₂
• southamerica-west1 (Santiago, Chile)
• us-west2 (Los Ángeles)
• us-west3 (Salt Lake City)
• us-west4 (Las Vegas)

Si ya creaste un servicio de Cloud Run, puedes ver la región en el panel de Cloud Run en la consola de Google Cloud.

Aceptar

Crea un repositorio de imágenes de Artifact Registry

Crea un repositorio de Docker de Artifact Registry para alojar la imagen del servicio de muestra:

gcloud artifacts repositories create run-otel \
    --repository-format=docker \
    --location=REGION \
    --project=PROJECT_ID

Reemplaza lo siguiente:

• PROJECT_ID por el nombre del proyecto que creaste para este instructivo.
• REGION por la región de Cloud Run compatible que prefieras.

Recupera la muestra de código

A fin de recuperar la muestra de código para su uso, haz lo siguiente:

1. Clona el repositorio de la app de muestra en tu máquina local:

   Go

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

   De manera opcional, puedes descargar la muestra como un archivo ZIP y extraerla.

2. Ve al directorio que contiene el código de muestra de Cloud Run:

   Go

   cd golang-samples/run/custom-metrics/

Revisa el código

El código de este instructivo consta de los siguientes elementos:

• Un servidor que controla las solicitudes entrantes y genera una métrica llamada sample_sidecar_counter

run/custom-metrics/main.go

Ver en GitHub Comentarios

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os"

	"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
	"go.opentelemetry.io/otel/metric/instrument"
	"go.opentelemetry.io/otel/sdk/metric"
	"go.opentelemetry.io/otel/sdk/resource"
	semconv "go.opentelemetry.io/otel/semconv/v1.17.0"
)

var counter instrument.Int64Counter

func main() {
	ctx := context.Background()
	shutdown := setupCounter(ctx)
	defer shutdown(ctx)

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
		log.Printf("defaulting to port %s", port)
	}

	http.HandleFunc("/", handler)
	log.Fatal(http.ListenAndServe(":"+port, nil))
}

func handler(w http.ResponseWriter, r *http.Request) {
	counter.Add(context.Background(), 100)
	fmt.Fprintln(w, "Incremented sidecar_sample_counter metric!")
}

func setupCounter(ctx context.Context) func(context.Context) error {
	serviceName := os.Getenv("K_SERVICE")
	if serviceName == "" {
		serviceName = "sample-cloud-run-app"
	}
	r, err := resource.Merge(
		resource.Default(),
		resource.NewWithAttributes(
			semconv.SchemaURL,
			semconv.ServiceName(serviceName),
		),
	)
	if err != nil {
		log.Fatalf("Error creating resource: %s", err)
	}

	exporter, err := otlpmetricgrpc.New(ctx,
		otlpmetricgrpc.WithInsecure(),
	)
	if err != nil {
		log.Fatalf("Error creating exporter: %s", err)
	}
	provider := metric.NewMeterProvider(
		metric.WithReader(metric.NewPeriodicReader(exporter)),
		metric.WithResource(r),
	)

	meter := provider.Meter("example.com/metrics")
	counter, err = meter.Int64Counter("sidecar-sample-counter")
	if err != nil {
		log.Fatalf("Error creating counter: %s", err)
	}
	return provider.Shutdown
}

• Un Dockerfile que define el entorno operativo del servicio.

run/custom-metrics/Dockerfile

Ver en GitHub Comentarios

FROM golang:1.20 as builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o sample-app

FROM alpine:3
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/sample-app /sample-app
CMD ["/sample-app"]

En la muestra, también se incluyen archivos en el subdirectorio collector para compilar un recopilador de OpenTelemetry personalizado:

• Un archivo de configuración para el recopilador de OpenTelemetry.

  run/custom-metrics/collector/collector-config.yaml

  Ver en GitHub Comentarios
  receivers:
    otlp:
      protocols:
        grpc:
        http:
  
  processors:
    batch:
      # batch metrics before sending to reduce API usage
      send_batch_max_size: 200
      send_batch_size: 200
      timeout: 5s
  
    memory_limiter:
      # drop metrics if memory usage gets too high
      check_interval: 1s
      limit_percentage: 65
      spike_limit_percentage: 20
  
    # automatically detect Cloud Run resource metadata
    resourcedetection:
      detectors: [env, gcp]
      timeout: 2s
      override: false
  
    resource:
      attributes:
        # add instance_id as a resource attribute
      - key: service.instance.id
        from_attribute: faas.id
        action: upsert
        # parse service name from K_SERVICE Cloud Run variable
      - key: service.name
        value: ${env:K_SERVICE}
        action: insert
  
  exporters:
    googlemanagedprometheus: # Note: this is intentionally left blank
  
  extensions:
    health_check:
  
  service:
    extensions: [health_check]
    pipelines:
      metrics:
        receivers: [otlp]
        processors: [batch, memory_limiter, resourcedetection, resource]
        exporters: [googlemanagedprometheus]

• Un Dockerfile que agrupa el archivo de configuración proporcionado en una imagen ascendente de recopilador.

  run/custom-metrics/collector/Dockerfile

  Ver en GitHub Comentarios
  FROM otel/opentelemetry-collector-contrib:0.75.0
  
  COPY collector-config.yaml /etc/otelcol-contrib/config.yaml

Envía el código

El código de envío consta de tres pasos: compilar una imagen de contenedor con Cloud Build, subir la imagen de contenedor a Container Registry y, luego, implementar la imagen de contenedor en Cloud Run.

Para enviar el código, haz lo siguiente:

1. Compila el contenedor de servicio de muestra y publica en Container Registry:

   gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app

   Si la operación se completa de manera correcta, deberías ver un mensaje de ÉXITO con el ID, la hora de creación y el nombre de la imagen. La imagen se almacena en Artifact Registry y puede volver a usarse si así se desea.

2. Compila el contenedor del recopilador y publica en Container Registry:

   gcloud builds submit collector --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics

   Si la operación se completa de manera correcta, deberías ver un mensaje de ÉXITO con el ID, la hora de creación y el nombre de la imagen. La imagen se almacena en Artifact Registry y puede volver a usarse si así se desea.

3. Implementa tu aplicación:

   YAML

   1. Crea un nuevo archivo llamado service.yaml con el siguiente contenido:

      apiVersion: serving.knative.dev/v1
      kind: Service
      metadata:
        name: SERVICE-NAME
        annotations:
          run.googleapis.com/launch-stage: BETA
      spec:
        template:
          metadata:
            annotations:
              run.googleapis.com/container-dependencies: "{app:[collector]}"
          spec:
            containers:
            - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app
              name: app
              ports:
              - containerPort: CONTAINER_PORT
              env:
              - name: "OTEL_EXPORTER_OTLP_ENDPOINT"
                value: "http://localhost:4317"
            - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics
              name: collector
              startupProbe:
                httpGet:
                  path: /
                  port: 13133
      

   2. Reemplaza lo siguiente:
      • CONTAINER_PORT por el puerto en el que escucha el contenedor de entrada de tu servicio. El valor predeterminado es 8080.
      • SERVICE-NAME por cualquier nombre para tu servicio, como custom-metrics-sample-service.

4. Crea el Service nuevo con el siguiente comando:

   gcloud run services replace service.yaml

   Este comando muestra una URL de servicio. Usa esta URL para probar la aplicación de muestra en Prueba.

Prueba

Usa la URL del comando gcloud run en Envía el código para conectarte al servicio y generar algunas métricas de muestra (puedes ejecutar este comando varias veces para generar datos más interesantes):

curl -H \
"Authorization: Bearer $(gcloud auth print-identity-token)" \
SERVICE_URL

Reemplaza SERVICE_URL por la URL de tu servicio.

A continuación, navega al Explorador de métricas dentro de la sección Cloud Monitoring de la consola de Google Cloud y selecciona la métrica sidecar_sample_counter.

También puedes consultar las métricas con PromQL. Por ejemplo, la siguiente consulta filtrará las métricas según el ID de instancia de Cloud Run:

sidecar_sample_counter{instance="INSTANCE_ID"}

Reemplaza INSTANCE_ID por el ID de cualquier instancia de tu servicio (disponible en los registros de la instancia o desde el servidor de metadatos).

Esta consulta genera un gráfico como el que se muestra a continuación:

Limpia

Si creaste un proyecto nuevo para este instructivo, bórralo. Si usaste un proyecto existente y deseas conservarlo sin los cambios que se agregaron en este instructivo, borra los recursos creados para el instructivo.

Borra el proyecto

La manera más fácil de eliminar la facturación es borrar el proyecto que creaste para el instructivo.

Para borrar el proyecto, sigue estos pasos:

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

• Se borra todo en el proyecto. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los ID personalizados de proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID del proyecto personalizado que desees utilizar en el futuro. Para conservar las URL que utilizan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto en lugar de borrar todo el proyecto.

Si planeas explorar varias infraestructuras, instructivos y guías de inicio rápido la reutilización de proyectos puede ayudarte a evitar exceder los límites de las cuotas del proyecto.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Borra los recursos del instructivo

1. Usa este comando para borrar el servicio de Cloud Run que implementaste en este instructivo:

   gcloud run services delete SERVICE-NAME

   En el ejemplo anterior, SERVICE-NAME es el nombre del servicio que elegiste.

   También puedes borrar los servicios de Cloud Run desde la consola de Google Cloud.

2. Quita la configuración de región predeterminada de gcloud que agregaste durante la configuración en el instructivo:

    gcloud config unset run/region
   

3. Quita la configuración del proyecto:

    gcloud config unset project
   

4. Borra otros recursos de Google Cloud que creaste en este instructivo:

   • Borra el repositorio de Docker de Artifact Registry

¿Qué sigue?

En GitHub, se encuentran más ejemplos, incluidos ejemplos de seguimientos y registros.