Escreva métricas OTLP através de um sidecar do OpenTelemetry Collector

Este tutorial mostra como escrever, implementar e chamar um serviço do Cloud Run que comunica métricas OTLP personalizadas ao Google Cloud Managed Service for Prometheus através do coletor OpenTelemetry integrado na Google como um sidecar. Para ver informações acerca do coletor criado pela Google, consulte o artigo Vista geral do coletor OpenTelemetry criado pela Google.

Se tiver um serviço do Cloud Run que comunique métricas do Prometheus, use o sidecar do Prometheus para o Cloud Run.

Configurar predefinições do gcloud

Para configurar o gcloud com predefinições para o seu serviço do Cloud Run:

  1. Defina o projeto predefinido:

    gcloud config set project PROJECT_ID

    Substitua PROJECT_ID pelo nome do projeto que criou para este tutorial.

  2. Configure o gcloud para a região escolhida:

    gcloud config set run/region REGION

    Substitua REGION pela região do Cloud Run suportada à sua escolha.

Localizações do Cloud Run

O Cloud Run é regional, o que significa que a infraestrutura que executa os seus serviços do Cloud Run está localizada numa região específica e é gerida pela Google para estar disponível de forma redundante em todas as zonas dessa região.

O cumprimento dos seus requisitos de latência, disponibilidade ou durabilidade são fatores principais para selecionar a região onde os seus serviços do Cloud Run são executados. Geralmente, pode selecionar a região mais próxima dos seus utilizadores, mas deve considerar a localização dos outros Google Cloudprodutos usados pelo seu serviço do Cloud Run. A utilização Google Cloud de produtos em conjunto em várias localizações pode afetar a latência do seu serviço, bem como o custo.

O Cloud Run está disponível nas seguintes regiões:

Sujeito aos preços de Nível 1

  • asia-east1 (Taiwan)
  • asia-northeast1 (Tóquio)
  • asia-northeast2 (Osaca)
  • asia-south1 (Mumbai, Índia)
  • europe-north1 (Finlândia) ícone de folha Baixo CO2
  • europe-north2 (Estocolmo) ícone de folha Baixo CO2
  • europe-southwest1 (Madrid) ícone de folha Baixo CO2
  • europe-west1 (Bélgica) ícone de folha Baixo CO2
  • europe-west4 (Países Baixos) ícone de folha Baixo CO2
  • europe-west8 (Milão)
  • europe-west9 (Paris) ícone de folha Baixo CO2
  • me-west1 (Telavive)
  • northamerica-south1 (México)
  • us-central1 (Iowa) ícone de folha Baixo CO2
  • us-east1 (Carolina do Sul)
  • us-east4 (Virgínia do Norte)
  • us-east5 (Columbus)
  • us-south1 (Dallas) ícone de folha Baixo CO2
  • us-west1 (Oregão) ícone de folha Baixo CO2

Sujeito aos preços de Nível 2

  • africa-south1 (Joanesburgo)
  • asia-east2 (Hong Kong)
  • asia-northeast3 (Seul, Coreia do Sul)
  • asia-southeast1 (Singapura)
  • asia-southeast2 (Jacarta)
  • asia-south2 (Deli, Índia)
  • australia-southeast1 (Sydney)
  • australia-southeast2 (Melbourne)
  • europe-central2 (Varsóvia, Polónia)
  • europe-west10 (Berlim)
  • europe-west12 (Turim)
  • europe-west2 (Londres, Reino Unido) ícone de folha Baixo CO2
  • europe-west3 (Frankfurt, Alemanha)
  • europe-west6 (Zurique, Suíça) ícone de folha Baixo CO2
  • me-central1 (Doha)
  • me-central2 (Dammam)
  • northamerica-northeast1 (Montreal) ícone de folha Baixo CO2
  • northamerica-northeast2 (Toronto) ícone de folha Baixo CO2
  • southamerica-east1 (São Paulo, Brasil) ícone de folha Baixo CO2
  • southamerica-west1 (Santiago, Chile) ícone de folha Baixo CO2
  • us-west2 (Los Angeles)
  • us-west3 (Salt Lake City)
  • us-west4 (Las Vegas)

