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 da utilização 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.

Objetivos

• Escreva, crie e implemente um serviço no Cloud Run com o coletor OpenTelemetry criado pela Google como um sidecar.
• Gerar métricas personalizadas e comunicá-las ao serviço gerido do Google Cloud para o Prometheus.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

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

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Antes de começar

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.

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

Verify that billing is enabled for your Google Cloud project.

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

Verify that billing is enabled for your Google Cloud project.

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

   Enable the APIs

2. Instale e inicialize a CLI gcloud.
3. Atualize a CLI do Google Cloud: gcloud components update

Funções necessárias

Para receber as autorizações de que precisa para concluir o tutorial, peça ao seu administrador para lhe conceder as seguintes funções da IAM no seu projeto:

• Editor do Cloud Build (roles/cloudbuild.builds.editor)
• Administrador do Cloud Run (roles/run.admin)
• Criar contas de serviço (roles/iam.serviceAccountCreator)
• Project IAM Admin (roles/resourcemanager.projectIamAdmin)
• Monitoring Metric Writer (roles/monitoring.metricWriter)
• Utilizador da conta de serviço (roles/iam.serviceAccountUser)
• Consumidor de utilização do serviço (roles/serviceusage.serviceUsageConsumer)
• Administrador de armazenamento (roles/storage.admin)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Nota: as funções básicas da IAM também podem conter autorizações para concluir o tutorial. Não deve conceder funções básicas num ambiente de produção, mas pode concedê-las num ambiente de desenvolvimento ou de teste.

Tenha também em atenção que a identidade do serviço do Cloud Run precisa da função Gravador de métricas de monitorização (roles/monitoring.metricWriter). A conta de serviço predefinida do Compute Engine pode ter esta função por predefinição, mas pode ter de a adicionar se tiver alterado as respetivas autorizações ou estiver a usar uma conta de serviço diferente.

Configurar predefinições do gcloud

Para configurar o gcloud com as predefinições do 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 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) Baixo CO₂
• europe-north2 (Estocolmo) Baixo CO₂
• europe-southwest1 (Madrid) Baixo CO₂
• europe-west1 (Bélgica) Baixo CO₂
• europe-west4 (Países Baixos) Baixo CO₂
• europe-west8 (Milão)
• europe-west9 (Paris) Baixo CO₂
• me-west1 (Telavive)
• northamerica-south1 (México)
• us-central1 (Iowa) Baixo CO₂
• us-east1 (Carolina do Sul)
• us-east4 (Virgínia do Norte)
• us-east5 (Columbus)
• us-south1 (Dallas) Baixo CO₂
• us-west1 (Oregão) Baixo CO₂

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) Baixo CO₂
• europe-west12 (Turim)
• europe-west2 (Londres, Reino Unido) Baixo CO₂
• europe-west3 (Frankfurt, Alemanha)
• europe-west6 (Zurique, Suíça) Baixo CO₂
• me-central1 (Doha)
• me-central2 (Dammam)
• northamerica-northeast1 (Montreal) Baixo CO₂
• northamerica-northeast2 (Toronto) Baixo CO₂
• southamerica-east1 (São Paulo, Brasil) Baixo CO₂
• southamerica-west1 (Santiago, Chile) Baixo CO₂
• 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.

OK

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.23 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:
      • CONTAINER_PORT com a porta na qual o contentor de entrada do seu serviço está a escutar. Por predefinição, esta opção é 8080.
      • SERVICE-NAME com qualquer nome para o seu serviço, como custom-metrics-sample-service.

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.

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:

Êxito: implementou um serviço do Cloud Run que comunica métricas OTLP personalizadas ao Google Cloud Managed Service for Prometheus.

Limpar

Se criou um novo projeto para este tutorial, elimine o projeto. Se usou um projeto existente e quer mantê-lo sem as alterações adicionadas neste tutorial, elimine os recursos criados para o tutorial.

Eliminar o projeto

A forma mais fácil de eliminar a faturação é eliminar o projeto que criou para o tutorial.

Para eliminar o projeto:

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

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.

Eliminar recursos do tutorial

1. Elimine o serviço do Cloud Run que implementou neste tutorial:

   gcloud run services delete SERVICE-NAME

   Onde SERVICE-NAME é o nome do serviço escolhido.

   Também pode eliminar serviços do Cloud Run a partir da Google Cloud consola.

2. Remova a configuração da região predefinida do gcloud que adicionou durante a configuração do tutorial:

    gcloud config unset run/region
   

3. Remova a configuração do projeto:

    gcloud config unset project
   

4. Elimine outros Google Cloud recursos criados neste tutorial:

   • Elimine o repositório Docker do Artifact Registry

O que se segue?

Estão disponíveis mais exemplos, incluindo exemplos de rastreios e registos, no GitHub.