Se já criou um serviço do Cloud Run, pode ver a região no painel de controlo do Cloud Run na Google Cloud consola.

Criar um repositório de imagens do Artifact Registry

Crie um repositório Docker do Artifact Registry para alojar a imagem do serviço de exemplo:

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

Substitua o seguinte:

  • PROJECT_ID com o nome do projeto que criou para este tutorial.
  • REGION REGION com a região do Cloud Run suportada à sua escolha.

Obter o exemplo de código

Para obter o exemplo de código para utilização:

  1. Clone o repositório da app de exemplo para a sua máquina local:

    Ir 

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

    Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

  2. Altere para o diretório que contém o código de exemplo do Cloud Run:

    Ir 

    cd golang-samples/run/custom-metrics/

A rever o código

O código deste tutorial consiste no seguinte:

  • Um servidor que processa pedidos recebidos e gera uma métrica denominada sidecar_sample_counter_total.
package main

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

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

var counter metric.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_total 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(
			resource.Default().SchemaURL(),
			semconv.ServiceName(serviceName),
		),
	)
	if err != nil {
		log.Fatalf("Error creating resource: %v", err)
	}

	exporter, err := otlpmetricgrpc.New(ctx,
		otlpmetricgrpc.WithInsecure(),
	)
	if err != nil {
		log.Fatalf("Error creating exporter: %s", err)
	}
	provider := sdkmetric.NewMeterProvider(
		sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exporter)),
		sdkmetric.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
}
  • Um Dockerfile que define o ambiente operacional do serviço.
FROM golang:1.24 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"]

O exemplo também inclui ficheiros no subdiretório collector para criar um coletor personalizado:

  • Um ficheiro de configuração para o coletor.

    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:
    endpoint: 0.0.0.0:13133
service:
  extensions: [health_check]
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch, memory_limiter, resourcedetection, resource]
      exporters: [googlemanagedprometheus]

  • Um Dockerfile que agrupa a configuração fornecida numa imagem do Collector a montante.

    FROM us-docker.pkg.dev/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector/otelcol-google:0.121.0

COPY collector-config.yaml /etc/otelcol-google/config.yaml

Envio do código

O código de envio consiste em três passos: criar uma imagem de contentor com o Cloud Build, carregar a imagem de contentor para o Artifact Registry e implementar a imagem de contentor no Cloud Run.

Para enviar o código:

  1. Crie o contentor de serviço de exemplo e publique-o no Artifact Registry:

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

    Após o êxito, deve ver uma mensagem SUCCESS com o ID, a hora de criação e o nome da imagem. A imagem é armazenada no Artifact Registry e pode ser reutilizada, se quiser.

  2. Crie o contentor do coletor e publique-o no Artifact Registry:

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

    Após o êxito, deve ver uma mensagem SUCCESS com o ID, a hora de criação e o nome da imagem. A imagem é armazenada no Artifact Registry e pode ser reutilizada, se quiser.

  3. Implemente a sua aplicação:

    YAML

    1. Cria um novo ficheiro denominado service.yaml com o seguinte:

      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. Substitua o seguinte:

  4. Crie o novo serviço com o seguinte comando:

    gcloud run services replace service.yaml

    Este comando devolve um URL de serviço. Use este URL para experimentar a aplicação de exemplo em Experimentar.

Experimentar

Usando o URL do comando gcloud run em Envio do código, ligue-se ao serviço para gerar algumas métricas de exemplo (pode executar este comando várias vezes para gerar dados mais interessantes):

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

Substitua SERVICE_URL pelo URL do seu serviço.

Em seguida, navegue para o Explorador de métricas na secção Cloud Monitoring da Google Cloud consola e selecione a métrica sidecar_sample_counter_total.

Métrica personalizada apresentada na IU do explorador de métricas

Também pode consultar as métricas com PromQL. Por exemplo, a consulta abaixo filtra as métricas com base no ID da instância do Cloud Run:

sidecar_sample_counter_total{instance="INSTANCE_ID"}

Substitua INSTANCE_ID pelo ID de qualquer instância do seu serviço (disponível nos registos de instâncias ou no servidor de metadados).

Esta consulta gera um gráfico como o apresentado abaixo:

Métrica personalizada consultada por PromQL